@pouchy_ai/admin-sdk 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 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.1";
 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. */
@@ -127,15 +127,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 +151,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 +165,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 +203,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 +235,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;
@@ -286,37 +294,44 @@ export interface AdminClient {
         deleted: boolean;
     }>;
     listChannels(): Promise<{
-        channels: unknown[];
+        connectors: unknown[];
     }>;
     createChannel(input: {
         type: string;
         agentId: string;
         config?: 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) or `runAt`
+     *  (one-shot ISO time) — 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?: string;
+        deliverTo?: unknown;
     }): Promise<{
         schedule: {
-            scheduleId: string;
+            id: string;
         };
     }>;
     getSchedule(scheduleId: string): Promise<{
@@ -326,7 +341,7 @@ export interface AdminClient {
         schedule: unknown;
     }>;
     deleteSchedule(scheduleId: string): Promise<{
-        deleted: boolean;
+        ok: boolean;
     }>;
     listWebhooks(): Promise<{
         webhooks: unknown[];
@@ -363,11 +378,17 @@ 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;
+        };
+        ledger: unknown;
     }>;
     getTracesSummary(params?: {
         agentId?: string;

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.1';
 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. */

package/package.json

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