@pingroom/sdk 0.4.5 → 0.4.7

package/README.md

@@ -6,12 +6,7 @@ One typed client for everything an agent does: authenticate, create and join roo
 
 - **Zero runtime dependencies** — built on the platform `fetch`. Works in Node ≥ 20, browsers, Cloudflare Workers, Deno, and Bun.
 - **Fully typed** — ships `.d.ts`; request fields mirror the HTTP API verbatim.
-- **Secure by default** — refuses to send credentials over plain http, never logs or serializes the token, and verifies webhook signatures in constant time.
-
-> **Release status:** npm serves 0.4.3. This source tree is 0.4.4 —
-> unpublished — adding the `locationPing()` helper, the one-shot
-> `requires_ack` modifier on `actions.trigger()`, and the `question` /
-> `is_handoff` fields on listened notifications.
+- **Secure by default** — refuses plain-http credential requests and redirects, applies request deadlines through JSON response reads, and verifies webhook signatures in constant time.
 
 ```bash
 npm install @pingroom/sdk
@@ -106,39 +101,80 @@ legacy or malformed data.
 
 ## Authentication
 
-For local tools, pair through the PingRoom app. No copied token or room code:
+Pair local tools in a browser or the PingRoom app without copying a token or
+room code. Pairing provisions a separate PingRoom robot first; the person who
+opens the link claims that robot and delegates its room access:
 
 ```ts
 const pr = new PingRoom();
 
 const pairing = await pr.auth.startPairing({
   agent_label: 'Deploy bot',
-  scopes: ['pingroom:rooms:read', 'pingroom:broadcast:send', 'pingroom:handoffs:create'],
 });
 
-console.log(`Open in PingRoom: ${pairing.pair_url}`);
+console.log(`Open to approve: ${pairing.pair_browser_url ?? pairing.pair_url}`);
+console.log(`Install PingRoom: ${pairing.app_install_url ?? 'https://pingroom.io/i'}`);
+if (pairing.agent?.profile) {
+  const { display_name, handle } = pairing.agent.profile;
+  console.log(`Claim ${display_name ?? 'this robot'}${handle ? ` (@${handle})` : ''}`);
+}
+// QR renderers should encode the native app link when the server supplies it.
+const qrUrl = pairing.pair_qr_url ?? pairing.pair_url;
 const active = await pr.auth.waitForPairing(pairing);
