@pouchy_ai/admin-sdk 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.3.0 — 2026-07-13
+
+Skill-config parity — a docs-only skill (no `tools:` block) can now be
+installed AND armed entirely via the API, no dashboard step:
+
+- **`grantSkill(slug, { freeHttp, grantedDomains? })`** — the free-HTTP grant
+  (`PATCH /v1/admin/skills/{slug}`): let the agent drive a skill's API from its
+  prose body via `http_request`, bounded to the manifest's `allowed_domains` ∪
+  `grantedDomains`. The new def is re-pushed to running instances; the result's
+  `reprovisioned` reports how many picked it up. Full flow: `installSkill` →
+  `updateAgent(id, { skills: [...] })` → `grantSkill`.
+- **`setSkillRate(slug, ratePerMin)`** — typed convenience over `updateSkill`
+  for the per-minute call budget (1..120, or null to restore the default).
+
+## 0.2.0 — 2026-07-11
+
+Provisioning-parity release (driven by integrator feedback — programmatic
+per-member agent provisioning with no human in the loop):
+
+- **`listVoices({ gender?, locale? })`** — the platform voice catalog on the
+  admin key (`GET /v1/admin/voice-catalog`). Rows carry `provider` (which agent
+  `voices` slot the `providerVoiceId` goes in), plus `gender` / `locales` tags
+  for auto-selection. Gender filter matches explicitly tagged rows; locale
+  filter matches rows listing it (no locale list = unrestricted).
+- **`rotateKey(keyId, { graceHours? })`** — secret-key rotation with a grace
+  window (default 24 h; the old key keeps verifying while you swap envs).
+- **`testWebhook(webhookId)`** / **`redeliverWebhook(deliveryId)`** — send a
+  test event; manually re-send a recorded delivery's original body.
+- **`updateWebhook(webhookId, { url?, events? })`** — edit an endpoint in
+  place (keeps the signing secret + delivery history) — and
+  **`rotateWebhookSecret(webhookId)`** — roll the signing secret (shown once).
+- **`getRecentTraces({ agentId?, sinceHours?, errorsOnly?, limit? })`** — the
+  project-wide failed-run browser.
+- **`importUsers({ externalUserIds, agentId?, env? })`** — batch instance
+  import (idempotent per external id; never meters MAU).
+- **`exportUser(instanceId)`** — GDPR data-portability export.
+- **`getUserSessions(instanceId)`** / **`getUserTurns(instanceId, sessionId)`**
+  — session list + turn-log transcripts.
+- `AuditRow.actor` — audit-log rows now attribute WHO acted.
+
 ## 0.1.0
 
 Initial release. Typed, zero-dependency client for the Pouchy Admin API

package/README.md

@@ -40,6 +40,19 @@ console.log(key.token); // shown ONCE
 // Read this month's usage
 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
+// `tools:` block — entirely via the API:
+const { skill } = await admin.installSkill({
+  md: '---\nname: echo-probe\nallowed_domains:\n  - postman-echo.com\n---\nGET https://postman-echo.com/get echoes the request.'
+});
+await admin.updateAgent(agent.agentId, { skills: [skill.slug] }); // attach to the agent
+const armed = await admin.grantSkill(skill.slug, {
+  freeHttp: true,
+  grantedDomains: ['postman-echo.com'] // unioned with the manifest's allowed_domains
+});
+console.log(`armed — ${armed.reprovisioned} running instance(s) updated`);
+// The agent can now drive the API from the skill's prose via http_request.
 ```
 
 ## Options
@@ -70,15 +83,16 @@ try {
 | Area | Methods |
 | --- | --- |
 | Agents | `listAgents` · `createAgent` · `getAgent` · `updateAgent` · `deleteAgent` |
-| Secret keys | `listKeys` · `createKey` · `revokeKey` |
-| End users | `listUsers` · `setUserSuspended` · `deleteUser` · `getUserWallet` · `getUserTraces` |
+| Voices | `listVoices({ gender?, locale? })` — catalog for programmatic voice selection |
+| 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` · `uninstallSkill` |
+| Skills | `listSkills` · `installSkill` · `updateSkill` · `setSkillRate` · `grantSkill` (free-HTTP) · `uninstallSkill` |
 | Credentials | `listCredentials` · `putCredentials` · `deleteCredentials` |
 | Channels | `listChannels` · `createChannel` · `getChannel` · `updateChannel` · `deleteChannel` |
 | Schedules | `listSchedules` · `createSchedule` · `getSchedule` · `updateSchedule` · `deleteSchedule` |
