@pouchy_ai/admin-sdk 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.14.0 — 2026-08-02
+
+- **Channel provider registration is now typed.** The server registers
+  `telegram`/`discord` connectors with their provider on create (Telegram
+  `setWebhook`, Discord slash command) and re-registers on a `rotate` or a
+  secret replacement, reporting the outcome as a `provision` object. The
+  package typed neither half, so the opt-out was unreachable and the outcome
+  unreadable:
+  - `createChannel` takes **`autoProvision?: boolean`**. This is the half that
+    mattered: `setWebhook` REPLACES rather than adds, so an integrator who
+    already owns their bot's webhook had no typed way to say "don't touch it"
+    — the closed input type made the flag an excess-property error, leaving
+    `request()` or a cast as the only route.
+  - `createChannel` / `updateChannel` return **`provision?:
+    ChannelProvisionResult`**, and `updateChannel` returns the rotate-only
+    `inboundUrl?`. A `failed` outcome on a rotate is the one that bites — the
+    provider still points at the URL the rotate just invalidated, and
+    `manualCommand` is the fix.
+  - `ChannelProvisionResult`, `ChannelProvisionStatus` and
+    `ChannelProvisionCode` are exported. Branch on `code` (a stable contract
+    vocabulary), never on `detail` (provider prose).
+
+  Purely additive: no existing signature narrowed, so 0.13.x code compiles
+  unchanged. `admin-sdk-provision.drift.test.ts` now binds both unions to
+  `channels/provision.ts` so the two copies cannot drift again.
+
+## 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

package/README.md