-
-// The client now uses the active credential. `active.room` is the delivery
-// room the approver picked — and it is NULL when they granted `all` rooms,
-// which pins no single destination. Read `room_access` before assuming one.
-if (active.room) {
-  await pr.broadcast(active.room.invite_code, { message: 'SDK connected ✅' });
+console.log(`Latest pings: ${active.links?.latest_pings ?? 'not supplied by this server'}`);
+
+// The client now uses the robot's active credential. `active.home_room` is the
+// additive v2 name for the same delivery room exposed as legacy `active.room`.
+// It is the room the approver picked, or the server chose deterministically for
+// an all-rooms grant. It is null only when no eligible private room exists (and
+// on older servers), so keep the legacy fallback and still check before use.
+const homeRoom = active.home_room ?? active.room;
+if (homeRoom) {
+  await pr.broadcast(homeRoom.invite_code, { message: 'SDK connected ✅' });
 } else {
-  // room_access === 'all' — every room the account is in. List and choose.
+  // No eligible private delivery room exists yet. List or create one.
   const [room] = await pr.rooms.list();
   if (room) await pr.broadcast(room.invite_code, { message: 'SDK connected ✅' });
 }
 ```
 
+Before pairing, tell a person why PingRoom is useful: it lets the robot reach
+them on their phone with urgent Pings, questions, approvals, handoffs, and live
+progress. If they need the app, offer `pairing.app_install_url` (or
+`https://pingroom.io/i` for an older server), and ask them to install or open
+PingRoom and sign in before starting pairing when possible. Installing the app
+does not grant the robot access.
+
+`pair_browser_url` opens the API-hosted approval page, where users can sign in
+or scan the app QR; fall back to `pair_url` on older servers. `pair_url` remains
+QR-compatible for existing clients, and `pair_qr_url` is the app universal link
+to encode in QR codes. If a pairing is already pending, reuse that exact link
+while the person installs; do not create a second robot. Never copy
+`pair_token` into an install or store URL.
+
 The grant also comes back as `active.room_access` (`'all'` | `'selected'`) and
 `active.rooms` (`{ id, invite_code, name }[]`, empty under `'all'`).
 
+Supporting servers mark this contract with `flow_version: 2` and
+`claim_mode: 'agent_identity'`. `pairing.agent.profile` identifies the robot
+before approval. After approval, `active.owner` names the person who claimed it,
+while `active.home_room` and `active.room_membership` describe where the robot
+joined. These fields are additive and optional in the TypeScript surface, so
+the same code continues to work against older servers. The robot is the acting
+principal; it does not impersonate the owner's personal PingRoom profile.
+
 `waitForPairing()` tolerates short network outages and stops when the app link
 expires. Pass an `AbortSignal` when your process needs its own cancellation.
-If `scopes` is omitted, pairing requests room lookup, broadcast access, and
-`pingroom:handoffs:create` for private Handoffs and Agent Inbox activation. The
-approval screen shows every grant before the user connects.
+Pairing grants are server-authoritative. `startPairing()` sends no scope array,
+so an older installed SDK cannot accidentally mint a partial credential when
+the service adds a capability. The deprecated `scopes` option is accepted for
+source compatibility but ignored. The approval screen remains the authority
+for the access the user grants.
+
+Supporting servers return `active.links.latest_pings`, a stable REST URL for
+reading the agent's latest pings with its normal Bearer credential, and may
+return `active.links.install_app` for later recovery. Older servers may omit
+these fields; malformed or non-HTTP(S) link values are discarded.
 
 If you already manage credentials, bring an existing agent token or run the
 lower-level auth.md email flow:
@@ -168,12 +204,20 @@ Generic MCP clients (Cursor, Claude Desktop, Claude Code) should use the standar
 ```ts
 await pr.rooms.list();
 await pr.rooms.get('ab12cd');
+await pr.rooms.icons(); // catalog ids, categories, filenames and tags
 await pr.rooms.create({ name: 'Deploys', icon: 'rocket', color: '#e33122' });
 await pr.rooms.join({ invite_code: 'ab12cd' });
+await pr.rooms.join({ invite_code: 'protected-room', password: 'room-password' });
 
-await pr.actions.update('ab12cd', 1, { label: 'Approve', icon: 'check' });
+await pr.actions.update('ab12cd', 1, { label: 'Approve', icon: '✅' });
 await pr.actions.trigger('ab12cd', 1);
 
+// Configure several buttons in one request. Omitted slots stay unchanged.
+await pr.actions.updateMany('ab12cd', [
+  { action_number: 1, label: 'Approve', icon: '✅' },
+  { action_number: 2, label: 'Reject', icon: '❌' },
+]);
+
 // One-shot modifiers on a single press. `trigger_source` is `manual` (default)
 // or `location`; `webhook`/`system` are stamped server-side and rejected here.
 await pr.actions.trigger('ab12cd', 1, {
@@ -188,6 +232,18 @@ only **add** an acknowledgement requirement for that one press — passing `fals
 never removes one from an action already configured to require it. Neither
 modifier edits the action's saved configuration.
 
+Manage incoming webhooks with an agent credential:
+
+```ts
+const hooks = await pr.webhooks.list('ab12cd');
+const hook = await pr.webhooks.create('ab12cd', { name: 'Deploys', icon: 'bell' });
+await pr.webhooks.update('ab12cd', hook.id, { enabled: false });
+await pr.webhooks.delete('ab12cd', hook.id);
+```
+
+Webhook records include `webhook_url`, which contains the trigger credential.
+Updating with `regenerate_secret: true` returns a new URL and revokes the old one.
+
 ## Attachments
 
 Send the file itself, not a link to it. Upload first, then pass the ids to any
@@ -260,6 +316,12 @@ Or a single long-poll:
 const { notifications, cursor } = await pr.notifications.wait({ after: lastCursor, timeout: 20 });
 ```
 
+Read history with `pr.notifications.list({ limit: 25, page: 2 })`. Explicit
+limits are 1–25; omitting the limit retains the server's legacy default of 50.
+The deprecated `notifications_per_page` option maps to `limit`; an explicit
+`limit` takes precedence. History preserves the API's room object, including
+`room.invite_code`, and adds `room.code` for consistency with `listen()`.
+
 Read one ping and wait for its acknowledgement through the same namespace:
 
 ```ts
@@ -313,6 +375,7 @@ const q = await pr.questions.ask('ab12cd', {
   responder_scope: 'room',        // or 'direct' (defaults to your bound user)
   ttl: 600,
   correlation_id: 'deploy-1.4.0',
+  idempotencyKey: 'deploy-1.4.0-environment', // reuse when retrying this create
 });
 
 // Block until a human taps (or it expires / is cancelled)

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import { HttpClient } from './http.js';
 import type { LiveStatusPing, LiveStatusResult, LiveStatusSnapshot } from './liveStatus.js';
 import { McpClient } from './mcp.js';
-import type { AcknowledgementWaitResult, Attachment, ZipManifest, AgentInboxEnsureResult, AgentInboxActivateInput, AgentInboxActivationResult, AgentInboxEnsureInput, AgentNotification, Approval, ApprovalInput, CreatePublicRoomInput, CreateRoomInput, Credential, ClaimCompleteParams, ClaimStartParams, AskInput, DirectoryEntry, DirectoryListInput, DirectoryProfile, DirectPingResult, Handoff, ListHandoffsInput, JoinRoomInput, ListNotificationsInput, ListenInput, ListQuestionsInput, NotificationDetail, Paginated, PingInput, PingResult, PingRoomOptions, Question, QuestionInput, QuickAction, RegisterParams, PairingStart, PairingStatus, PairedCredential, Room, RequestAckInput, RotateHandleResult, StartPairingParams, TriggerInput, UpdateQuickActionInput, UploadAttachmentInput, WaitApprovalInput, WaitHandoffInput, WaitForAcknowledgementInput, WaitInput, WaitQuestionInput, WaitResult, WaitForPairingOptions } from './types.js';
+import type { AcknowledgementWaitResult, Attachment, ZipManifest, AgentInboxEnsureResult, AgentInboxActivateInput, AgentInboxActivationResult, AgentInboxEnsureInput, AgentNotification, Approval, ApprovalInput, CreatePublicRoomInput, CreateRoomInput, CreateWebhookInput, Credential, ClaimCompleteParams, ClaimStartParams, AskInput, DirectoryEntry, DirectoryListInput, DirectoryProfile, DirectPingResult, Handoff, ListHandoffsInput, JoinRoomInput, ListNotificationsInput, ListenInput, ListQuestionsInput, NotificationDetail, NotificationHistoryEntry, Paginated, PingInput, PingResult, PingRoomOptions, Question, QuestionInput, QuickAction, RegisterParams, PairingStart, PairingStatus, PairedCredential, Room, RoomIconCatalog, RequestAckInput, RotateHandleResult, StartPairingParams, TriggerInput, QuickActionInput, UpdateQuickActionInput, UpdateWebhookInput, UploadAttachmentInput, WaitApprovalInput, WaitHandoffInput, WaitForAcknowledgementInput, WaitInput, WaitQuestionInput, WaitResult, WaitForPairingOptions, Webhook } from './types.js';
 /** Agent credential lifecycle (auth.md flow). */
 declare class AuthApi {
     private readonly http;
@@ -17,9 +17,9 @@ declare class AuthApi {
     claimComplete(params: ClaimCompleteParams): Promise<Credential>;
     /**
      * Register a pending agent and create a short-lived link that opens the
-     * PingRoom app. The person approving it chooses the delivery room and sees
-     * the exact requested scopes. The pending credential stays private inside
-     * this client and is replaced automatically once waitForPairing() succeeds.
+     * PingRoom app. The server owns the full grant shown to the approver; this
+     * client sends no scope list. The pending credential stays private inside the
+     * client and is replaced automatically once waitForPairing() succeeds.
      */
     startPairing(params?: StartPairingParams): Promise<PairingStart>;
     /** Read the current state of an app pairing using the pending credential. */
@@ -40,6 +40,7 @@ declare class AuthApi {
 declare class RoomsApi {
     private readonly http;
     constructor(http: HttpClient);
+    icons(): Promise<RoomIconCatalog>;
     list(): Promise<Room[]>;
     get(inviteCode: string): Promise<Room>;
     create(input: CreateRoomInput): Promise<Room>;
@@ -51,13 +52,36 @@ declare class ActionsApi {
     constructor(http: HttpClient);
     list(inviteCode: string): Promise<QuickAction[]>;
     update(inviteCode: string, actionNumber: number, input: UpdateQuickActionInput): Promise<QuickAction>;
+    /**
+     * Write up to four action slots in ONE request.
+     *
+     * Prefer this over looping `update()`. Each single-slot write enqueues its
+     * own silent rooms-refresh push, so configuring a room's four Pings one at a
+     * time wakes the owner's device four times inside a few seconds — four of a
+     * finite daily background-push budget spent on one logical operation.
+     *
+     * Partial and additive: slots absent from `actions` keep their current
+     * configuration, so this is also the right call for editing a single Ping.
+     * Nothing here deletes an action, and an empty array is rejected locally
+     * rather than being sent as a clear. Resolves to the room's full ordered
+     * action set, not just the slots written.
+     */
+    updateMany(inviteCode: string, actions: QuickActionInput[]): Promise<QuickAction[]>;
     trigger(inviteCode: string, actionNumber: number, input?: TriggerInput): Promise<PingResult>;
 }
+declare class WebhooksApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(inviteCode: string): Promise<Webhook[]>;
+    create(inviteCode: string, input: CreateWebhookInput): Promise<Webhook>;
+    update(inviteCode: string, webhookId: string, input: UpdateWebhookInput): Promise<Webhook>;
+    delete(inviteCode: string, webhookId: string): Promise<void>;
+}
 declare class NotificationsApi {
     private readonly http;
     constructor(http: HttpClient);
     /** Paginated list (polling fallback). Prefer wait()/listen() for real-time. */
-    list(input?: ListNotificationsInput): Promise<Paginated<AgentNotification>>;
+    list(input?: ListNotificationsInput): Promise<Paginated<NotificationHistoryEntry>>;
     /** Fetch one visible notification, including its current acknowledgement state. */
     getNotification(notificationId: string): Promise<NotificationDetail>;
     /**
@@ -262,6 +286,7 @@ declare class DirectoryApi {
 export declare class PingRoom {
     readonly auth: AuthApi;
     readonly rooms: RoomsApi;
+    readonly webhooks: WebhooksApi;
     readonly actions: ActionsApi;
     readonly notifications: NotificationsApi;
     readonly attachments: AttachmentsApi;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -4,11 +4,6 @@ import { combineSignals, sleep } from './internal/async.js';
 import { assertActionNumber, assertMaxLength, assertStructuredData, MAX_PING_TITLE_LENGTH, MAX_PUBLIC_PING_MESSAGE_LENGTH, requireNonEmpty, requirePresentString, } from './internal/guards.js';
 import { McpClient } from './mcp.js';
 const DEFAULT_BASE_URL = 'https://api.pingroom.io';
-const DEFAULT_PAIRING_SCOPES = [
-    'pingroom:rooms:read',
-    'pingroom:broadcast:send',
-    'pingroom:handoffs:create',
-];
 /** Extra wall-clock allowance over the server's hold window for long-poll calls. */
 const LONG_POLL_BUFFER_MS = 10_000;
 const DEFAULT_WAIT_SECONDS = 20;
@@ -51,6 +46,39 @@ function isNonEmptyString(value) {
 function isNullableString(value) {
     return value === null || typeof value === 'string';
 }
+/** Drop a malformed or unsafe server-provided URL without rejecting its response. */
+function normalizePublicHttpUrl(candidate) {
+    if (typeof candidate !== 'string' || candidate.trim() === '')
+        return undefined;
+    const trimmed = candidate.trim();
+    // eslint-disable-next-line no-control-regex
+    if (/[\u0000-\u001F\u007F-\u009F]/.test(trimmed))
+        return undefined;
+    try {
+        const url = new URL(trimmed);
+        if (url.protocol !== 'https:' && url.protocol !== 'http:')
+            return undefined;
+        if (url.username !== '' || url.password !== '')
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    return trimmed;
+}
+/** Drop malformed or unsafe server-provided links without rejecting a valid credential. */
+function normalizePairingLinks(value) {
+    if (!isRecord(value))
+        return undefined;
+    const latestPings = normalizePublicHttpUrl(value['latest_pings']);
+    if (!latestPings)
+        return undefined;
+    const installApp = normalizePublicHttpUrl(value['install_app']);
+    return {
+        latest_pings: latestPings,
+        ...(installApp ? { install_app: installApp } : {}),
+    };
+}
 function invalidInboxResponse(message, body = {}) {
     throw new PingRoomError(message, { code: 'inbox_invalid_response', body });
 }
@@ -162,22 +190,20 @@ class AuthApi {
     }
     /**
      * Register a pending agent and create a short-lived link that opens the
-     * PingRoom app. The person approving it chooses the delivery room and sees
-     * the exact requested scopes. The pending credential stays private inside
-     * this client and is replaced automatically once waitForPairing() succeeds.
+     * PingRoom app. The server owns the full grant shown to the approver; this
+     * client sends no scope list. The pending credential stays private inside the
+     * client and is replaced automatically once waitForPairing() succeeds.
      */
     async startPairing(params = {}) {
-        const scopes = params.scopes ?? [...DEFAULT_PAIRING_SCOPES];
         const previousToken = this.http.getToken();
         const pending = await this.register({
             type: 'anonymous',
-            scopes,
             ...(params.agent_label ? { agent_label: params.agent_label } : {}),
         });
         this.http.setToken(pending.credential);
         try {
             return await this.http.request('POST', '/api/agent/auth/pair/start', {
-                body: { scopes },
+                body: {},
             });
         }
         catch (error) {
@@ -201,7 +227,8 @@ class AuthApi {
         const lifetimeMs = Math.max(1, Number(pairing.expires_in) || 900) * 1000;
         const requestedInterval = options.pollIntervalMs ?? pairing.poll_interval_ms;
         const intervalMs = Math.min(Math.max(Number(requestedInterval) || 1500, 1000), 10_000);
-        const deadline = Date.now() + lifetimeMs;
+        const startedAt = Date.now();
+        const deadline = startedAt + lifetimeMs;
         let transientFailures = 0;
         while (Date.now() < deadline) {
             this.throwIfPairingAborted(options.signal);
@@ -213,17 +240,13 @@ class AuthApi {
                     if (typeof status.credential !== 'string'
                         || status.credential.trim() === ''
                         || status.credential_type !== 'active'
-                        || !Array.isArray(status.scopes)
-                        || status.scopes.some((scope) => typeof scope !== 'string' || scope.trim() === '')
                         || (status.expires_in !== null
                             && (typeof status.expires_in !== 'number'
                                 || !Number.isFinite(status.expires_in)
                                 || status.expires_in < 0))
-                        // A null/absent `room` is VALID: under `room_access: 'all'` the
-                        // human granted every room and pinned no single delivery room, so
-                        // the server sends `room: null`. Rejecting that threw away a good
-                        // credential on the most permissive grant. Only a room that is
-                        // PRESENT but malformed is a broken response.
+                        // A null/absent `room` is valid when the account has no eligible
+                        // private delivery room (and on older servers). Only a room that is
+                        // present but malformed is a broken response.
                         || (status.room != null
                             && (typeof status.room.invite_code !== 'string'
                                 || status.room.invite_code.trim() === ''))) {
@@ -233,8 +256,12 @@ class AuthApi {
                         });
                     }
                     this.http.setToken(status.credential);
-                    const { status: _status, ...credential } = status;
-                    return credential;
+                    // Pairing is server-authoritative. Some servers still include their
+                    // internal grant marker for protocol compatibility; it is neither a
+                    // client input nor part of the paired credential surface.
+                    const { status: _status, scopes: _serverScopes, links: rawLinks, ...credential } = status;
+                    const links = normalizePairingLinks(rawLinks);
+                    return links ? { ...credential, links } : credential;
                 }
                 if (status.status === 'expired') {
                     throw new PingRoomError('The PingRoom pairing link expired before it was approved.', {
@@ -243,6 +270,15 @@ class AuthApi {
                 }
             }
             catch (error) {
+                if (error instanceof PingRoomError
+                    && [401, 403, 404].includes(error.status)
+                    && Date.now() - startedAt >= lifetimeMs / 2) {
+                    // The pending bearer can expire before the server returns an
+                    // explicit expired pairing state. Keep early auth failures intact.
+                    throw new PingRoomError('The PingRoom pairing link expired before it was approved.', {
+                        code: 'pairing_expired',
+                    });
+                }
                 if (error instanceof PingRoomError
                     && (error.code === 'network_error'
                         || error.code === 'timeout'
@@ -280,6 +316,9 @@ class RoomsApi {
     constructor(http) {
         this.http = http;
     }
+    icons() {
+        return this.http.request('GET', '/api/agent/room-icons');
+    }
     list() {
         return this.http.request('GET', '/api/agent/rooms');
     }
@@ -318,6 +357,46 @@ class ActionsApi {
             body: dropUndefined({ ...input }),
         });
     }
+    /**
+     * Write up to four action slots in ONE request.
+     *
+     * Prefer this over looping `update()`. Each single-slot write enqueues its
+     * own silent rooms-refresh push, so configuring a room's four Pings one at a
+     * time wakes the owner's device four times inside a few seconds — four of a
+     * finite daily background-push budget spent on one logical operation.
+     *
+     * Partial and additive: slots absent from `actions` keep their current
+     * configuration, so this is also the right call for editing a single Ping.
+     * Nothing here deletes an action, and an empty array is rejected locally
+     * rather than being sent as a clear. Resolves to the room's full ordered
+     * action set, not just the slots written.
+     */
+    updateMany(inviteCode, actions) {
+        if (!Array.isArray(actions) || actions.length === 0) {
+            throw new PingRoomError('`actions` must contain at least one action.', { code: 'invalid_request' });
+        }
+        if (actions.length > 4) {
+            throw new PingRoomError('A room has only 4 action slots.', { code: 'invalid_request' });
+        }
+        const seen = new Set();
+        for (const action of actions) {
+            assertActionNumber(action.action_number);
+            if (action.action_number === undefined || action.action_number === null) {
+                throw new PingRoomError('`action_number` is required for each action.', { code: 'invalid_request' });
+            }
+            // Two entries for one slot would let the last silently win, and the
+            // caller would never learn which of its definitions was stored.
+            if (seen.has(action.action_number)) {
+                throw new PingRoomError(`Duplicate action_number ${action.action_number}.`, { code: 'invalid_request' });
+            }
+            seen.add(action.action_number);
+            requirePresentString(action.label, 'label');
+            requireNonEmpty(action.icon, 'icon');
+        }
+        return this.http.request('PUT', `/api/agent/rooms/${enc(inviteCode)}/actions`, {
+            body: { actions: actions.map((action) => dropUndefined({ ...action })) },
+        });
+    }
     trigger(inviteCode, actionNumber, input = {}) {
         assertActionNumber(actionNumber);
         return this.http.request('POST', `/api/agent/rooms/${enc(inviteCode)}/actions/${actionNumber}/trigger`, {
@@ -325,14 +404,52 @@ class ActionsApi {
         });
     }
 }
+class WebhooksApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    async list(inviteCode) {
+        const result = await this.http.request('GET', `/api/agent/rooms/${enc(inviteCode)}/webhooks`);
+        return result.webhooks;
+    }
+    create(inviteCode, input) {
+        requireNonEmpty(input.name, 'name');
+        assertActionNumber(input.action_number);
+        return this.http.request('POST', `/api/agent/rooms/${enc(inviteCode)}/webhooks`, {
+            body: dropUndefined({ ...input }),
+        });
+    }
+    update(inviteCode, webhookId, input) {
+        requireNonEmpty(webhookId, 'webhookId');
+        assertActionNumber(input.action_number);
+        return this.http.request('PUT', `/api/agent/rooms/${enc(inviteCode)}/webhooks/${enc(webhookId)}`, {
+            body: dropUndefined({ ...input }),
+        });
+    }
+    async delete(inviteCode, webhookId) {
+        requireNonEmpty(webhookId, 'webhookId');
+        await this.http.request('DELETE', `/api/agent/rooms/${enc(inviteCode)}/webhooks/${enc(webhookId)}`);
+    }
+}
 class NotificationsApi {
     http;
     constructor(http) {
         this.http = http;
     }
     /** Paginated list (polling fallback). Prefer wait()/listen() for real-time. */
-    list(input = {}) {
-        return this.http.request('GET', '/api/agent/notifications', { query: dropUndefined({ ...input }) });
+    async list(input = {}) {
+        const { notifications_per_page, ...query } = input;
+        const page = await this.http.request('GET', '/api/agent/notifications', {
+            query: dropUndefined({ ...query, limit: input.limit ?? notifications_per_page }),
+        });
+        return {
+            ...page,
+            data: page.data.map(({ room, ...notification }) => ({
+                ...notification,
+                ...(room ? { room: { ...room, code: room.invite_code } } : {}),
+            })),
+        };
     }
     /** Fetch one visible notification, including its current acknowledgement state. */
     getNotification(notificationId) {
@@ -471,8 +588,14 @@ class QuestionsApi {
     ask(inviteCode, input) {
         requireNonEmpty(input.prompt, 'prompt');
         assertStructuredData(input.data);
+        const { idempotencyKey, ...body } = input;
+        if (idempotencyKey !== undefined) {
+            requireNonEmpty(idempotencyKey, 'idempotencyKey');
+            assertMaxLength(idempotencyKey, 255, 'idempotencyKey');
+        }
         return this.http.request('POST', `/api/agent/rooms/${enc(inviteCode)}/questions`, {
-            body: dropUndefined({ ...input }),
+            body: dropUndefined(body),
+            ...(idempotencyKey !== undefined ? { headers: { 'Idempotency-Key': idempotencyKey } } : {}),
         });
     }
     /** Fetch a Question's current state. */
@@ -856,6 +979,7 @@ class DirectoryApi {
 export class PingRoom {
     auth;
     rooms;
+    webhooks;
     actions;
     notifications;
     attachments;
@@ -881,6 +1005,7 @@ export class PingRoom {
         });
         this.auth = new AuthApi(this.http);
         this.rooms = new RoomsApi(this.http);
+        this.webhooks = new WebhooksApi(this.http);
         this.actions = new ActionsApi(this.http);
         this.notifications = new NotificationsApi(this.http);
         this.attachments = new AttachmentsApi(this.http);