@pouchy_ai/admin-sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to `@pouchy_ai/admin-sdk` are documented here.
+
+## 0.1.0
+
+Initial release. Typed, zero-dependency client for the Pouchy Admin API
+(`https://pouchy.ai/v1/admin`):
+
+- `createAdminClient({ adminKey, baseUrl?, fetch? })` → typed methods for agents,
+  secret keys, end users, knowledge, skills, credentials, channels, schedules,
+  webhooks, plus usage / billing / traces / audit-log / project reporting.
+- `AdminApiError` (with `status`) on any non-2xx response.
+- `request(method, path, body?)` escape hatch for endpoints not yet typed.
+- Pairs with the machine-readable spec at `GET /v1/admin/openapi` (OpenAPI 3.1).

package/LICENSE

@@ -0,0 +1,41 @@
+Pouchy Companion SDK License
+Copyright (c) 2026 Pouchy.ai. All Rights Reserved.
+
+This license governs use of the "@pouchy_ai/companion-sdk" software package (the
+"SDK") as published to the npm registry. The SDK is proprietary software owned
+by Pouchy.ai. By installing, copying, or using the SDK you agree to these terms.
+
+1. GRANT. Subject to these terms, Pouchy.ai grants you a worldwide,
+   non-exclusive, non-transferable, royalty-free, revocable license to install
+   and use the SDK, as distributed, solely to build and operate applications
+   that integrate with Pouchy.ai's official services and APIs.
+
+2. RESTRICTIONS. Except to the extent a restriction below is prohibited by
+   applicable law, you may not:
+   (a) modify, adapt, or create derivative works of the SDK's source for
+       redistribution;
+   (b) redistribute, sublicense, sell, rent, or lease the SDK as a standalone
+       product, or republish it under a different name;
+   (c) reverse engineer, decompile, or disassemble the SDK except to the extent
+       necessary for interoperability and expressly permitted by law;
+   (d) use the SDK to build or operate a service that competes with Pouchy.ai's
+       services, or to access Pouchy.ai's services in violation of their terms;
+   (e) remove or alter any copyright, trademark, or other proprietary notices.
+
+3. RESERVATION OF RIGHTS. All rights not expressly granted are reserved by
+   Pouchy.ai. No rights are granted in Pouchy.ai's source repositories,
+   trademarks, or services beyond what is needed to use the SDK as described.
+
+4. TERMINATION. This license terminates automatically if you breach it. On
+   termination you must stop using and delete all copies of the SDK.
+
+5. NO WARRANTY. THE SDK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
+6. LIMITATION OF LIABILITY. IN NO EVENT SHALL POUCHY.AI BE LIABLE FOR ANY CLAIM,
+   DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR
+   OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SDK OR THE USE OR
+   OTHER DEALINGS IN THE SDK.
+
+For any other use, or for written permission, contact legal@pouchy.ai.

package/README.md

@@ -0,0 +1,92 @@
+# @pouchy_ai/admin-sdk
+
+Typed TypeScript client for the **Pouchy Admin API** — everything the dashboard
+does, headless. Manage agents, secret keys, end users, knowledge, skills,
+channels, schedules, webhooks and credentials; read usage, billing, traces and
+audit logs. Zero runtime dependencies (uses the global `fetch`).
+
+The Admin API is authenticated with a **project-scoped Admin key**
+(`pchy_admin_…`, from the dashboard **Admin Keys** page). The project is implied
+by the key — you never pass a project id.
+
+## Install
+
+```bash
+npm i @pouchy_ai/admin-sdk
+```
+
+## Quickstart
+
+```ts
+import { createAdminClient } from '@pouchy_ai/admin-sdk';
+
+const admin = createAdminClient({ adminKey: process.env.POUCHY_ADMIN_KEY! });
+
+// List agents
+const { agents } = await admin.listAgents();
+
+// Create + publish an agent
+const { agent } = await admin.createAgent({
+  name: 'Support Bot',
+  archetype: 'support',
+  systemPrompt: 'You are a concise, friendly support agent.'
+});
+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
+
+// Read this month's usage
+const usage = await admin.getUsage();
+console.log(usage.mau, '/', usage.mauLimit, 'MAU');
+```
+
+## Options
+
+```ts
+createAdminClient({
+  adminKey: 'pchy_admin_…',   // required
+  baseUrl: 'https://pouchy.ai/v1/admin', // optional (self-host / staging)
+  fetch: myFetch              // optional (Node <18, or tests)
+});
+```
+
+## Errors
+
+Every method throws `AdminApiError` on a non-2xx response:
+
+```ts
+import { AdminApiError } from '@pouchy_ai/admin-sdk';
+try {
+  await admin.getAgent('nope');
+} catch (e) {
+  if (e instanceof AdminApiError) console.error(e.status, e.message); // 404 "unknown agent"
+}
+```
+
+## Surface
+
+| Area | Methods |
+| --- | --- |
+| Agents | `listAgents` · `createAgent` · `getAgent` · `updateAgent` · `deleteAgent` |
+| Secret keys | `listKeys` · `createKey` · `revokeKey` |
+| End users | `listUsers` · `setUserSuspended` · `deleteUser` · `getUserWallet` · `getUserTraces` |
+| Knowledge | `listKnowledge` · `ingestKnowledge` · `deleteKnowledge` |
+| Skills | `listSkills` · `installSkill` · `updateSkill` · `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` |
+| Escape hatch | `request(method, path, body?)` — any endpoint not yet typed |
+
+## OpenAPI
+
+The machine-readable contract is served at **`GET https://pouchy.ai/v1/admin/openapi`**
+(OpenAPI 3.1, public). Import it into Postman / Swagger UI, or generate a client
+in any other language with `openapi-generator`.
+
+## License
+
+SEE LICENSE IN LICENSE.

