@pouchy_ai/admin-sdk 0.4.3 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.5.0 — 2026-07-17
+
+Additive: end-user listing pagination.
+
+- **`listUsers` gains cursor pagination**: pass `limit` (clamped 1..100
+  server-side, default 100) and `cursor` (opaque — the previous response's
+  `nextCursor`); the response now carries `nextCursor` while more rows exist.
+  Previously the unfiltered listing was hard-capped at the 100 most recently
+  active instances with no way to reach the tail. The filtered variants
+  (`external_user_id` / `external_user_prefix`) are unchanged and don't
+  paginate. Requires a server deployment serving Admin API >= 1.2.0; older
+  servers ignore the new params and never return `nextCursor` (you just get
+  the old first-100 behavior).
+
+## 0.4.4 — 2026-07-17
+
+Transport-error parity with the JS/python/unity siblings (they got this in
+their last release; admin-sdk was only touched for packaging).
+
+- **Every failure now throws `AdminApiError`.** A network/DNS failure
+  previously escaped as a raw `TypeError: fetch failed`, contradicting the
+  documented "failures throw AdminApiError" contract. Transport errors are
+  wrapped as `AdminApiError(status: 0)`.
+- **Per-request timeout** (`timeoutMs`, default 30s): a hung upstream now
+  rejects with `AdminApiError('request timed out after …', 0)` instead of
+  hanging forever. Uses `AbortSignal.timeout`.
+- **`ADMIN_SDK_VERSION` corrected to match `package.json`** (it had drifted to
+  `0.4.2`, the second time this constant fell behind — now pinned by a test).
+
 ## 0.4.3 — 2026-07-17
 
 - Packaging only: added the `default` export condition beside `import` in the

package/README.md

@@ -61,13 +61,16 @@ console.log(`armed — ${armed.reprovisioned} running instance(s) updated`);
 createAdminClient({
   adminKey: 'pchy_admin_…',   // required
   baseUrl: 'https://pouchy.ai/v1/admin', // optional (self-host / staging)
-  fetch: myFetch              // optional (Node <18, or tests)
+  fetch: myFetch,             // optional (Node <18, or tests)
+  timeoutMs: 30_000           // optional per-request timeout (default 30s)
 });
 ```
 
 ## Errors
 
-Every method throws `AdminApiError` on a non-2xx response:
+Every method throws `AdminApiError` on failure — a non-2xx response, a network
+error, or a timeout. Transport failures (network/DNS/timeout) carry
+`status: 0`; HTTP errors carry the real status and the server's `error` string:
 
 ```ts
 import { AdminApiError } from '@pouchy_ai/admin-sdk';