@@ -200,7 +200,7 @@ Reads (`GET`) are not covered by that bucket. `retryAfter` is available from
 | 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` · `getBilling` · `getTracesSummary` · `getRecentTraces` · `getLogs` · `getProject` · `updateProject` |
+| 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
@@ -208,6 +208,40 @@ Channel types are checked at compile time: `createChannel` takes a
 `internal-a2a`), and `secret` is a named `ChannelSecretInput`. Per-transport
 `secret.extra` fields are listed in <https://pouchy.ai/docs/channel-setup>.
 
+**Telegram and Discord register themselves.** On create — and again on a
+`rotate: true` or a secret replacement, which invalidate what the provider
+holds — the server calls Telegram's `setWebhook` / registers Discord's slash
+command with `secret.token`, and reports the outcome as a
+`ChannelProvisionResult` on `provision`. Two things to know:
+
+- `setWebhook` **replaces** rather than adds. If you already manage your bot's
+  webhook, pass `autoProvision: false` or the create will overwrite it.
+- The connector is durable before any provider call, so this never fails the
+  request — a `failed` outcome is reported, not thrown. Branch on `code` (a
+  stable vocabulary, `ChannelProvisionCode`), never on `detail`; `manualCommand`
+  is the equivalent curl with secrets left as `<PLACEHOLDER>`.
+
+```ts
+import { createAdminClient } from '@pouchy_ai/admin-sdk';
+
+const admin = createAdminClient({ adminKey: process.env.POUCHY_ADMIN_KEY! });
+
+const { connector, provision } = await admin.createChannel({
+  type: 'telegram',
+  agentId: process.env.AGENT_ID!,
+  secret: {
+    token: process.env.TELEGRAM_BOT_TOKEN!,
+    inboundSecret: process.env.TELEGRAM_SECRET_TOKEN!
+  }
+});
+
+if (provision?.status === 'failed') {
+  // The connector exists — only the webhook registration didn't land.
+  console.warn('register by hand:', provision.detail, provision.manualCommand);
+}
+console.log(connector.id);
+```
+
 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

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const ADMIN_SDK_VERSION = "0.12.0";
+export declare const ADMIN_SDK_VERSION = "0.14.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
@@ -220,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;
@@ -297,6 +307,32 @@ export interface ChannelSecretInput {
     /** Extra named credentials for transports whose auth needs more than the pair above. */
     extra?: Record<string, string>;
 }
+/** Outcome class of the provider registration the server performs on create,
+ *  and on a rotate / secret replacement. Mirrors the server's `ProvisionStatus`
+ *  (`channels/provision.ts`); `admin-sdk-provision.drift.test.ts` binds them. */
+export type ChannelProvisionStatus = 'ok' | 'skipped' | 'failed';
+/** Machine-readable reason for a `ChannelProvisionResult`. The server treats
+ *  this vocabulary as part of the response contract (the dashboard keys its
+ *  copy off it), so branch on `code`, never on `detail`. */
+export type ChannelProvisionCode = 'webhook_set' | 'command_registered' | 'unsupported_type' | 'no_token' | 'no_inbound_url' | 'not_requested' | 'invalid_command_name' | 'app_lookup_failed' | 'upstream_rejected' | 'upstream_unreachable';
+/** What the provider said when the server registered this connector for you.
+ *
+ *  Registration is an enrichment on top of a durable write: the connector
+ *  exists whether or not the provider answered, so this NEVER turns a
+ *  successful create into an error — a non-ok outcome is reported here instead.
+ *  A `failed` result always carries `manualCommand`, the equivalent curl with
+ *  every credential left as a `<PLACEHOLDER>`, so the fallback is the manual
+ *  registration this feature replaced rather than a dead end. `detail` is built
+ *  from the provider's own message and never contains a credential. */
+export interface ChannelProvisionResult {
+    status: ChannelProvisionStatus;
+    code: ChannelProvisionCode;
+    /** Operator-facing detail, from the provider's message. Never a credential. */
+    detail?: string;
+    /** The equivalent command to run by hand, secrets left as `<PLACEHOLDER>`.
+     *  Present on every non-ok outcome a human can act on. */
+    manualCommand?: string;
+}
 /** A durable run as the API returns it. Typed rather than `unknown` because
  *  the parked-run flow — read `status`, read `awaiting.token`, answer — is the
  *  SDK's most important interaction, and forcing a cast there would put the
@@ -649,17 +685,44 @@ export interface AdminClient {
         /** Connector credentials (bot token, signing secret, …) — stored
          *  encrypted, never returned. */
         secret?: ChannelSecretInput;
+        /** Default **true**. For `telegram`/`discord` the server registers the
+         *  connector with the provider on create — Telegram `setWebhook(inboundUrl)`,
+         *  Discord a slash command — using `secret.token`, and reports the outcome
+         *  on `provision`. Set `false` if you already manage that registration:
+         *  otherwise the create OVERWRITES your bot's existing webhook, since
+         *  `setWebhook` replaces rather than adds. Every other transport ignores
+         *  this (`provision.code: 'unsupported_type'`). */
+        autoProvision?: boolean;
     }): Promise<{
         connector: {
             id: string;
         };
         inboundUrl: string;
+        /** Absent for transports that need no provider registration. */
+        provision?: ChannelProvisionResult;
     }>;
     getChannel(channelId: string): Promise<{
         connector: unknown;
     }>;
+    /** Patch a connector. Accepts `agentId`, `enabled`, `config`, `secret`,
+     *  `rotate` and `autoProvision` (see `createChannel`).
+     *
+     *  `rotate: true` re-signs the inbound URL and returns it ONCE on
+     *  `inboundUrl` — which also invalidates the old one, so a telegram/discord
+     *  connector is RE-REGISTERED with the provider on a rotate or a secret
+     *  replacement (without that, the provider would keep delivering to a dead
+     *  endpoint while the connector still looked healthy). Check `provision` on
+     *  those two patches: a `failed` outcome means the provider still points at
+     *  the old URL, and `manualCommand` is the fix. Pass `autoProvision: false`
+     *  to suppress. Every other patch — enable/disable, rebind, config — leaves
+     *  both fields absent. */
     updateChannel(channelId: string, patch: Record<string, unknown>): Promise<{
         connector: unknown;
+        /** Present only when the patch carried `rotate: true`. */
+        inboundUrl?: string;
+        /** Present only on a rotate or a secret replacement, for a provisionable
+         *  transport, when not suppressed with `autoProvision: false`. */
+        provision?: ChannelProvisionResult;
     }>;
     deleteChannel(channelId: string): Promise<{
         ok: boolean;
@@ -670,8 +733,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;
@@ -918,6 +983,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.12.0';
+export const ADMIN_SDK_VERSION = '0.14.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;
@@ -302,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.12.0",
+  "version": "0.14.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",