@pouchy_ai/admin-sdk 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 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` —

package/README.md

@@ -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.13.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
@@ -307,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
@@ -659,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;

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.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;

package/package.json

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