@@ -85,7 +88,7 @@ try {
 | Agents | `listAgents` · `createAgent` · `getAgent` · `updateAgent` · `deleteAgent` |
 | 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` · `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` · `getUserTraces` · `importUsers` · `exportUser` · `getUserSessions` · `getUserTurns` |
 | Knowledge | `listKnowledge` · `ingestKnowledge` · `deleteKnowledge` |
 | Skills | `listSkills` · `installSkill` · `updateSkill` · `setSkillRate` · `setSkillDailyCap` · `grantSkill` (free-HTTP) · `compileSkill` (prose→tools) · `uninstallSkill` |
 | Credentials | `listCredentials` · `putCredentials` · `deleteCredentials` |

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.4.2";
+export declare const ADMIN_SDK_VERSION = "0.5.0";
 export declare const DEFAULT_BASE_URL = "https://pouchy.ai/v1/admin";
 export interface AdminClientOptions {
     /** A project Admin key (`pchy_admin_…`) from the dashboard Admin Keys page. */
@@ -7,6 +7,9 @@ export interface AdminClientOptions {
     baseUrl?: string;
     /** Inject a fetch impl (Node <18, or for tests). Default global fetch. */
     fetch?: typeof fetch;
+    /** Per-request timeout in ms (default 30s). A request that outlives it
+     *  rejects with an AdminApiError(status 0). */
+    timeoutMs?: number;
 }
 /** Thrown on any non-2xx response. `status` is the HTTP status; `message` is the
  *  server's `error` string when present. */
@@ -156,13 +159,19 @@ export interface AdminClient {
             graceUntil: string | null;
         };
     }>;
-    /** List end-user instances. Filter by exact external id or by prefix (the
-     *  server ignores any other query param and hard-caps the page at 100). */
+    /** List end-user instances. Filter by exact external id or by prefix, or
+     *  page the full listing: `limit` (clamped 1..100 server-side, default 100)
+     *  + `cursor` (opaque — pass back the previous response's `nextCursor`).
+     *  `nextCursor` is present while more rows exist; the filtered variants
+     *  don't paginate. */
     listUsers(params?: {
         external_user_id?: string;
         external_user_prefix?: string;
+        limit?: number;
+        cursor?: string;
     }): Promise<{
         users: Instance[];
+        nextCursor?: string;
     }>;
     setUserSuspended(instanceId: string, suspended: boolean): Promise<{
         suspended: boolean;

package/dist/index.js

@@ -8,8 +8,10 @@
 //   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.4.2';
+export const ADMIN_SDK_VERSION = '0.5.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;
 /** Thrown on any non-2xx response. `status` is the HTTP status; `message` is the
  *  server's `error` string when present. */
 export class AdminApiError extends Error {
@@ -35,15 +37,28 @@ export function createAdminClient(opts) {
     const f = opts.fetch ?? globalThis.fetch;
     if (!f)
         throw new AdminApiError('no fetch available — pass opts.fetch on Node <18', 0);
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     async function request(method, path, body) {
-        const res = await f(base + path, {
-            method,
-            headers: {
-                authorization: `Bearer ${opts.adminKey}`,
-                ...(body !== undefined ? { 'content-type': 'application/json' } : {})
-            },
-            body: body !== undefined ? JSON.stringify(body) : undefined
-        });
+        // Every failure surfaces as an AdminApiError (the doc contract): a
+        // network/DNS error or a timeout would otherwise escape as a raw
+        // `TypeError: fetch failed` / AbortError. Status 0 = never reached the
+        // server (parity with the JS/python SDKs' transport-error wrapping).
+        let res;
+        try {
+            res = await f(base + path, {
+                method,
+                headers: {
+                    authorization: `Bearer ${opts.adminKey}`,
+                    ...(body !== undefined ? { 'content-type': 'application/json' } : {})
+                },
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: AbortSignal.timeout(timeoutMs)
+            });
+        }
+        catch (e) {
+            const isTimeout = e instanceof Error && (e.name === 'TimeoutError' || e.name === 'AbortError');
+            throw new AdminApiError(isTimeout ? `request timed out after ${timeoutMs}ms` : `network error: ${e instanceof Error ? e.message : String(e)}`, 0);
+        }
         const data = (await res.json().catch(() => ({})));
         if (!res.ok)
             throw new AdminApiError(data?.error ?? `HTTP ${res.status}`, res.status);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pouchy_ai/admin-sdk",
-  "version": "0.4.3",
-  "description": "Typed TypeScript client for the Pouchy Admin API — manage agents, keys, end users, knowledge, skills, channels, schedules, webhooks and credentials headlessly, with a project Admin key.",
+  "version": "0.5.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",
   "homepage": "https://pouchy.ai/sdk",
@@ -10,7 +10,9 @@
     "url": "https://github.com/oviswang/Pouchy.git",
     "directory": "packages/admin-sdk"
   },
-  "bugs": { "email": "support@pouchy.ai" },
+  "bugs": {
+    "email": "support@pouchy.ai"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -20,13 +22,28 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": ["dist", "README.md", "CHANGELOG.md", "LICENSE"],
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "sideEffects": false,
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build"
   },
-  "devDependencies": { "typescript": "^5.5.0" },
-  "keywords": ["pouchy", "admin", "api", "sdk", "agent-platform"],
-  "publishConfig": { "access": "public" }
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  },
+  "keywords": [
+    "pouchy",
+    "admin",
+    "api",
+    "sdk",
+    "agent-platform"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
 }