@pouchy_ai/admin-sdk 0.4.4 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.6.0 — 2026-07-21
+
+Additive: knowledge ingestion parity + headless agent version control. Both
+close a documented owner-console-only gap so the whole build-and-serve loop is
+now reachable with a `pchy_admin_…` key.
+
+- **Knowledge ingestion beyond raw text.** Three new methods mirror the
+  dashboard's knowledge tab, sharing the exact server-side pipelines:
+  - **`ingestKnowledgeFile({ dataUrl, name?, kind?, locale?, replaceDocId? })`**
+    — ingest a PDF / audio / video / image data URL; the server runs the same
+    understanding (OCR / Whisper / vision caption) as the SDK personal-materials
+    path, then chunks + embeds into the shared corpus.
+  - **`ingestKnowledgeUrl({ url, name?, locale?, replaceDocId? })`** — ingest a
+    web page (https only, SSRF-guarded fetch, HTML reduced to text).
+  - **`searchKnowledge(query)`** — recall probe: run the SAME retrieval an
+    instance turn uses and get the ranked chunks back, without burning an LLM
+    turn. `mode` is `semantic` or `lexical`.
+- **Agent version control (headless GitOps of a persona).** Six methods:
+  `listAgentVersions`, `getAgentVersion`, `diffAgentVersions`, `rollbackAgent`,
+  `getAgentPromotion`, `promoteAgent`. Inspect the rolling revision history,
+  diff any two revisions (or against `current`), roll back (git-revert
+  semantics), and drive staging→prod promotion — all previously
+  owner-session-only.
+
+Server: adds `POST /v1/admin/knowledge/{file,url,search}`,
+`GET /v1/admin/agents/{agentId}/versions[/{rev}|/diff]`,
+`POST /v1/admin/agents/{agentId}/versions/rollback`, and
+`GET|POST /v1/admin/agents/{agentId}/promote`. No breaking changes.
+
+## 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

package/README.md

