Migration: 0.3.x → 0.4.0

Mirrors the canonical RELEASE_NOTES_0.4.0.md — update both together.

mixpanel_data 0.4.0 ships a complete rewrite of the auth subsystem (single TOML schema, three first-class account types, a single resolver, fluent in-session switching). It is a hard break from 0.3.x: legacy ~/.mp/config.toml files no longer load and there is no auto-migration path. Recovery is a wipe + re-add (5 commands).

Recovery recipe

# 1. Back up your existing config (it will become unreadable on 0.4.x)
cp ~/.mp/config.toml ~/.mp/config.toml.0.3-backup
rm ~/.mp/config.toml

# 2. Re-add accounts

# Service account (default_project is required at add-time)
mp account add team --type service_account \
  --username "sa_abc123..." --project 12345 --region us
# (will prompt for the secret with hidden input)

# OAuth browser
mp account add personal --type oauth_browser --region us
mp account login personal     # opens browser for PKCE flow

Confirm the new state:

mp session              # shows resolved account / project / workspace
mp account list         # shows all configured accounts
mp project list         # shows accessible projects via /me

Breaking Changes

Configuration schema

• No legacy v1 / v2 detection. Configs written by 0.3.x raise a Pydantic validation error on first load. There is no mp config convert — recovery is a wipe + re-add via mp account add ....
• [active].project is rejected (the project axis lives on the account itself as default_project). Sessions persist [active].account + [active].workspace only.
• v1 / v2 OAuth token files at ~/.mp/oauth/tokens_{region}.json are no longer read; tokens now live at ~/.mp/accounts/{name}/tokens.json.

CLI command groups

The following entire command groups were deleted (no backwards-compat shim, no deprecation banner):

Removed	Replacement
mp auth list/add/remove/switch/show/test/login/logout	mp account list/add/remove/use/show/test/login/logout
mp auth migrate	(no replacement — schema break, wipe ~/.mp/config.toml)
mp auth cowork-setup	mp account export-bridge --to PATH
mp auth cowork-status	mp session --bridge
mp auth cowork-teardown	mp account remove-bridge [--at PATH]
mp projects list/use/show	mp project list/use/show
mp workspaces list/use/show	mp workspace list/use/show
mp context show	mp session
mp config convert	(descoped — see above)

CLI globals

Removed	Replacement
--credential	--account (-a)
--workspace-id	--workspace (-w)
(added)	--project (-p)
(added)	--target (-t) — apply a saved target

--target is mutually exclusive with --account/--project/--workspace.

Public Python API

The following names were deleted from mixpanel_data:

Removed	Notes
Credentials, AuthMethod	Internal shim types — use Workspace(...) directly.
AccountInfo, CredentialInfo, ProjectAlias	Replaced by AccountSummary / Account (discriminated union) / Target.
MigrationResult, ActiveContext	Migration descoped; active state lives in Session / ActiveSession.
AuthCredential, CredentialType, ProjectContext, ResolvedSession	v2 internals — see Account + Session instead.
Workspace.set_workspace_id(...)	Workspace.use(workspace=N)
Workspace.switch_project(...)	Workspace.use(project=P)
Workspace.switch_workspace(...)	Workspace.use(workspace=N)
Workspace.current_credential()	Workspace.account (read-only property)
Workspace.current_project()	Workspace.project (read-only property)
Workspace.test_credentials(...)	mp.accounts.test(NAME) returning AccountTestResult

The following names were added as part of the v3 surface and are canonical going forward (re-exported from the top-level mixpanel_data namespace):

• Discriminated account union: Account, AccountType, ServiceAccount, OAuthBrowserAccount, OAuthTokenAccount, Region
• Session axes: Session, Project, WorkspaceRef
• Result types: AccountSummary, AccountTestResult, OAuthLoginResult, Target
• Exceptions: AccountInUseError, ProjectNotFoundError, WorkspaceScopeError
• Functional namespaces: mp.accounts, mp.session, mp.targets

The following low-level types are available only from mixpanel_data.auth_types:

• Active session snapshot: ActiveSession
• Token plumbing: OAuthTokens, OAuthClientInfo, TokenResolver, OnDiskTokenResolver
• Cowork bridge: BridgeFile, load_bridge

Token & config file moves

Was	Now
~/.mp/oauth/tokens_{region}.json	~/.mp/accounts/{name}/tokens.json (per-account)
~/.mp/oauth/me_{region}.json	~/.mp/accounts/{name}/me.json (per-account)
~/.mp/oauth/client_{region}.json	unchanged (still shared per region)
[default] + [accounts.X].project_id	[active].account + [accounts.X].default_project

The legacy ~/.mp/oauth/tokens_*.json and ~/.mp/oauth/me_*.json files are left untouched on disk — delete them manually if you want a clean slate.

Plugin

• The mixpanel-data Claude Code plugin manifest version bumps from 4.1.0 → 5.0.0.
• The /mixpanel-data:auth slash command re-routes to the new subcommand vocabulary (account / project / workspace / target / session / bridge). Old verbs (status / list / switch / migrate / context / cowork-setup) are gone.
• auth_manager.py JSON shape is now stable with schema_version: 1 and a discriminated state field (ok | needs_account | needs_project | error).

Pin mixpanel-data >= 5.0.0 so the slash command consumes the new JSON contract.

What stayed the same

• Region defaults (us, eu, in)
• Output formats (json, jsonl, table, csv, plain)
• Discovery / live query / streaming / entity CRUD APIs (no auth-only methods affected — Workspace.events(), .segmentation(), .list_dashboards(), etc. are unchanged)
• All entity CRUD on dashboards, reports, cohorts, flags, experiments, alerts, annotations, webhooks, lexicon, drop filters, custom properties, custom events, lookup tables, schemas

Next Steps

• Configuration — Full setup walkthrough with the new commands and config schema
• API → Auth — Python API reference for the v3 surface
• CLI Reference — Full command and global-options reference

Copy markdown