@pouchy_ai/admin-sdk 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.4.2 — 2026-07-16
+
+The rest of the 0.4.1 drift class — four more response/input shapes that lied
+about the live routes, caught by comparing every method against its
+`/v1/admin` handler. Type + doc fixes only (the client is a generic proxy).
+
+- **`listCredentials`** returns `{ enabled, skills }` (vault status + which
+  skill slugs hold credentials) — the old `{ credentials }` key never existed,
+  so `res.credentials` was always `undefined`. `putCredentials` returns
+  `{ ok, skill, entries }`.
+- **`updateProject`** returns what changed — `{ renamed?, name?, archived? }` —
+  not `{ project: { projectId } }` (that key never existed on PATCH).
+- **`createSchedule.runAt`** is **epoch milliseconds** (number), not an ISO
+  string — the server type-checks `typeof runAt === 'number'` and silently
+  drops a string (your "one-shot" 400s, or becomes recurring if
+  `intervalMinutes` was also set). Input also gains the server's `env?`.
+- **`SecretKey.displayPrefix`** — the stored-key metadata field is
+  `displayPrefix`, not `prefix` (affects `listKeys`/`createKey`/`rotateKey`
+  consumers); `lastUsedAt`/`revokedAt` marked optional as stored.
+- **`getTracesSummary`** now requires `agentId` — the server 400s without it,
+  so the old all-optional signature compiled calls that always fail.
+- **`createChannel`** input gains `env?` + `secret?` (connector credentials) —
+  the closed object literal blocked fields the server accepts, so test-env /
+  secret-bearing connectors were unreachable through the typed method.
+- **`getBilling().billing.periodEnd`** is `string | null` (always present).
+
+Also in this release: `GET /v1/admin/openapi` (the machine-readable spec this
+SDK mirrors) was rewritten against the live routes — it still described the
+pre-0.4.1 contract, so generated clients inherited every bug above.
+
+## 0.4.1 — 2026-07-16
+
+Type-shape corrections — several method signatures had drifted from the live
+`/v1/admin` routes, so a caller trusting the types built request bodies the
+server rejects or read response fields that don't exist. No runtime code
+changed (the client is a generic proxy); these are type + doc fixes.
+
+- **`createSchedule`** now requires `externalUserId` + `prompt` alongside
+  `agentId` and schedules by `intervalMinutes`/`runAt` — the old `{ agentId,
+  cron, prompt? }` was unusable (there is no `cron` field; the server 400s
+  without `externalUserId`). Return is `{ schedule: { id } }` (was
+  `scheduleId`).
+- **`ingestKnowledge`** input is `{ text, name?, kind?, locale? }` — the old
+  `title`/`url` fields were silently ignored by the server.
+- **`getUserWallet`** returns `{ hasWallet, balance: string | null }` (a prose
+  balance string), not `{ balance: number, address }`.
+- **`createKey`** returns `{ key: string, record }` (plaintext token in `key`);
+  the README example logged the nonexistent `key.token`.
+- **`getUsage`** returns `{ usage }` and **`getBilling`** returns `{ billing,
+  ledger }` (both were typed flat); the README `usage.mau` example is fixed.
+- **Channels** methods return `connector`/`connectors` (was `channel`), and
+  `deleteChannel`/`deleteSchedule` return `{ ok }` (was `{ deleted }`).
+- **`listUsers`** params are `{ external_user_id?, external_user_prefix? }`
+  (the old `{ q, limit }` were no-ops; the server hard-caps at 100).
+- **`updateSkill`** generic return is `Record<string, unknown>` (it echoes only
+  the changed knob) — prefer the typed `setSkillRate`/`setSkillDailyCap`/
+  `grantSkill` conveniences, which were already correct.
+
 ## 0.4.0 — 2026-07-13
 
 Full skill-lifecycle parity — the two knobs the dashboard grew (a runaway

package/README.md

@@ -35,10 +35,10 @@ await admin.updateAgent(agent.agentId, { status: 'published' });
 
 // Mint a secret key for your backend to open end-user sessions with
 const { key } = await admin.createKey({ label: 'prod-backend', env: 'live' });
-console.log(key.token); // shown ONCE
+console.log(key); // the plaintext token — shown ONCE
 
 // Read this month's usage
-const usage = await admin.getUsage();
+const { usage } = await admin.getUsage();
 console.log(usage.mau, '/', usage.mauLimit, 'MAU');
 
 // Equip an agent with ANY skill — including a docs-only skill.md that has no

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.4.0";
+export declare const ADMIN_SDK_VERSION = "0.4.2";
 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. */
@@ -32,10 +32,13 @@ export interface SecretKey {
     keyId: string;
     label: string;
     env: Env;
-    prefix: string;
+    /** The key's display prefix (e.g. `pchy_live_ab12…`) — the server never
+     *  returns the plaintext after mint. */
+    displayPrefix: string;
     createdAt: string;
-    lastUsedAt: string | null;
-    revokedAt: string | null;
+    lastUsedAt?: string | null;
+    revokedAt?: string | null;
+    [k: string]: unknown;
 }
 export interface Instance {
     instanceId: string;
@@ -75,6 +78,8 @@ export interface CatalogVoice {
     previewUrl?: string;
     /** Present on tagged rows; filter with listVoices({ gender }). */
     gender?: 'female' | 'male' | 'neutral';
+    /** Present on tagged rows; filter with listVoices({ age }). */
+    age?: 'young' | 'middle_aged' | 'old';
     /** Locales this voice suits; ABSENT = unrestricted. */
     locales?: string[];
 }
@@ -127,15 +132,14 @@ export interface AdminClient {
     listKeys(): Promise<{
         keys: SecretKey[];
     }>;
+    /** Mint a secret key. `key` is the plaintext token, returned ONCE; `record`
+     *  is the stored metadata (no plaintext). */
     createKey(input: {
         label?: string;
         env?: Env;
     }): Promise<{
-        key: {
-            keyId: string;
-            token: string;
-            env: Env;
-        };
+        key: string;
+        record: SecretKey;
     }>;
     revokeKey(keyId: string): Promise<{
         revoked: boolean;
@@ -152,9 +156,11 @@ 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). */
     listUsers(params?: {
-        q?: string;
-        limit?: number;
+        external_user_id?: string;
+        external_user_prefix?: string;
     }): Promise<{
         users: Instance[];
     }>;
@@ -164,9 +170,12 @@ export interface AdminClient {
     deleteUser(instanceId: string): Promise<{
         deleted: boolean;
     }>;
+    /** 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<{
-        balance: number;
-        address: string;
+        hasWallet: boolean;
+        balance: string | null;
     }>;
     getUserTraces(instanceId: string): Promise<{
         traces: unknown[];
@@ -199,10 +208,13 @@ export interface AdminClient {
     listKnowledge(): Promise<{
         docs: unknown[];
     }>;
+    /** Ingest a knowledge doc. `text` is required; `name`/`kind`/`locale` are the
+     *  server's fields (an earlier `title`/`url` shape was silently ignored). */
     ingestKnowledge(input: {
-        title?: string;
-        text?: string;
-        url?: string;
+        text: string;
+        name?: string;
+        kind?: string;
+        locale?: string;
     }): Promise<{
         doc: {
             docId: string;
@@ -228,11 +240,12 @@ export interface AdminClient {
             version: number;
         };
     }>;
-    updateSkill(slug: string, patch: Record<string, unknown>): Promise<{
-        skill: {
-            slug: string;
-        };
-    }>;
+    /** Generic PATCH of a skill's knobs. The response echoes only the knob(s)
+     *  you changed (e.g. `{ ratePerMin }`, `{ maxCallsPerDay, reprovisioned }`,
+     *  `{ freeHttp, grantedDomains, reprovisioned }`) — prefer the typed
+     *  conveniences (setSkillRate / setSkillDailyCap / grantSkill) for a precise
+     *  return type. */
+    updateSkill(slug: string, patch: Record<string, unknown>): Promise<Record<string, unknown>>;
     /** Set a skill's per-minute call budget (1..120; null restores the default). */
     setSkillRate(slug: string, ratePerMin: number | null): Promise<{
         ratePerMin: number | null;
@@ -273,50 +286,69 @@ export interface AdminClient {
     uninstallSkill(slug: string): Promise<{
         deleted: boolean;
     }>;
+    /** Secret-free vault metadata: `enabled` says whether the deployment has a
+     *  vault at all; `skills` lists which skill slugs hold credentials (values
+     *  are never returned by any endpoint). */
     listCredentials(): Promise<{
-        credentials: unknown[];
+        enabled: boolean;
+        skills: unknown[];
     }>;
     putCredentials(input: {
         skill: string;
         credentials: Record<string, unknown>;
     }): Promise<{
         ok: boolean;
+        skill: string;
+        entries: number;
     }>;
     deleteCredentials(skill: string): Promise<{
         deleted: boolean;
     }>;
     listChannels(): Promise<{
-        channels: unknown[];
+        connectors: unknown[];
     }>;
     createChannel(input: {
         type: string;
         agentId: string;
+        env?: Env;
         config?: Record<string, unknown>;
+        /** Connector credentials (bot token, signing secret, …) — stored
+         *  encrypted, never returned. */
+        secret?: Record<string, unknown>;
     }): Promise<{
-        channel: {
+        connector: {
             id: string;
         };
         inboundUrl: string;
     }>;
     getChannel(channelId: string): Promise<{
-        channel: unknown;
+        connector: unknown;
     }>;
     updateChannel(channelId: string, patch: Record<string, unknown>): Promise<{
-        channel: unknown;
+        connector: unknown;
     }>;
     deleteChannel(channelId: string): Promise<{
-        deleted: boolean;
+        ok: boolean;
     }>;
     listSchedules(): Promise<{
         schedules: unknown[];
     }>;
+    /** Create a schedule. `externalUserId` and `prompt` are required alongside
+     *  `agentId`; the schedule fires by `intervalMinutes` (recurring, >=5) or
+     *  `runAt` (one-shot **epoch milliseconds** — an ISO string is silently
+     *  ignored by the server) — there is NO cron field. Returns the stored
+     *  record, whose id lives on `.id`. */
     createSchedule(input: {
         agentId: string;
-        cron: string;
-        prompt?: string;
+        externalUserId: string;
+        prompt: string;
+        intervalMinutes?: number;
+        runAt?: number;
+        env?: Env;
+        deliverTo?: unknown;
     }): Promise<{
         schedule: {
-            scheduleId: string;
+            id: string;
         };
     }>;
     getSchedule(scheduleId: string): Promise<{
@@ -326,7 +358,7 @@ export interface AdminClient {
         schedule: unknown;
     }>;
     deleteSchedule(scheduleId: string): Promise<{
-        deleted: boolean;
+        ok: boolean;
     }>;
     listWebhooks(): Promise<{
         webhooks: unknown[];
@@ -363,14 +395,22 @@ export interface AdminClient {
     testWebhook(webhookId: string): Promise<DeliveryOutcome>;
     /** Manually re-send a recorded delivery's original body, re-signed. */
     redeliverWebhook(deliveryId: string): Promise<DeliveryOutcome>;
-    getUsage(): Promise<MonthUsage>;
+    getUsage(): Promise<{
+        usage: MonthUsage;
+    }>;
     getBilling(): Promise<{
-        plan: string;
-        mauLimit: number;
-        periodEnd?: string;
+        billing: {
+            plan: string;
+            effectivePlan: string;
+            mauLimit: number;
+            periodEnd: string | null;
+        };
+        ledger: unknown;
     }>;
-    getTracesSummary(params?: {
-        agentId?: string;
+    /** Aggregate trace analytics. `agentId` is REQUIRED — the server 400s
+     *  without it. */
+    getTracesSummary(params: {
+        agentId: string;
         sinceHours?: number;
     }): Promise<Record<string, unknown>>;
     /** Recent run rows project-wide (the failed-run browser). */
@@ -382,11 +422,12 @@ export interface AdminClient {
     }): Promise<{
         traces: RecentTrace[];
     }>;
-    /** Enabled platform voices for programmatic provisioning. Filter by gender
-     *  (explicitly tagged rows only) and/or locale (rows listing it, or with no
-     *  locale list = unrestricted). */
+    /** Enabled platform voices for programmatic provisioning. Filter by gender /
+     *  age (explicitly tagged rows only) and/or locale (rows listing it, or with
+     *  no locale list = unrestricted). */
     listVoices(params?: {
         gender?: 'female' | 'male' | 'neutral';
+        age?: 'young' | 'middle_aged' | 'old';
         locale?: string;
     }): Promise<{
         voices: CatalogVoice[];
@@ -403,13 +444,15 @@ export interface AdminClient {
             archived?: boolean;
         };
     }>;
+    /** Rename / archive the project. The response echoes only what changed —
+     *  `{ renamed, name }` and/or `{ archived }` — there is no `project` key. */
     updateProject(patch: {
         name?: string;
         archived?: boolean;
     }): Promise<{
-        project: {
-            projectId: string;
-        };
+        renamed?: boolean;
+        name?: string;
+        archived?: boolean;
     }>;
     /** Escape hatch: call any endpoint the typed methods don't cover yet. */
     request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;

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.4.0';
+export const ADMIN_SDK_VERSION = '0.4.2';
 export const DEFAULT_BASE_URL = 'https://pouchy.ai/v1/admin';
 /** Thrown on any non-2xx response. `status` is the HTTP status; `message` is the
  *  server's `error` string when present. */
@@ -104,7 +104,7 @@ export function createAdminClient(opts) {
         redeliverWebhook: (id) => request('POST', `/webhooks/deliveries/${encodeURIComponent(id)}/redeliver`),
         getUsage: () => request('GET', '/usage'),
         getBilling: () => request('GET', '/billing'),
-        getTracesSummary: (params = {}) => request('GET', `/traces/summary${qs(params)}`),
+        getTracesSummary: (params) => request('GET', `/traces/summary${qs(params)}`),
         getRecentTraces: (params = {}) => request('GET', `/traces/recent${qs({ ...params, errorsOnly: params.errorsOnly ? '1' : undefined })}`),
         listVoices: (params = {}) => request('GET', `/voice-catalog${qs(params)}`),
         getLogs: (params = {}) => request('GET', `/logs${qs(params)}`),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pouchy_ai/admin-sdk",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",