@pouchy_ai/admin-sdk 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 All notable changes to `@pouchy_ai/admin-sdk` are documented here.
 
+## 0.15.0 — 2026-08-03
+
+- **`MonthUsage` now types the whole meter, including credits and voice.** The
+  interface declared six fields (`month`, `mau`, `mauLimit`, `sessions`,
+  `tokensIn`, `tokensOut`) while `GET /usage` returns sixteen. The rest fell
+  through the `[k: string]: unknown` index signature, so they were reachable but
+  typed `unknown` — `usage.credits > limit` did not compile, and reading the
+  product's metered units from the typed client required a cast. Newly declared:
+  - `credits`, `creditsByDay`, `creditLimit` — the per-turn credit meter;
+  - `creditsVoice`, `voiceMs`, `voiceCalls` — the realtime-voice slice of
+    `credits` and the measured minutes behind it. Voice is the most expensive
+    metered unit, so this is the split worth alerting on;
+  - `mauTest`, `sessionsByDay`, `mauByDay`, `tokensByDay` — the test-key MAU
+    count and the per-day chart buckets.
+
+  Additive and backwards-compatible: the index signature is retained, and every
+  new field is optional so the package stays honest against a deployment that
+  predates one. No runtime change — this release is types and docs only.
+
+  A drift gate now pins the interface against the server's usage reader, so the
+  next field added server-side cannot silently skip the package again.
+
+## 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` —

package/README.md

@@ -37,9 +37,12 @@ await admin.updateAgent(agent.agentId, { status: 'published' });
 const { key } = await admin.createKey({ label: 'prod-backend', env: 'live' });
 console.log(key); // the plaintext token — shown ONCE
 
-// Read this month's usage
+// Read this month's usage — MAU, tokens, and the credit meter (all typed)
 const { usage } = await admin.getUsage();
 console.log(usage.mau, '/', usage.mauLimit, 'MAU');
+console.log(usage.credits, '/', usage.creditLimit, 'credits');
+// Voice is the priciest metered unit — watch its slice, not just the total
+console.log(usage.creditsVoice, 'of those credits were', usage.voiceCalls, 'voice calls');
 
 // Equip an agent with ANY skill — including a docs-only skill.md that has no
 // `tools:` block — entirely via the API:
@@ -208,6 +211,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.13.0";
+export declare const ADMIN_SDK_VERSION = "0.15.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
@@ -211,13 +211,52 @@ export interface Instance {
     lastActiveAt: string;
     suspended?: boolean;
 }
+/** The current month's meter, as `GET /usage` returns it.
+ *
+ *  Every field the server sends is declared. The index signature stays for
+ *  forward compatibility with a newer server, but it is a fallback, not the
+ *  contract: reaching a field THROUGH it yields `unknown`, so
+ *  `usage.credits > limit` does not compile and an integrator has to cast — the
+ *  same untyped-surface friction the channel-provisioning gap caused. The
+ *  credit/voice fields below are the ones that bit: they are the product's
+ *  metered units, and they shipped server-side (and in the OpenAPI) while this
+ *  interface still described only MAU and tokens.
+ *
+ *  All but `month` are optional so the package stays honest against an OLDER
+ *  deployment that predates a field — a self-hosted server on a prior release
+ *  really can omit the voice trio, and typing them as required would be the
+ *  package asserting something it cannot know. */
 export interface MonthUsage {
     month: string;
     mau: number;
+    /** Sessions minted by TEST keys — metered but never gated. */
+    mauTest?: number;
+    /** The plan's monthly MAU cap. ACCOUNT-scoped (pooled across the owner's
+     *  projects) while `mau` above is this project's slice, so `mau / mauLimit`
+     *  understates consumption on a multi-project account — compare against the
+     *  pooled figure from `getUsageHistory({ scope: 'account' })` when you need
+     *  the number the mint gate actually enforces. */
     mauLimit: number;
     sessions: number;
     tokensIn: number;
     tokensOut: number;
+    /** Per-UTC-day buckets, `{ 'YYYY-MM-DD': n }` — for charts. */
+    sessionsByDay?: Record<string, number>;
+    mauByDay?: Record<string, number>;
+    tokensByDay?: Record<string, number>;
+    creditsByDay?: Record<string, number>;
+    /** Credits consumed this month: one per completed standard turn, the Pro
+     *  multiplier per Pro turn, and the per-minute rate for realtime voice. */
+    credits?: number;
+    /** The VOICE slice of `credits`, and the measured minutes it came from.
+     *  Project-scoped: the pooled account counter carries no per-source
+     *  breakdown. Voice is by far the most expensive metered unit, so this is
+     *  the split to watch before a bill surprises anyone. */
+    creditsVoice?: number;
+    voiceMs?: number;
+    voiceCalls?: number;
+    /** The plan's monthly credit allowance (account-level, like `mauLimit`). */
+    creditLimit?: number;
     [k: string]: unknown;
 }
 /** One month of the usage-history series. Unlike `MonthUsage` (the current
@@ -307,6 +346,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
@@ -659,17 +724,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;

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.13.0';
+export const ADMIN_SDK_VERSION = '0.15.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;

package/package.json

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