API cleanup (Batch 1): mirror gateway billing/account route renames in SDK/CLI/MCP

[MajorTal]

API cleanup (Batch 1): mirror gateway billing/account route renames in SDK/CLI/MCP

Part of a pre-launch API-consistency cleanup happening in run402-private. Several gateway billing/account routes are being renamed for consistency. Because these are admin routes they're excluded from openapi.json/llms-full.txt, but they are baked into the published @run402/sdk, run402-mcp, the CLI, and the sync.test.ts cross-surface contract here — so this repo must mirror the renames in lockstep, and republish.

⚠️ Coordination: the gateway-side change for item 1 is implemented on branch api-cleanup-batch-1 in run402-private (not yet merged/deployed). Do not deploy the gateway rename until this repo's SDK/CLI/MCP changes are merged + published, otherwise published clients calling the old path will 404.

1. Shipping now (gateway side done): lease-perpetual fold-in

POST /billing-accounts/v1/admin/:id/lease-perpetual → POST /billing/v1/admin/accounts/:account_id/lease-perpetual
(The one-route /billing-accounts/v1/* namespace is retired; the toggle joins the /billing/v1/admin/accounts/* family next to credit/debit/set-tier.)

Files to update here:

• sdk/src/namespaces/admin.ts — setLeasePerpetual() path (~L435/442)
• sdk/src/namespaces/admin.test.ts — URL assertions (~L214/229/256)
• src/index.ts — MCP tool admin_set_lease_perpetual description "Calls POST …" (~L690)
• CLI command admin:lease-perpetual — URL builder
• cli-e2e.test.mjs — mock URL match (~L1883/1908)
• sync.test.ts — endpoint registry entry (~L374)
• Republish @run402/sdk + run402-mcp; coordinate timing with the gateway deploy

2. Planned next (gateway shapes pending final design in run402-private)

These are the remaining Batch 1 consolidations. Listed so this repo has the full picture; exact target paths will be confirmed before the gateway change lands, then this issue (or a follow-up) will get the precise mapping.

• Admin account routes keyed by :account_id instead of :wallet (credit, debit, set-tier) → /billing/v1/admin/accounts/:account_id/{credit,debit,set-tier}
• Public account addressing: /billing/v1/accounts/:id unified to :account_id (UUID) + ?wallet=/?email= lookup (today :id means wallet or email on GET but a UUID on link-wallet)
• Tier mutation consolidated (today 3 write paths across 2 namespaces: /tiers/v1/:tier, /billing/v1/tiers/:tier/checkout, /billing/v1/admin/accounts/:wallet/set-tier)
• Checkout consolidated (today 3 shapes: /billing/v1/checkouts, /billing/v1/tiers/:tier/checkout, /billing/v1/email-packs/checkout)

Naming convention adopted (for reference)

• "admin" = platform staff (us); "operator" = the human customer who owns a billing account. Platform-admin actions stay under /<resource>/v1/admin/*.
• Path params: resource-qualified snake_case (:account_id), not bare :id.

cc: tracking the gateway side in run402-private branch api-cleanup-batch-1.

[MajorTal]

Piece 2 locked (gateway side merged into api-cleanup-batch-1)

The admin account routes are now keyed by :account_id (UUID) instead of :wallet. Exact SDK/CLI/MCP mappings to mirror:

Old	New
POST /billing/v1/admin/accounts/:wallet/credit	POST /billing/v1/admin/accounts/:account_id/credit
POST /billing/v1/admin/accounts/:wallet/debit	POST /billing/v1/admin/accounts/:account_id/debit
POST /billing/v1/admin/accounts/:wallet/set-tier	POST /billing/v1/admin/accounts/:account_id/set-tier

Response changes: credit/debit responses drop the wallet field (kept billing_account_id, available_usd_micros, ledger_entry_id); set-tier response drops wallet (kept billing_account_id, tier, action, previous_tier, lease_started_at, lease_expires_at). The path param is a billing-account UUID, validated server-side. These now work on email-only / multi-wallet accounts.

Pieces 3–5 (public /billing/v1/accounts/:id addressing, tier, checkout) still in progress — mappings to follow as each lands.

[MajorTal]

Piece 1 shipped ✅ — published, gateway rename now safe to deploy

The lease-perpetual fold-in is merged and published.

• Merged: fix(admin): mirror gateway lease-perpetual route rename (SDK + MCP) #431 → main
• Published (lockstep): run402-mcp, run402, @run402/sdk all at v2.36.0 (OIDC Trusted Publisher, SLSA provenance attestations confirmed). Release: https://github.com/kychee-com/run402/releases/tag/v2.36.0
• Path: POST /billing-accounts/v1/admin/:id/lease-perpetual → POST /billing/v1/admin/accounts/:account_id/lease-perpetual

Updated the SDK request path (the only place that builds the URL), the MCP tool description, and the SDK / cli-e2e / sync cross-surface assertions. The run402 admin lease-perpetual CLI/OpenClaw command is a thin shim over the SDK and references only the command name (unchanged), so the checklist's "CLI URL builder" item was a no-op.

✅ Coordination gate cleared: published clients now call the new path, so the gateway rename on api-cleanup-batch-1 is safe to merge/deploy.

---

Piece 2 (admin credit / debit / set-tier keyed by :account_id): no action needed in this repo. Those are gateway-internal admin routes — they have no published-client surface in the SDK/CLI/MCP (verified: no credit/debit/admin-set-tier methods or commands exist here; the only set_tier is the public POST /tiers/v1/:tier flow, which is piece 4 territory). Nothing to mirror unless a future batch exposes them as client methods.

Pieces 3–5: standing by for the gateway path mappings.