package/dist/index.d.ts

@@ -0,0 +1,262 @@
+export declare const ADMIN_SDK_VERSION = "0.1.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. */
+    adminKey: string;
+    /** Override the API base (self-host / staging). Default production. */
+    baseUrl?: string;
+    /** Inject a fetch impl (Node <18, or for tests). Default global fetch. */
+    fetch?: typeof fetch;
+}
+/** Thrown on any non-2xx response. `status` is the HTTP status; `message` is the
+ *  server's `error` string when present. */
+export declare class AdminApiError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+export type Env = 'live' | 'test';
+export type AgentStatus = 'draft' | 'published';
+export type ModelTier = 'standard' | 'pro';
+export interface Agent {
+    agentId: string;
+    name: string;
+    archetype: string;
+    systemPrompt: string;
+    status?: AgentStatus;
+    modelTier?: ModelTier;
+    templateRev: number;
+    createdAt: string;
+    [k: string]: unknown;
+}
+export interface SecretKey {
+    keyId: string;
+    label: string;
+    env: Env;
+    prefix: string;
+    createdAt: string;
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+}
+export interface Instance {
+    instanceId: string;
+    externalUserId: string;
+    agentId: string;
+    createdAt: string;
+    lastActiveAt: string;
+    suspended?: boolean;
+}
+export interface MonthUsage {
+    month: string;
+    mau: number;
+    mauLimit: number;
+    sessions: number;
+    tokensIn: number;
+    tokensOut: number;
+    [k: string]: unknown;
+}
+export interface AuditRow {
+    at: string;
+    type: string;
+    detail: Record<string, unknown>;
+}
+/** The Admin API client. Every method returns the parsed JSON body; failures
+ *  throw AdminApiError. */
+export interface AdminClient {
+    listAgents(): Promise<{
+        agents: Agent[];
+    }>;
+    createAgent(input: {
+        name: string;
+        archetype: string;
+        systemPrompt?: string;
+    } & Record<string, unknown>): Promise<{
+        agent: Agent;
+    }>;
+    getAgent(agentId: string): Promise<{
+        agent: Agent;
+    }>;
+    updateAgent(agentId: string, patch: Partial<Agent> & Record<string, unknown>): Promise<{
+        agent: Agent;
+    }>;
+    deleteAgent(agentId: string): Promise<{
+        deleted: boolean;
+    }>;
+    listKeys(): Promise<{
+        keys: SecretKey[];
+    }>;
+    createKey(input: {
+        label?: string;
+        env?: Env;
+    }): Promise<{
+        key: {
+            keyId: string;
+            token: string;
+            env: Env;
+        };
+    }>;
+    revokeKey(keyId: string): Promise<{
+        revoked: boolean;
+    }>;
+    listUsers(params?: {
+        q?: string;
+        limit?: number;
+    }): Promise<{
+        users: Instance[];
+    }>;
+    setUserSuspended(instanceId: string, suspended: boolean): Promise<{
+        suspended: boolean;
+    }>;
+    deleteUser(instanceId: string): Promise<{
+        deleted: boolean;
+    }>;
+    getUserWallet(instanceId: string): Promise<{
+        balance: number;
+        address: string;
+    }>;
+    getUserTraces(instanceId: string): Promise<{
+        traces: unknown[];
+    }>;
+    listKnowledge(): Promise<{
+        docs: unknown[];
+    }>;
+    ingestKnowledge(input: {
+        title?: string;
+        text?: string;
+        url?: string;
+    }): Promise<{
+        doc: {
+            docId: string;
+            chunks: number;
+        };
+    }>;
+    deleteKnowledge(docId: string): Promise<{
+        deleted: boolean;
+    }>;
+    listSkills(): Promise<{
+        skills: unknown[];
+    }>;
+    installSkill(input: {
+        md?: string;
+        url?: string;
+        mcpUrl?: string;
+        openapi?: string;
+        openapiUrl?: string;
+        slug?: string;
+    }): Promise<{
+        skill: {
+            slug: string;
+            version: number;
+        };
+    }>;
+    updateSkill(slug: string, patch: Record<string, unknown>): Promise<{
+        skill: {
+            slug: string;
+        };
+    }>;
+    uninstallSkill(slug: string): Promise<{
+        deleted: boolean;
+    }>;
+    listCredentials(): Promise<{
+        credentials: unknown[];
+    }>;
+    putCredentials(input: {
+        skill: string;
+        credentials: Record<string, unknown>;
+    }): Promise<{
+        ok: boolean;
+    }>;
+    deleteCredentials(skill: string): Promise<{
+        deleted: boolean;
+    }>;
+    listChannels(): Promise<{
+        channels: unknown[];
+    }>;
+    createChannel(input: {
+        type: string;
+        agentId: string;
+        config?: Record<string, unknown>;
+    }): Promise<{
+        channel: {
+            id: string;
+        };
+        inboundUrl: string;
+    }>;
+    getChannel(channelId: string): Promise<{
+        channel: unknown;
+    }>;
+    updateChannel(channelId: string, patch: Record<string, unknown>): Promise<{
+        channel: unknown;
+    }>;
+    deleteChannel(channelId: string): Promise<{
+        deleted: boolean;
+    }>;
+    listSchedules(): Promise<{
+        schedules: unknown[];
+    }>;
+    createSchedule(input: {
+        agentId: string;
+        cron: string;
+        prompt?: string;
+    }): Promise<{
+        schedule: {
+            scheduleId: string;
+        };
+    }>;
+    getSchedule(scheduleId: string): Promise<{
+        schedule: unknown;
+    }>;
+    updateSchedule(scheduleId: string, patch: Record<string, unknown>): Promise<{
+        schedule: unknown;
+    }>;
+    deleteSchedule(scheduleId: string): Promise<{
+        deleted: boolean;
+    }>;
+    listWebhooks(): Promise<{
+        webhooks: unknown[];
+    }>;
+    createWebhook(input: {
+        url: string;
+        events?: string[];
+    }): Promise<{
+        webhook: {
+            webhookId: string;
+            secret: string;
+        };
+    }>;
+    deleteWebhook(webhookId: string): Promise<{
+        deleted: boolean;
+    }>;
+    getUsage(): Promise<MonthUsage>;
+    getBilling(): Promise<{
+        plan: string;
+        mauLimit: number;
+        periodEnd?: string;
+    }>;
+    getTracesSummary(params?: {
+        agentId?: string;
+        sinceHours?: number;
+    }): Promise<Record<string, unknown>>;
+    getLogs(params?: {
+        limit?: number;
+    }): Promise<{
+        logs: AuditRow[];
+    }>;
+    getProject(): Promise<{
+        project: {
+            projectId: string;
+            name: string;
+            archived?: boolean;
+        };
+    }>;
+    updateProject(patch: {
+        name?: string;
+        archived?: boolean;
+    }): Promise<{
+        project: {
+            projectId: string;
+        };
+    }>;
+    /** Escape hatch: call any endpoint the typed methods don't cover yet. */
+    request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+}
+export declare function createAdminClient(opts: AdminClientOptions): AdminClient;

