@pouchy_ai/admin-sdk 0.36.0 → 0.39.0

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.39.0 — 2026-09-26
+
+- **`getUserWallet()` now types the figures, and a failed read throws.**
+  Admin API 1.18.0 returns `balances` (`{ currency, amount }[]`, decimal
+  strings) and `totalUsd` beside the prose `balance`, typed here as the new
+  exported `UserWallet`. Both fields are optional because an older server does
+  not send them. Before 1.18.0, a wallet service that could not be read
+  answered 200 `{ hasWallet: true, balance: "Could not fetch the wallet balance
+  right now." }`, which looked like a balance. The server now answers 503, so
+  the call throws an `AdminApiError` with `status: 503`; retry it.
+  `balance` is unchanged, so code that displays it keeps working.
+
+## 0.38.0 — 2026-09-25
+
+- **`ADMIN_ERROR_CODES` gains `subscription_exists`** (409). `POST
+  /v1/projects/{id}/billing/checkout` now refuses when the account already pays
+  through a live Stripe subscription. Before, a second checkout opened a SECOND
+  subscription: both billed, and each one's lifecycle events rewrote the
+  account's plan. Upgrade through `POST /v1/projects/{id}/billing/upgrade`
+  instead, which moves the existing subscription to the new price and charges
+  the prorated difference. Additive: the `AdminErrorCode` type was
+  already open to codes newer than the build.
+
+## 0.37.0 — 2026-09-24
+
+- **`getUsage()` now types the `credits` block** the server has returned since
+  admin API 1.14.0: `{ project, account, limit, scope: 'account', enforcement:
+  { armed, plan, verdict, effect } }` (new exported types `UsageCredits` and
+  `UsageCreditEnforcement`). Additive: `usage` is unchanged, and `credits` is
+  optional because a server older than 1.14.0 does not send it.
+
+  `usage.credits / usage.creditLimit` is NOT a headroom ratio — `usage.credits`
+  is this project's slice and `creditLimit` is the ACCOUNT's pooled allowance,
+  so on a multi-project account it understates consumption. Until now the typed
+  client offered only that ratio (reading `res.credits` did not compile), and
+  this README's quickstart printed it. Read `credits.account / credits.limit`
+  instead; `account` is `null` when the pool could not be read, which means
+  unknown, never zero.
+
 ## 0.36.0 — 2026-09-12
 
 - **`deleteChannel` reports what happened to the PROVIDER registration**, and

package/README.md

@@ -38,9 +38,15 @@ const { key } = await admin.createKey({ label: 'prod-backend', env: 'live' });
 console.log(key); // the plaintext token — shown ONCE
 
 // Read this month's usage — MAU, tokens, and the credit meter (all typed)
-const { usage } = await admin.getUsage();
+const { usage, credits } = await admin.getUsage();
 console.log(usage.mau, '/', usage.mauLimit, 'MAU');
-console.log(usage.credits, '/', usage.creditLimit, 'credits');
+// Credits pool across the ACCOUNT's projects: `usage.credits` is only this
+// project's slice, so divide the ACCOUNT figure by the limit, never the slice.
+// `account` is null when the pool could not be read — unknown, not zero.
+if (credits) {
+  console.log(credits.project, 'credits here;', credits.account ?? '?', '/', credits.limit, 'account-wide');
+  console.log('next turn:', credits.enforcement.verdict ?? 'unknown', '—', credits.enforcement.effect);
+}
 // Voice is the priciest metered unit — watch its slice, not just the total
 console.log(usage.creditsVoice, 'of those credits were', usage.voiceCalls, 'voice calls');
 
@@ -417,6 +423,7 @@ type), and is append-only:
 | `event_mismatch` | `signalRun` | the run wants a different key; your event is early or wrong |
 | `one_shot_spent` | `updateSchedule` | the one-shot already fired — create a new schedule instead of re-enabling |
 | `ghost_row` | `updateSchedule` | a legacy fieldless row that can never run — delete it, create a new schedule |
+| `subscription_exists` | `POST /v1/projects/{id}/billing/checkout` (console) | the account already pays through a live subscription — upgrade it with `POST …/billing/upgrade` |
 
 `code` is `undefined` on every failure the server did not tag (400s, 404s, the
 429, transport errors), so always keep a `default` branch. The type has a
@@ -458,7 +465,7 @@ Reads (`GET`) are not covered by that bucket. `retryAfter` is available from
 | Agent versions | `listAgentVersions` · `getAgentVersion` · `diffAgentVersions({ from?, to? })` · `rollbackAgent` · `getAgentPromotion` · `promoteAgent` (staging→prod) |
 | Voices | `listVoices({ gender?, age?, locale? })` — catalog for programmatic voice selection (each `CatalogVoice` carries `age`) |
 | Secret keys | `listKeys` · `createKey` · `revokeKey` · `rotateKey` (24 h grace) |
