@pouchy_ai/admin-sdk 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 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
+guard + the prose→tools upgrade) are now typed on the client:
+
+- **`setSkillDailyCap(slug, maxCallsPerDay)`** — the opt-in daily call ceiling
+  (`PATCH /v1/admin/skills/{slug}` with `{ maxCallsPerDay }`, 1..20000, null to
+  clear): max HTTP calls per rolling 24h for a skill, a runaway guard for
+  autonomous outbound the per-minute cap doesn't cover. Returns `reprovisioned`.
+- **`compileSkill(slug)`** — compile a docs-only skill's prose into declared
+  `http` tools (`POST /v1/admin/skills/{slug}/compile`): a one-shot LLM proposes
+  tools bound to the skill's allowlist, re-installed (reversible via rollback).
+  Returns `{ skill, toolNames, warnings }`.
+- (Also fixes the `ADMIN_SDK_VERSION` constant, which had drifted to `0.2.0`.)
+
 ## 0.3.0 — 2026-07-13
 
 Skill-config parity — a docs-only skill (no `tools:` block) can now be

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
@@ -87,7 +87,7 @@ try {
 | Secret keys | `listKeys` · `createKey` · `revokeKey` · `rotateKey` (24 h grace) |
 | End users | `listUsers` · `setUserSuspended` · `deleteUser` · `getUserWallet` · `getUserTraces` · `importUsers` · `exportUser` · `getUserSessions` · `getUserTurns` |
 | Knowledge | `listKnowledge` · `ingestKnowledge` · `deleteKnowledge` |
-| Skills | `listSkills` · `installSkill` · `updateSkill` · `setSkillRate` · `grantSkill` (free-HTTP) · `uninstallSkill` |
+| Skills | `listSkills` · `installSkill` · `updateSkill` · `setSkillRate` · `setSkillDailyCap` · `grantSkill` (free-HTTP) · `compileSkill` (prose→tools) · `uninstallSkill` |
 | Credentials | `listCredentials` · `putCredentials` · `deleteCredentials` |
 | Channels | `listChannels` · `createChannel` · `getChannel` · `updateChannel` · `deleteChannel` |
 | Schedules | `listSchedules` · `createSchedule` · `getSchedule` · `updateSchedule` · `deleteSchedule` |

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.2.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,15 +235,35 @@ 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;
     }>;
+    /** Set a skill's opt-in daily call ceiling — max HTTP calls per rolling 24h
+     *  (1..20000; null clears it, leaving only the per-minute cap). A runaway
+     *  guard for autonomous outbound. Re-pushes the def to running instances. */
+    setSkillDailyCap(slug: string, maxCallsPerDay: number | null): Promise<{
+        maxCallsPerDay: number | null;
+        reprovisioned: number;
+    }>;
+    /** Compile a docs-only skill's prose (curl snippets / endpoint tables) into
+     *  declared `http` tools via a one-shot LLM, then re-install the result
+     *  (safety gate + version archive → reversible via rollback). Each tool is
+     *  bound to the skill's allowlist; `warnings` lists any dropped by a bad host
+     *  or shape. Turns a free-HTTP skill into structured `run_skill` tools. */
+    compileSkill(slug: string): Promise<{
+        skill: {
+            slug: string;
+        };
+        toolNames: string[];
+        warnings: string[];
+    }>;
     /** Free-HTTP grant (universal import): let the agent drive this skill's API
      *  from its prose body via `http_request`, bounded to the manifest's
      *  `allowed_domains` ∪ `grantedDomains`. This is how a docs-only skill
@@ -267,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<{
@@ -307,7 +341,7 @@ export interface AdminClient {
         schedule: unknown;
     }>;
     deleteSchedule(scheduleId: string): Promise<{
-        deleted: boolean;
+        ok: boolean;
     }>;
     listWebhooks(): Promise<{
         webhooks: unknown[];
@@ -344,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.2.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. */
@@ -75,6 +75,8 @@ export function createAdminClient(opts) {
         installSkill: (input) => request('POST', '/skills', input),
         updateSkill: (slug, patch) => request('PATCH', `/skills/${encodeURIComponent(slug)}`, patch),
         setSkillRate: (slug, ratePerMin) => request('PATCH', `/skills/${encodeURIComponent(slug)}`, { ratePerMin }),
+        setSkillDailyCap: (slug, maxCallsPerDay) => request('PATCH', `/skills/${encodeURIComponent(slug)}`, { maxCallsPerDay }),
+        compileSkill: (slug) => request('POST', `/skills/${encodeURIComponent(slug)}/compile`, {}),
         grantSkill: (slug, grant) => request('PATCH', `/skills/${encodeURIComponent(slug)}`, {
             freeHttp: grant.freeHttp,
             grantedDomains: grant.grantedDomains ?? []

package/package.json

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