@pouchy_ai/admin-sdk 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.13.0 — 2026-08-02
+
+- **`getUsageHistory({ months? })`** over `GET /v1/admin/usage/history` —
+  month-over-month `{ months: MonthUsageHistoryEntry[], scope }`, oldest
+  first, quiet months zero-filled. The route shipped with the 1.4.x history
+  work; this closes the package's own "new mirror ⇒ new method" convention
+  gap (a headless operator could read this month but not the history).
+  `scope: 'account'` is the pooled series the plan cap compares;
+  `'project'` is the fallback when the account can't be resolved.
+  `MonthUsageHistoryEntry` is exported.
+
+## 0.12.0 — 2026-08-01
+
+- **Typed capability declarations.** `publishCapability` now takes a
+  `CapabilityDeclaration` (`ViewDeclaration | ActionDeclaration |
+  EventDeclaration`, all exported) — compile-time help for the one call with
+  14+ fields and four closed vocabularies (`sensitivity`, `idempotency`,
+  `automation`, `signing`). The server stays the one validator; an index
+  signature keeps newer server fields publishable from an older SDK.
+- **Typed agent Data flags.** `Agent` gains `data?: AgentData` — the live
+  levers (`enabled`, `actions.enabled` / `autoRun` / `autoRunDailyCap`,
+  `events.enabled` / `subscriptions`), usable through
+  `updateAgent(id, { data: { … } })`.
+- **Observability readers.** `listActionExecutions({ limit? })` and
+  `listEventReceipts({ limit? })` over the new `/v1/admin/actions` +
+  `/v1/admin/events` mirrors (Admin API 1.5.0) — the durable Action journal
+  (typed rows incl. `authorizedBy: 'automation'`) and Event receipts + wake
+  trail, closing the headless loop: publish → test → read back what ran.
+
 ## 0.11.0 — 2026-08-01
 
 - **Data capabilities, headless.** Six new methods over the `/v1/admin/capabilities`

package/README.md

@@ -198,15 +198,20 @@ Reads (`GET`) are not covered by that bucket. `retryAfter` is available from
 | Channels | `listChannels` · `createChannel` · `getChannel` · `updateChannel` · `deleteChannel` |
 | Schedules | `listSchedules` · `createSchedule` · `getSchedule` · `updateSchedule` · `deleteSchedule` |
 | Durable runs | `listRuns` · `createRun` · `getRun` · `cancelRun` · `resumeRun` · `signalRun` |
+| Data capabilities | `listCapabilities` (heads + MASKED signing status) · `publishCapability` (TYPED `CapabilityDeclaration`; immutable next version, idempotent on content) · `setCapabilityDisabled` (per-capability live revoke) · `listCapabilityVersions` (history; rollback = republish an old declaration) · `testReadCapability` · `testActionCapability({ confirmDuplicates: true, … })` (REAL deliveries incl. intentional duplicates — 428 without consent) · `listActionExecutions` (the durable Action journal, incl. `authorizedBy: 'automation'`) · `listEventReceipts` (receipts + wake trail) |
+| Webhooks | `listWebhooks` · `createWebhook` · `updateWebhook` · `rotateWebhookSecret` · `deleteWebhook` · `testWebhook` · `redeliverWebhook` |
+| Reporting | `getUsage` · `getUsageHistory` · `getBilling` · `getTracesSummary` · `getRecentTraces` · `getLogs` · `getProject` · `updateProject` |
+| Escape hatch | `request(method, path, body?)` — any endpoint not yet typed |
 
 Channel types are checked at compile time: `createChannel` takes a
 `CreatableChannelType` (the platform's 31-transport union minus the adapterless
 `internal-a2a`), and `secret` is a named `ChannelSecretInput`. Per-transport
 `secret.extra` fields are listed in <https://pouchy.ai/docs/channel-setup>.