-| Webhooks | `listWebhooks` · `createWebhook` · `deleteWebhook` |
-| Reporting | `getUsage` · `getBilling` · `getTracesSummary` · `getLogs` · `getProject` · `updateProject` |
+| Webhooks | `listWebhooks` · `createWebhook` · `updateWebhook` · `rotateWebhookSecret` · `deleteWebhook` · `testWebhook` · `redeliverWebhook` |
+| Reporting | `getUsage` · `getBilling` · `getTracesSummary` · `getRecentTraces` · `getLogs` · `getProject` · `updateProject` |
 | Escape hatch | `request(method, path, body?)` — any endpoint not yet typed |
 
 ## OpenAPI

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.1.0";
+export declare const ADMIN_SDK_VERSION = "0.2.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. */
@@ -58,6 +58,49 @@ export interface AuditRow {
     at: string;
     type: string;
     detail: Record<string, unknown>;
+    /** Who performed the action (member email/uid or `admin_key:{keyId}`);
+     *  absent on system-originated entries. */
+    actor?: string;
+}
+export interface CatalogVoice {
+    /** Catalog id (std_… / hd_…) — display/reference only. */
+    id: string;
+    name: string;
+    desc: string;
+    tier: 'standard' | 'premium';
+    /** Which agent `voices` slot the providerVoiceId goes in. */
+    provider: 'openAI' | 'elevenLabs';
+    /** The value to write into that slot. */
+    providerVoiceId: string;
+    previewUrl?: string;
+    /** Present on tagged rows; filter with listVoices({ gender }). */
+    gender?: 'female' | 'male' | 'neutral';
+    /** Locales this voice suits; ABSENT = unrestricted. */
+    locales?: string[];
+}
+export interface RecentTrace {
+    traceId: string;
+    sessionId: string;
+    agentId?: string;
+    instanceId?: string;
+    trigger: string;
+    startedAt: number;
+    durationMs: number;
+    tokensIn: number;
+    tokensOut: number;
+    tokensCached: number;
+    toolCount: number;
+    ok: boolean;
+    spans: {
+        name: string;
+        kind: string;
+        ms: number;
+    }[];
+}
+export interface DeliveryOutcome {
+    ok: boolean;
+    status?: number;
+    error?: string;
 }
 /** The Admin API client. Every method returns the parsed JSON body; failures
  *  throw AdminApiError. */