package/dist/index.js

@@ -0,0 +1,97 @@
+// @pouchy_ai/admin-sdk — a tiny, zero-dependency TypeScript client for the
+// Pouchy Admin API (https://pouchy.ai/v1/admin). Everything the dashboard does,
+// headless: manage agents, keys, end users, knowledge, skills, channels,
+// schedules, webhooks, credentials — plus read usage, billing, traces and audit
+// logs. Authenticate with a project-scoped Admin key (the project is implied by
+// the key). The machine-readable contract is at GET /v1/admin/openapi.
+//
+//   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 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. */
+export class AdminApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = 'AdminApiError';
+        this.status = status;
+    }
+}
+function qs(params) {
+    const u = new URLSearchParams();
+    for (const [k, v] of Object.entries(params))
+        if (v != null)
+            u.set(k, String(v));
+    const s = u.toString();
+    return s ? `?${s}` : '';
+}
+export function createAdminClient(opts) {
+    if (!opts.adminKey)
+        throw new AdminApiError('adminKey is required', 0);
+    const base = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const f = opts.fetch ?? globalThis.fetch;
+    if (!f)
+        throw new AdminApiError('no fetch available — pass opts.fetch on Node <18', 0);
+    async function request(method, path, body) {
+        const res = await f(base + path, {
+            method,
+            headers: {
+                authorization: `Bearer ${opts.adminKey}`,
+                ...(body !== undefined ? { 'content-type': 'application/json' } : {})
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined
+        });
+        const data = (await res.json().catch(() => ({})));
+        if (!res.ok)
+            throw new AdminApiError(data?.error ?? `HTTP ${res.status}`, res.status);
+        return data;
+    }
+    return {
+        listAgents: () => request('GET', '/agents'),
+        createAgent: (input) => request('POST', '/agents', input),
+        getAgent: (id) => request('GET', `/agents/${encodeURIComponent(id)}`),
+        updateAgent: (id, patch) => request('PATCH', `/agents/${encodeURIComponent(id)}`, patch),
+        deleteAgent: (id) => request('DELETE', `/agents/${encodeURIComponent(id)}`),
+        listKeys: () => request('GET', '/keys'),
+        createKey: (input) => request('POST', '/keys', input),
+        revokeKey: (id) => request('DELETE', `/keys/${encodeURIComponent(id)}`),
+        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`),
+        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),
+        uninstallSkill: (slug) => request('DELETE', `/skills/${encodeURIComponent(slug)}`),
+        listCredentials: () => request('GET', '/credentials'),
+        putCredentials: (input) => request('POST', '/credentials', input),
+        deleteCredentials: (skill) => request('DELETE', `/credentials/${encodeURIComponent(skill)}`),
+        listChannels: () => request('GET', '/channels'),
+        createChannel: (input) => request('POST', '/channels', input),
+        getChannel: (id) => request('GET', `/channels/${encodeURIComponent(id)}`),
+        updateChannel: (id, patch) => request('PATCH', `/channels/${encodeURIComponent(id)}`, patch),
+        deleteChannel: (id) => request('DELETE', `/channels/${encodeURIComponent(id)}`),
+        listSchedules: () => request('GET', '/schedules'),
+        createSchedule: (input) => request('POST', '/schedules', input),
+        getSchedule: (id) => request('GET', `/schedules/${encodeURIComponent(id)}`),
+        updateSchedule: (id, patch) => request('PATCH', `/schedules/${encodeURIComponent(id)}`, patch),
+        deleteSchedule: (id) => request('DELETE', `/schedules/${encodeURIComponent(id)}`),
+        listWebhooks: () => request('GET', '/webhooks'),
+        createWebhook: (input) => request('POST', '/webhooks', input),
+        deleteWebhook: (id) => request('DELETE', `/webhooks/${encodeURIComponent(id)}`),
+        getUsage: () => request('GET', '/usage'),
+        getBilling: () => request('GET', '/billing'),
+        getTracesSummary: (params = {}) => request('GET', `/traces/summary${qs(params)}`),
+        getLogs: (params = {}) => request('GET', `/logs${qs(params)}`),
+        getProject: () => request('GET', '/project'),
+        updateProject: (patch) => request('PATCH', '/project', patch),
+        request
+    };
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@pouchy_ai/admin-sdk",
+  "version": "0.1.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",
+  "homepage": "https://pouchy.ai/sdk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/oviswang/Pouchy.git",
+    "directory": "packages/admin-sdk"
+  },
+  "bugs": { "email": "support@pouchy.ai" },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "README.md", "CHANGELOG.md", "LICENSE"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": { "typescript": "^5.5.0" },
+  "keywords": ["pouchy", "admin", "api", "sdk", "agent-platform"],
+  "publishConfig": { "access": "public" }
+}