-| Data capabilities | `listCapabilities` (heads + MASKED signing status) · `publishCapability` (immutable next version, idempotent on content) · `setCapabilityDisabled` (per-capability live revoke) · `listCapabilityVersions` (history; rollback = republish an old declaration) · `testReadCapability` · `testActionCapability({ confirmDuplicates: true, … })` (REAL deliveries incl. intentional duplicates — 428 without consent) |
-| 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 |
+
+Capability **signing-key management is deliberately not mirrored** here: the
+one-time `pcsk_`/`pesk_` plaintext reveal stays a human act on the owner
+plane (dashboard / owner API). `listCapabilities` returns masked key status
+only.
 
 ### Durable runs
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.11.0";
+export declare const ADMIN_SDK_VERSION = "0.13.0";
 export declare const DEFAULT_BASE_URL = "https://pouchy.ai/v1/admin";
 /** Deadline for the routes whose server handler declares `maxDuration: 300` —
  *  the server's own ceiling plus headroom, so a client abort can only ever mean
@@ -99,6 +99,30 @@ export declare class AdminApiError extends Error {
 export type Env = 'live' | 'test';
 export type AgentStatus = 'draft' | 'published';
 export type ModelTier = 'standard' | 'pro';
+/** The agent template's Data plane flags — the LIVE half of every Data
+ *  authorization (the pinned half is the published declaration). All fields
+ *  are live levers: flipping one off stops that plane on the next turn of
+ *  sessions already running. */
+export interface AgentData {
+    /** Parent gate: instances get `read_data` + the pinned capability menu. */
+    enabled?: boolean;
+    actions?: {
+        /** Exposes the confirm-gated `run_action` gateway (needs `enabled`). */
+        enabled?: boolean;
+        /** Operator half of event-to-action automation (≤5 action names; the
+         *  declaration must also say `automation: 'allowed'`). */
+        autoRun?: string[];
+        /** Automated runs per user per UTC day, 1..50 (default 10). */
+        autoRunDailyCap?: number;
+    };
+    events?: {
+        /** Lets your backend POST published events at this agent's instances. */
+        enabled?: boolean;
+        /** Subscription routing: an event POSTed WITHOUT agentId fans out to
+         *  every subscribed, events-enabled agent (≤10 capability names). */
+        subscriptions?: string[];
+    };
+}
 export interface Agent {
     agentId: string;
     name: string;
@@ -106,10 +130,67 @@ export interface Agent {
     systemPrompt: string;
     status?: AgentStatus;
     modelTier?: ModelTier;
+    /** Agent Data plane flags (see AgentData). */
+    data?: AgentData;
     templateRev: number;
     createdAt: string;
     [k: string]: unknown;
 }
+export type CapabilitySensitivity = 'public' | 'personal' | 'intimate';
+export interface ViewDeclaration {
+    kind: 'view';
+    /** The agent's business vocabulary (e.g. `Order`), not a table name. */
+    name: string;
+    description: string;
+    sensitivity?: CapabilitySensitivity;
+    /** ONE exact lowercase hostname; every endpoint must live on it. */
+    audience: string;
+    /** HTTPS GET endpoint — declared `filters` arrive as query parameters. */
+    endpoint: string;
+    /** Output allowlist — extra fields your endpoint returns never reach the agent. */
+    fields: string[];
+    filters?: string[];
+    [k: string]: unknown;
+}
+export interface ActionDeclaration {
+    kind: 'action';
+    name: string;
+    description: string;
+    sensitivity?: CapabilitySensitivity;
+    audience: string;
+    /** HTTPS POST endpoint — receives `{"actionId","action","args"}` signed. */
+    endpoint: string;
+    args?: string[];
+    /** The contract's only Phase-1 mode. */
+    idempotency: 'action_id';
+    /** Signed read-only `GET ?actionId=` resolver for `unknown` outcomes. */
+    reconcile?: {
+        endpoint: string;
+    };
+    /** Declared + validated today, NOT yet dispatched (forward-compat). */
+    compensate?: {
+        endpoint: string;
+    };
+    /** Author's pinned safety claim: eligible for event-driven automation
+     *  (still needs the agent's live `autoRun` grant). */
+    automation?: 'allowed';
+    [k: string]: unknown;
+}
+export interface EventDeclaration {
+    kind: 'event';
+    name: string;
+    description: string;
+    sensitivity?: CapabilitySensitivity;
+    /** The declared emitter id — bound at ingress, never payload-decided. */
+    source: string;
+    schemaVersion: number;
+    /** Payload field mined as the subject reference (an EXISTING instance). */
+    subjectField: string;
+    /** Demand POUCHY-SOURCE-V1 per-source signatures on ingress. */
+    signing?: 'required';
+    [k: string]: unknown;
+}
+export type CapabilityDeclaration = ViewDeclaration | ActionDeclaration | EventDeclaration;
 export interface SecretKey {
     keyId: string;
     label: string;
@@ -139,6 +220,16 @@ export interface MonthUsage {
     tokensOut: number;
     [k: string]: unknown;
 }
+/** One month of the usage-history series. Unlike `MonthUsage` (the current
+ *  month's full meter incl. day buckets and the cap), history rows are the
+ *  compact per-month rollup the server keeps for every past month. */
+export interface MonthUsageHistoryEntry {
+    month: string;
+    mau: number;
+    mauTest: number;
+    sessions: number;
+    [k: string]: unknown;
+}
 export interface AuditRow {
     at: string;
     type: string;
@@ -589,8 +680,10 @@ export interface AdminClient {
     /** Create a schedule. `externalUserId` and `prompt` are required alongside
      *  `agentId`; the schedule fires by `intervalMinutes` (recurring, >=5) or
      *  `runAt` (one-shot **epoch milliseconds** — an ISO string is silently
-     *  ignored by the server) — there is NO cron field. Returns the stored
-     *  record, whose id lives on `.id`. */
+     *  ignored by the server; must be in the future — a past `runAt` is a 400,
+     *  with a 60s clock-skew grace) — there is NO cron field. A storage outage
+     *  answers 503, not a validation 400. Returns the stored record, whose id
+     *  lives on `.id`. */
     createSchedule(input: {
         agentId: string;
         externalUserId: string;
@@ -712,7 +805,7 @@ export interface AdminClient {
      *  bytes mint version+1 and never rewrite an old one. Publishing is NOT
      *  revocation — the per-agent data flags and `setCapabilityDisabled` are
      *  the live levers. */
-    publishCapability(declaration: Record<string, unknown>): Promise<{
+    publishCapability(declaration: CapabilityDeclaration): Promise<{
         revision: {
             capabilityId: string;
             version: number;
@@ -757,6 +850,48 @@ export interface AdminClient {
         args?: Record<string, unknown>;
         externalUserId?: string;
     }): Promise<Record<string, unknown>>;
+    /** The durable Action journal, newest first (limit clamped to 1..100,
+     *  default 50) — every run_action ever dispatched, with pinned revision,
+     *  canonical intent, outcome status and reconcile trail. `unknown` is
+     *  shown as unknown, never dressed up; `authorizedBy: 'automation'` marks
+     *  event-driven runs (absent = a user approved). Same rows as the
+     *  owner-plane viewer (one server-side shaper, two doors). */
+    listActionExecutions(params?: {
+        limit?: number;
+    }): Promise<{
+        executions: Array<{
+            actionId: string;
+            capabilityId: string;
+            version: number;
+            revisionHash: string;
+            status: 'dispatching' | 'committed' | 'rejected' | 'unknown';
+            intent: Record<string, string>;
+            intentHash: string;
+            subject: {
+                kind: string;
+                externalUserId?: string;
+            } | null;
+            confirmId: string;
+            authorizedBy?: 'user' | 'automation';
+            createdAt: number;
+            settledAt?: number;
+            remoteStatus?: number;
+            receipt?: string;
+            reconcileAttempts?: number;
+            reconcileLastAt?: number | null;
+            reconcileLastResult?: string | null;
+            [k: string]: unknown;
+        }>;
+    }>;
+    /** Event receipts + wake trail, newest first (limit clamped to 1..100,
+     *  default 50). Pure metadata — the payload was mined for the subject and
+     *  discarded at ingress. The wake trail records acceptance, turn and
+     *  delivery milestones SEPARATELY: accepted never implies a turn ran. */
+    listEventReceipts(params?: {
+        limit?: number;
+    }): Promise<{
+        receipts: Array<Record<string, unknown>>;
+    }>;
     listWebhooks(): Promise<{
         webhooks: unknown[];
     }>;
@@ -795,6 +930,18 @@ export interface AdminClient {
     getUsage(): Promise<{
         usage: MonthUsage;
     }>;
+    /** Month-over-month usage series, oldest first; quiet months zero-fill
+     *  rather than drop. `scope: 'account'` means the pooled account series —
+     *  the figure the plan cap actually compares (a multi-project account's
+     *  pooled number differs from any one project's slice); `'project'` is the
+     *  fallback when the account can't be resolved. */
+    getUsageHistory(params?: {
+        /** Window size in months, clamped server-side to 1..24 (default 12). */
+        months?: number;
+    }): Promise<{
+        months: MonthUsageHistoryEntry[];
+        scope: 'account' | 'project';
+    }>;
     getBilling(): Promise<{
         billing: {
             plan: 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.11.0';
+export const ADMIN_SDK_VERSION = '0.13.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;
@@ -291,6 +291,8 @@ export function createAdminClient(opts) {
         setCapabilityDisabled: (name, disabled) => request('PATCH', `/capabilities/${encodeURIComponent(name)}`, { disabled }),
         listCapabilityVersions: (name) => request('GET', `/capabilities/${encodeURIComponent(name)}/versions`),
         testReadCapability: (name, input = {}) => request('POST', `/capabilities/${encodeURIComponent(name)}/test-read`, input),
+        listActionExecutions: (params = {}) => request('GET', `/actions${qs(params)}`),
+        listEventReceipts: (params = {}) => request('GET', `/events${qs(params)}`),
         testActionCapability: (name, input) => request('POST', `/capabilities/${encodeURIComponent(name)}/test-action`, input),
         listWebhooks: () => request('GET', '/webhooks'),
         createWebhook: (input) => request('POST', '/webhooks', input),
@@ -300,6 +302,7 @@ export function createAdminClient(opts) {
         testWebhook: (id) => request('POST', `/webhooks/${encodeURIComponent(id)}/test`),
         redeliverWebhook: (id) => request('POST', `/webhooks/deliveries/${encodeURIComponent(id)}/redeliver`),
         getUsage: () => request('GET', '/usage'),
+        getUsageHistory: (params = {}) => request('GET', `/usage/history${qs(params)}`),
         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 })}`),

package/package.json

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