@@ -97,6 +140,18 @@ export interface AdminClient {
     revokeKey(keyId: string): Promise<{
         revoked: boolean;
     }>;
+    /** Rotate a secret key: mints the replacement (plaintext returned ONCE);
+     *  the old key keeps verifying for the grace window (default 24 h). */
+    rotateKey(keyId: string, opts?: {
+        graceHours?: number;
+    }): Promise<{
+        key: string;
+        record: SecretKey;
+        old: {
+            keyId: string;
+            graceUntil: string | null;
+        };
+    }>;
     listUsers(params?: {
         q?: string;
         limit?: number;
@@ -116,6 +171,31 @@ export interface AdminClient {
     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). */
+    importUsers(input: {
+        externalUserIds: string[] | string;
+        agentId?: string;
+        env?: Env;
+    }): Promise<{
+        created: number;
+        skipped: number;
+        invalid: string[];
+    }>;
+    /** GDPR data-portability export: registry, character state, memories, contacts. */
+    exportUser(instanceId: string): Promise<Record<string, unknown>>;
+    /** The instance's companion sessions, most recently active first. */
+    getUserSessions(instanceId: string, params?: {
+        limit?: number;
+    }): Promise<{
+        sessions: unknown[];
+    }>;
+    /** A session's turn log (oldest first, with per-turn trace meta). */
+    getUserTurns(instanceId: string, sessionId: string, params?: {
+        limit?: number;
+    }): Promise<{
+        turns: unknown[];
+    }>;
     listKnowledge(): Promise<{
         docs: unknown[];
     }>;
@@ -153,6 +233,24 @@ export interface AdminClient {
             slug: string;
         };
     }>;
+    /** Set a skill's per-minute call budget (1..120; null restores the default). */
+    setSkillRate(slug: string, ratePerMin: number | null): Promise<{
+        ratePerMin: number | null;
+    }>;
+    /** 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
+     *  (no `tools:` block) becomes runnable — install it, attach it to an agent
+     *  (`updateAgent(id, { skills: [...] })`), then grant it here. The new def is
+     *  re-pushed to running instances; `reprovisioned` is how many were updated. */
+    grantSkill(slug: string, grant: {
+        freeHttp: boolean;
+        grantedDomains?: string[];
+    }): Promise<{
+        freeHttp: boolean;
+        grantedDomains: string[];
+        reprovisioned: number;
+    }>;
     uninstallSkill(slug: string): Promise<{
         deleted: boolean;
     }>;
@@ -226,6 +324,26 @@ export interface AdminClient {
     deleteWebhook(webhookId: string): Promise<{
         deleted: boolean;
     }>;
+    /** Edit url/events in place (keeps the signing secret + delivery history). */
+    updateWebhook(webhookId: string, patch: {
+        url?: string;
+        events?: string[];
+    }): Promise<{
+        webhook: {
+            webhookId: string;
+        };
+    }>;
+    /** Roll the signing secret (returned ONCE; no dual-secret grace). */
+    rotateWebhookSecret(webhookId: string): Promise<{
+        webhook: {
+            webhookId: string;
+            secret: string;
+        };
+    }>;
+    /** Send a clearly-marked test event to this endpoint (ignores subscriptions). */
+    testWebhook(webhookId: string): Promise<DeliveryOutcome>;
+    /** Manually re-send a recorded delivery's original body, re-signed. */
+    redeliverWebhook(deliveryId: string): Promise<DeliveryOutcome>;
     getUsage(): Promise<MonthUsage>;
     getBilling(): Promise<{
         plan: string;
@@ -236,6 +354,24 @@ export interface AdminClient {
         agentId?: string;
         sinceHours?: number;
     }): Promise<Record<string, unknown>>;
+    /** Recent run rows project-wide (the failed-run browser). */
+    getRecentTraces(params?: {
+        agentId?: string;
+        sinceHours?: number;
+        errorsOnly?: boolean;
+        limit?: number;
+    }): 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). */
+    listVoices(params?: {
+        gender?: 'female' | 'male' | 'neutral';
+        locale?: string;
+    }): Promise<{
+        voices: CatalogVoice[];
+    }>;
     getLogs(params?: {
         limit?: number;
     }): Promise<{

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.1.0';
+export const ADMIN_SDK_VERSION = '0.2.0';
 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. */
@@ -58,17 +58,27 @@ export function createAdminClient(opts) {
         listKeys: () => request('GET', '/keys'),
         createKey: (input) => request('POST', '/keys', input),
         revokeKey: (id) => request('DELETE', `/keys/${encodeURIComponent(id)}`),
+        rotateKey: (id, opts = {}) => request('POST', `/keys/${encodeURIComponent(id)}/rotate`, opts),
         listUsers: (params = {}) => request('GET', `/users${qs(params)}`),
         setUserSuspended: (id, suspended) => request('PATCH', `/users/${encodeURIComponent(id)}`, { suspended }),
         deleteUser: (id) => request('DELETE', `/users/${encodeURIComponent(id)}`),
         getUserWallet: (id) => request('GET', `/users/${encodeURIComponent(id)}/wallet`),
         getUserTraces: (id) => request('GET', `/users/${encodeURIComponent(id)}/traces`),
+        importUsers: (input) => request('POST', '/users/import', input),
+        exportUser: (id) => request('GET', `/users/${encodeURIComponent(id)}/export`),
+        getUserSessions: (id, params = {}) => request('GET', `/users/${encodeURIComponent(id)}/sessions${qs(params)}`),
+        getUserTurns: (id, sessionId, params = {}) => request('GET', `/users/${encodeURIComponent(id)}/sessions/${encodeURIComponent(sessionId)}/turns${qs(params)}`),
         listKnowledge: () => request('GET', '/knowledge'),
         ingestKnowledge: (input) => request('POST', '/knowledge', input),
         deleteKnowledge: (id) => request('DELETE', `/knowledge/${encodeURIComponent(id)}`),
         listSkills: () => request('GET', '/skills'),
         installSkill: (input) => request('POST', '/skills', input),
         updateSkill: (slug, patch) => request('PATCH', `/skills/${encodeURIComponent(slug)}`, patch),
+        setSkillRate: (slug, ratePerMin) => request('PATCH', `/skills/${encodeURIComponent(slug)}`, { ratePerMin }),
+        grantSkill: (slug, grant) => request('PATCH', `/skills/${encodeURIComponent(slug)}`, {
+            freeHttp: grant.freeHttp,
+            grantedDomains: grant.grantedDomains ?? []
+        }),
         uninstallSkill: (slug) => request('DELETE', `/skills/${encodeURIComponent(slug)}`),
         listCredentials: () => request('GET', '/credentials'),
         putCredentials: (input) => request('POST', '/credentials', input),
@@ -86,9 +96,15 @@ export function createAdminClient(opts) {
         listWebhooks: () => request('GET', '/webhooks'),
         createWebhook: (input) => request('POST', '/webhooks', input),
         deleteWebhook: (id) => request('DELETE', `/webhooks/${encodeURIComponent(id)}`),
+        updateWebhook: (id, patch) => request('PATCH', `/webhooks/${encodeURIComponent(id)}`, patch),
+        rotateWebhookSecret: (id) => request('POST', `/webhooks/${encodeURIComponent(id)}/rotate-secret`),
+        testWebhook: (id) => request('POST', `/webhooks/${encodeURIComponent(id)}/test`),
+        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)}`),
+        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)}`),
         getProject: () => request('GET', '/project'),
         updateProject: (patch) => request('PATCH', '/project', patch),

package/package.json

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