-| End users | `listUsers({ limit?, cursor? })` (cursor-paginated — the response's `nextCursor` feeds the next page; filter variants: `external_user_id` / `external_user_prefix`) · `setUserSuspended` · `deleteUser` · `getUserWallet` · `getUserTraces` · `importUsers` · `exportUser` · `getUserSessions` · `getUserTurns` |
+| End users | `listUsers({ limit?, cursor? })` (cursor-paginated — the response's `nextCursor` feeds the next page; filter variants: `external_user_id` / `external_user_prefix`) · `setUserSuspended` · `deleteUser` · `getUserWallet` (`balances` / `totalUsd` for the figures; `balance` is prose) · `getUserTraces` · `importUsers` · `exportUser` · `getUserSessions` · `getUserTurns` |
 | Knowledge | `listKnowledge` · `ingestKnowledge` · `ingestKnowledgeFile` (PDF/audio/video/image) · `ingestKnowledgeUrl` (web page) · `searchKnowledge` (recall probe) · `deleteKnowledge` |
 | Skills | `listSkills` · `installSkill` · `updateSkill` · `setSkillRate` · `setSkillDailyCap` · `grantSkill` (free-HTTP) · `setSkillAutoRunTools` (免确认工具 — required to arm an MCP skill on an instance) · `compileSkill` (prose→tools) · `uninstallSkill` · `importAgentPlugin` / `exportAgentPlugin` (Agent Plugins 1.0.0 interop) |
 | Credentials | `listCredentials` · `putCredentials` · `deleteCredentials` |

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.36.0";
+export declare const ADMIN_SDK_VERSION = "0.39.0";
 export declare const DEFAULT_BASE_URL = "https://pouchy.ai/v1/admin";
 /** Deadline for the routes whose server handler declares `maxDuration: 300` —
  *  the server's own ceiling plus headroom, so a client abort can only ever mean
@@ -60,7 +60,7 @@ export interface AdminClientOptions {
  *  published: on this plane the status line never disambiguates, so two of the
  *  durable-run routes answer 409 for two entirely different reasons each, with
  *  different recoveries. `code` is the only thing that tells them apart. */
-export declare const ADMIN_ERROR_CODES: readonly ["story_contract_v2_write_disabled", "story_contract_v3_write_disabled", "story_contract_v4_write_disabled", "has_pins", "pins_unknown", "story_package_limit", "story_package_documents_limit", "episode_history_incomplete", "episode_ended", "idempotency_key_reused", "stale_deliberation", "deliberation_disabled", "deliberation_uncalibrated", "deliberation_not_enabled", "deliberation_candidates_exceeded", "schedule_limit_reached", "one_shot_spent", "ghost_row", "channel_limit_reached", "webhook_limit_reached", "run_limit_reached", "reembed_required", "run_terminal", "run_not_parked", "stale_token", "run_not_waiting", "event_mismatch"];
+export declare const ADMIN_ERROR_CODES: readonly ["story_contract_v2_write_disabled", "story_contract_v3_write_disabled", "story_contract_v4_write_disabled", "has_pins", "pins_unknown", "story_package_limit", "story_package_documents_limit", "episode_history_incomplete", "episode_ended", "idempotency_key_reused", "stale_deliberation", "deliberation_disabled", "deliberation_uncalibrated", "deliberation_not_enabled", "deliberation_candidates_exceeded", "schedule_limit_reached", "one_shot_spent", "ghost_row", "channel_limit_reached", "webhook_limit_reached", "run_limit_reached", "reembed_required", "run_terminal", "run_not_parked", "stale_token", "run_not_waiting", "event_mismatch", "subscription_exists"];
 /** `AdminApiError.code` values. The `(string & {})` arm keeps the type open for
  *  codes newer than this SDK build while preserving autocomplete — same
  *  doctrine as the companion SDK's `CompanionErrorCodeValue`. */
@@ -312,6 +312,52 @@ export interface MonthUsage {
     creditLimit?: number;
     [k: string]: unknown;
 }
+/** What the credit gate would do on the NEXT turn of this account. */
+export interface UsageCreditEnforcement {
+    /** Whether this deployment has the credit gate switched on at all. While
+     *  false nothing is refused or downgraded at the ceiling. */
+    armed: boolean;
+    plan: string;
+    /** Computed on the ACCOUNT total, exactly as the gate does. `null` when the
+     *  pool could not be read — unknown, not `allow`. */
+    verdict: 'allow' | 'downgrade' | 'deny' | null;
+    /** One line saying what `verdict` does (a paid-plan `downgrade` keeps turns
+     *  running on `standard`; a free-plan ceiling refuses NEW sessions). */
+    effect: string;
+}
+/** One end user's wallet, as `getUserWallet` returns it. */
+export interface UserWallet {
+    hasWallet: boolean;
+    /** Human-readable prose, or null when there is no wallet. NOT a number. */
+    balance: string | null;
+    /** Nonzero per-currency balances; `amount` is a decimal string such as
+     *  "5.83", never atomic units. Admin API 1.18.0+, present when
+     *  `hasWallet` is true. */
+    balances?: {
+        currency: string;
+        amount: string;
+    }[];
+    /** USD total (the allowed stablecoins are USD-pegged 1:1). Admin API
+     *  1.18.0+, present when `hasWallet` is true. */
+    totalUsd?: number;
+}
+/** The credit meter with both scopes named (admin API 1.14.0+). Read this, not
+ *  `usage.credits / usage.creditLimit`: that divides THIS project's figure by
+ *  the ACCOUNT's allowance and understates consumption on any multi-project
+ *  account. */
+export interface UsageCredits {
+    /** THIS project's consumption — the same number `usage.credits` carries. */
+    project: number;
+    /** The whole ACCOUNT's consumption: the numerator the gate compares to
+     *  `limit`. `null` means it could not be read — never treat it as zero. */
+    account: number | null;
+    /** The ACCOUNT allowance (same value as `usage.creditLimit`). */
+    limit: number;
+    /** Which pool `limit` governs. Credits pool across the owner's projects, so
+     *  a second project does NOT isolate a workload — a second account does. */
+    scope: 'account';
+    enforcement: UsageCreditEnforcement;
+}
 /** One month of the usage-history series. Unlike `MonthUsage` (the current
  *  month's full meter incl. day buckets and the cap), history rows are the
  *  compact per-month rollup the server keeps for every past month. */
@@ -625,11 +671,10 @@ export interface AdminClient {
     }>;
     /** The instance companion's wallet. `balance` is a human-readable prose
      *  string (e.g. "Wallet balance: … (~$X total)."), or null when the instance
-     *  has no wallet — NOT a number, and there is no address field. */
-    getUserWallet(instanceId: string): Promise<{
-        hasWallet: boolean;
-        balance: string | null;
-    }>;
+     *  has no wallet — NOT a number, and there is no address field. Read
+     *  `balances` / `totalUsd` for the figures (admin API 1.18.0; absent from an
+     *  older server). A wallet service that cannot be read throws a 503. */
+    getUserWallet(instanceId: string): Promise<UserWallet>;
     getUserTraces(instanceId: string): Promise<{
         traces: unknown[];
     }>;
@@ -1362,8 +1407,12 @@ export interface AdminClient {
     testWebhook(webhookId: string): Promise<DeliveryOutcome>;
     /** Manually re-send a recorded delivery's original body, re-signed. */
     redeliverWebhook(deliveryId: string): Promise<DeliveryOutcome>;
+    /** Current-month usage. `credits` (admin API 1.14.0+; absent from an older
+     *  server) is the block to read for headroom — `account / limit` is the
+     *  ratio the gate enforces. */
     getUsage(): Promise<{
         usage: MonthUsage;
+        credits?: UsageCredits;
     }>;
     /** Month-over-month usage series, oldest first; quiet months zero-fill
      *  rather than drop. `scope: 'account'` means the pooled account series —

package/dist/index.js

@@ -8,7 +8,7 @@
 //   import { createAdminClient } from '@pouchy_ai/admin-sdk';
 //   const admin = createAdminClient({ adminKey: process.env.POUCHY_ADMIN_KEY! });
 //   const { agents } = await admin.listAgents();
-export const ADMIN_SDK_VERSION = '0.36.0';
+export const ADMIN_SDK_VERSION = '0.39.0';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1/admin';
 /** Default per-request timeout (ms). A hung upstream otherwise never rejects. */
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -96,7 +96,11 @@ export const ADMIN_ERROR_CODES = [
     'run_not_parked',
     'stale_token',
     'run_not_waiting',
-    'event_mismatch'
+    'event_mismatch',
+    // 0.38.0 — checkout on an account that already pays through a live
+    // subscription. Recovery: POST /v1/projects/{id}/billing/upgrade, which moves
+    // that subscription to the new price instead of opening a second one.
+    'subscription_exists'
 ];
 /** Thrown on any non-2xx response AND on a transport failure that never reached
  *  the server (network / DNS / timeout), which carries `status: 0`. `status` is

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pouchy_ai/admin-sdk",
-	"version": "0.36.0",
+	"version": "0.39.0",
 	"description": "Typed TypeScript client for the Pouchy Admin API \u2014 manage agents, keys, end users, knowledge, skills, channels, schedules, webhooks and credentials headlessly, with a project Admin key.",
 	"type": "module",
 	"license": "SEE LICENSE IN LICENSE",