@pouchy_ai/admin-sdk 0.38.0 → 0.39.1

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.39.1 — 2026-09-28
+
+Type corrections. The server's responses did not change; three return types
+described fields it never sent (CR-1101).
+
+- **`importUsers()`: `invalid` is a number**, the count of ids refused for
+  their shape, not `string[]`. Code that called `res.invalid.join()` threw.
+  The type also gains `requested` and `env`, which the server always sent.
+- **`promoteAgent()` returns `{ prodRev, stagingRev }`.** It was typed
+  `{ prodRev, templateRev }`, so `templateRev` was always `undefined`.
+- **`getRecentTraces()` types `degraded`** (`false | 'index' | 'error'`), plus
+  `sinceHours` and `window`. When `degraded` is not `false` the read failed,
+  and an empty `traces` does NOT mean "no runs".
+
+If your code relied on the old types, the compiler will now point at it. Each
+of those reads was already wrong at runtime.
+
+## 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

package/README.md

@@ -465,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.38.0";
+export declare const ADMIN_SDK_VERSION = "0.39.1";
 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
@@ -325,6 +325,22 @@ export interface UsageCreditEnforcement {
      *  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
@@ -601,10 +617,12 @@ export interface AdminClient {
     }>;
     /** Promote the head to production: freezes the head as an archived version and
      *  pins prodRev WITHOUT bumping the rev. Live instances re-resolve on their
-     *  next mint; test instances always run the head. */
+     *  next mint; test instances always run the head. `stagingRev` equals
+     *  `prodRev` right after a promote (0.39.1: this was typed `templateRev`,
+     *  which the server never sent). */
     promoteAgent(agentId: string): Promise<{
         prodRev: number;
-        templateRev: number;
+        stagingRev: number;
     }>;
     listKeys(): Promise<{
         keys: SecretKey[];
@@ -655,24 +673,27 @@ 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[];
     }>;
     /** Batch-import end users from your own id list (idempotent per external id;
-     *  never meters MAU — imported users bill only when they actually mint). */
+     *  never meters MAU — imported users bill only when they actually mint).
+     *  `invalid` is a COUNT of ids refused for their shape (0.39.1: it was typed
+     *  `string[]`, so `res.invalid.join()` threw). */
     importUsers(input: {
         externalUserIds: string[] | string;
         agentId?: string;
         env?: Env;
     }): Promise<{
+        requested: number;
         created: number;
         skipped: number;
-        invalid: string[];
+        env: Env;
+        invalid: number;
     }>;
     /** GDPR data-portability export: registry, character state, memories, contacts. */
     exportUser(instanceId: string): Promise<Record<string, unknown>>;
@@ -1426,13 +1447,21 @@ export interface AdminClient {
         agentId: string;
         sinceHours?: number;
     }): Promise<Record<string, unknown>>;
-    /** Recent run rows project-wide (the failed-run browser). */
+    /** Recent run rows project-wide (the failed-run browser). `degraded` other
+     *  than `false` means the READ failed (`'index'` a missing index, `'error'`
+     *  a fault): an empty `traces` is then NOT "no runs" and must not be shown as
+     *  one (0.39.1: the field was missing from this type). */
     getRecentTraces(params?: {
         agentId?: string;
         sinceHours?: number;
         errorsOnly?: boolean;
         limit?: number;
     }): Promise<{
+        sinceHours: number;
+        window: {
+            sinceMs: number;
+        };
+        degraded: false | 'index' | 'error';
         traces: RecentTrace[];
     }>;
     /** Enabled platform voices for programmatic provisioning. Filter by gender /

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.38.0';
+export const ADMIN_SDK_VERSION = '0.39.1';
 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;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pouchy_ai/admin-sdk",
-	"version": "0.38.0",
+	"version": "0.39.1",
 	"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",