@@ -86,10 +86,11 @@ try {
 | Area | Methods |
 | --- | --- |
 | Agents | `listAgents` · `createAgent` · `getAgent` · `updateAgent` · `deleteAgent` |
+| Agent versions | `listAgentVersions` · `getAgentVersion` · `diffAgentVersions({ from?, to? })` · `rollbackAgent` · `getAgentPromotion` · `promoteAgent` (staging→prod) |
 | 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` |
-| Knowledge | `listKnowledge` · `ingestKnowledge` · `deleteKnowledge` |
+| 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` · `ingestKnowledgeFile` (PDF/audio/video/image) · `ingestKnowledgeUrl` (web page) · `searchKnowledge` (recall probe) · `deleteKnowledge` |
 | Skills | `listSkills` · `installSkill` · `updateSkill` · `setSkillRate` · `setSkillDailyCap` · `grantSkill` (free-HTTP) · `compileSkill` (prose→tools) · `uninstallSkill` |
 | Credentials | `listCredentials` · `putCredentials` · `deleteCredentials` |
 | Channels | `listChannels` · `createChannel` · `getChannel` · `updateChannel` · `deleteChannel` |

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.4.4";
+export declare const ADMIN_SDK_VERSION = "0.6.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. */
@@ -132,6 +132,62 @@ export interface AdminClient {
     deleteAgent(agentId: string): Promise<{
         deleted: boolean;
     }>;
+    /** Archived template revisions, newest first. The live/current template is
+     *  NOT in here — it lives on the agent doc; a snapshot is created only when a
+     *  persona edit supersedes a rev. */
+    listAgentVersions(agentId: string): Promise<{
+        versions: Array<{
+            version: number;
+            templateRev: number;
+            archivedAt: string;
+            name: string;
+        }>;
+    }>;
+    /** One archived template snapshot — the full frozen agent for that revision. */
+    getAgentVersion(agentId: string, rev: number): Promise<{
+        version: Agent;
+    }>;
+    /** Field-level diff between two revisions. `from`/`to` are each an archived
+     *  version number or `current` (default) = the live template; only changed
+     *  fields are returned. */
+    diffAgentVersions(agentId: string, opts?: {
+        from?: number | 'current';
+        to?: number | 'current';
+    }): Promise<{
+        from: string;
+        to: string;
+        diff: Array<{
+            field: string;
+            from: unknown;
+            to: unknown;
+        }>;
+    }>;
+    /** Roll an agent back to an archived revision. git-revert semantics: the
+     *  snapshot re-applies as a NEW edit (rev moves forward), the current state is
+     *  archived first. */
+    rollbackAgent(agentId: string, version: number): Promise<{
+        agent: Agent;
+    }>;
+    /** Promotion status: the head (staging) vs the pinned production version, plus
+     *  the diff a promotion would ship (empty when in sync). `pending` is false
+     *  when the agent was never promoted (live follows the head). */
+    getAgentPromotion(agentId: string): Promise<{
+        stagingRev: number;
+        prodRev: number | null;
+        pending: boolean;
+        diff: Array<{
+            field: string;
+            from: unknown;
+            to: unknown;
+        }>;
+    }>;
+    /** Promote the head to production: freezes the head as an archived version and
+     *  pins prodRev WITHOUT bumping the rev. Live instances re-resolve on their
+     *  next mint; test instances always run the head. */
+    promoteAgent(agentId: string): Promise<{
+        prodRev: number;
+        templateRev: number;
+    }>;
     listKeys(): Promise<{
         keys: SecretKey[];
     }>;
@@ -159,13 +215,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;
@@ -224,6 +286,48 @@ export interface AdminClient {
             chunks: number;
         };
     }>;
+    /** Ingest a RAW file (PDF / audio / video / image data URL) into the shared
+     *  corpus — same server-side understanding (OCR / Whisper / vision caption)
+     *  as the SDK personal-materials path, then chunk + embed. `replaceDocId`
+     *  updates an existing doc in place. */
+    ingestKnowledgeFile(input: {
+        dataUrl: string;
+        name?: string;
+        kind?: string;
+        locale?: string;
+        replaceDocId?: string;
+    }): Promise<{
+        ok: boolean;
+        doc: {
+            docId: string;
+            chunks: number;
+        };
+        summary?: string;
+    }>;
+    /** Ingest a WEB PAGE by URL (https only, SSRF-guarded fetch, HTML reduced to
+     *  readable text server-side) into the shared corpus. */
+    ingestKnowledgeUrl(input: {
+        url: string;
+        name?: string;
+        locale?: string;
+        replaceDocId?: string;
+    }): Promise<{
+        ok: boolean;
+        doc: {
+            docId: string;
+            chunks: number;
+        };
+        summary?: string;
+        sourceUrl: string;
+    }>;
+    /** Recall probe: run the SAME retrieval an instance turn uses and get the
+     *  ranked chunks back, WITHOUT burning an LLM turn. `mode` is the recall
+     *  truth — `semantic` (vector path answered) or `lexical` (fallback). */
+    searchKnowledge(query: string): Promise<{
+        query: string;
+        mode: 'semantic' | 'lexical';
+        hits: unknown[];
+    }>;
     deleteKnowledge(docId: string): Promise<{
         deleted: boolean;
     }>;

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.4';
+export const ADMIN_SDK_VERSION = '0.6.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;
@@ -70,6 +70,12 @@ export function createAdminClient(opts) {
         getAgent: (id) => request('GET', `/agents/${encodeURIComponent(id)}`),
         updateAgent: (id, patch) => request('PATCH', `/agents/${encodeURIComponent(id)}`, patch),
         deleteAgent: (id) => request('DELETE', `/agents/${encodeURIComponent(id)}`),
+        listAgentVersions: (id) => request('GET', `/agents/${encodeURIComponent(id)}/versions`),
+        getAgentVersion: (id, rev) => request('GET', `/agents/${encodeURIComponent(id)}/versions/${rev}`),
+        diffAgentVersions: (id, opts = {}) => request('GET', `/agents/${encodeURIComponent(id)}/versions/diff${qs(opts)}`),
+        rollbackAgent: (id, version) => request('POST', `/agents/${encodeURIComponent(id)}/versions/rollback`, { version }),
+        getAgentPromotion: (id) => request('GET', `/agents/${encodeURIComponent(id)}/promote`),
+        promoteAgent: (id) => request('POST', `/agents/${encodeURIComponent(id)}/promote`, {}),
         listKeys: () => request('GET', '/keys'),
         createKey: (input) => request('POST', '/keys', input),
         revokeKey: (id) => request('DELETE', `/keys/${encodeURIComponent(id)}`),
@@ -85,6 +91,9 @@ export function createAdminClient(opts) {
         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),
+        ingestKnowledgeFile: (input) => request('POST', '/knowledge/file', input),
+        ingestKnowledgeUrl: (input) => request('POST', '/knowledge/url', input),
+        searchKnowledge: (query) => request('POST', '/knowledge/search', { query }),
         deleteKnowledge: (id) => request('DELETE', `/knowledge/${encodeURIComponent(id)}`),
         listSkills: () => request('GET', '/skills'),
         installSkill: (input) => request('POST', '/skills', input),

package/package.json

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