@pingroom/sdk 0.7.0 → 0.8.0

package/dist/client.js

@@ -1,11 +1,14 @@
 import { PingRoomActivationIncompleteError, PingRoomError } from './errors.js';
 import { HttpClient } from './http.js';
-import { combineSignals, sleep } from './internal/async.js';
-import { assertActionNumber, assertMaxLength, assertStructuredData, MAX_PING_TITLE_LENGTH, MAX_PUBLIC_PING_MESSAGE_LENGTH, normalizeRedeemCode, requireNonEmpty, requirePresentString, } from './internal/guards.js';
+import { combineSignals, sleep, throwIfAborted } from './internal/async.js';
+import { assertActionNumber, assertMaxLength, assertStructuredData, MAX_PING_TITLE_LENGTH, MAX_PUBLIC_PING_MESSAGE_LENGTH, normalizeIdempotencyKey, normalizeRedeemCode, requireNonEmpty, requirePresentString, } from './internal/guards.js';
+import { isTransientError, pollUntilSettled, transientDelayMs } from './internal/retry.js';
 import { linkPing } from './linkPing.js';
 import { locationPing } from './locationPing.js';
 import { McpClient } from './mcp.js';
 const DEFAULT_BASE_URL = 'https://api.pingroom.io';
+/** Node's util.inspect hook, named through the global registry so no import is needed. */
+const INSPECT = Symbol.for('nodejs.util.inspect.custom');
 /** Server cap per uploaded file; a larger body is a 413 the server answers before reading it. */
 const ATTACHMENT_MAX_BYTES = 5 * 1024 * 1024;
 const MAX_TRIGGER_ATTACHMENTS = 4;
@@ -15,14 +18,70 @@ const MAX_QUICK_ACTION_PAGES = 4;
 const LONG_POLL_BUFFER_MS = 10_000;
 const DEFAULT_WAIT_SECONDS = 20;
 const DEFAULT_INBOX_ACTIVATION_TIMEOUT_MS = 120_000;
-const MIN_INBOX_ACTIVATION_POLL_INTERVAL_MS = 2100;
+/**
+ * Minimum spacing between the starts of two handoff-wait polls. The route is
+ * throttled at 30 requests a minute per human; a short or zero `timeout`
+ * would otherwise let one loop exhaust it.
+ */
+const MIN_HANDOFF_POLL_INTERVAL_MS = 2100;
+/**
+ * Minimum spacing between the starts of two approval or question wait polls.
+ * The server normally holds each one, but a proxy or a zero hold that answers
+ * `pending` at once would otherwise spin the loop and keep the human's shared
+ * 30-per-minute wait bucket exhausted. Same floor as the CLI.
+ */
+const MIN_WAIT_POLL_INTERVAL_MS = 1000;
 function envBaseUrl() {
     const proc = globalThis.process;
     return proc?.env?.['PINGROOM_API_URL'] || proc?.env?.['PINGROOM_BASE_URL'] || undefined;
 }
 function enc(segment) {
+    // encodeURIComponent leaves `.` and `..` alone, and URL parsing then
+    // resolves them as dot segments: `live.get('AB12', '..')` would request the
+    // room itself. No id is empty or a dot segment, so refuse them.
+    if (segment === '' || segment === '.' || segment === '..') {
+        throw new PingRoomError('A path parameter may not be empty, `.` or `..`.', { code: 'invalid_request' });
+    }
     return encodeURIComponent(segment);
 }
+/**
+ * Lift the SDK-only `idempotencyKey` out of an input and into the
+ * `Idempotency-Key` header the server reads. The server trims the key and
+ * accepts 1–255 characters; as a header it must also be printable ASCII.
+ */
+function splitIdempotencyKey(input) {
+    const { idempotencyKey, ...body } = input;
+    if (idempotencyKey === undefined) {
+        return { body };
+    }
+    return { body, headers: { 'Idempotency-Key': normalizeIdempotencyKey(idempotencyKey) } };
+}
+/** `onRetry`, when given, must be callable: a TypeError mid-outage would hide the real failure. */
+function assertOnRetry(onRetry) {
+    if (onRetry !== undefined && typeof onRetry !== 'function') {
+        throw new PingRoomError('`onRetry` must be a function.', { code: 'invalid_request' });
+    }
+}
+/**
+ * The per-slot checks shared by `updateMany()` and `updateLayout()`: a valid,
+ * present, unique action_number and an icon whenever the slot has a label.
+ * Two entries for one slot would let the last silently win, and the caller
+ * would never learn which of its definitions was stored.
+ */
+function assertActionSlots(actions) {
+    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' });
+        }
+        if (seen.has(action.action_number)) {
+            throw new PingRoomError(`Duplicate action_number ${action.action_number}.`, { code: 'invalid_request' });
+        }
+        seen.add(action.action_number);
+        assertQuickActionIcon(action);
+    }
+}
 function dropUndefined(obj) {
     const out = {};
     for (const [k, v] of Object.entries(obj)) {
@@ -219,10 +278,56 @@ function validateInboxWait(value, expectedId) {
     }
     return value;
 }
-function throwIfAborted(signal) {
-    if (signal.aborted) {
-        throw signal.reason ?? new Error('aborted');
+/** UUIDs are case-insensitive; a caller may hold an id in either case. */
+function sameId(received, expected) {
+    return typeof received === 'string' && received.toLowerCase() === expected.toLowerCase();
+}
+function invalidWaitResponse(subject, expectedId, value, stateField) {
+    throw new PingRoomError(`PingRoom returned an invalid ${subject} wait response.`, {
+        code: 'invalid_response',
+        body: {
+            expected_id: expectedId,
+            received_id: isRecord(value) && typeof value['id'] === 'string' ? value['id'] : null,
+            [stateField]: isRecord(value) && typeof value[stateField] === 'string' ? value[stateField] : null,
+        },
+    });
+}
+const APPROVAL_STATUSES = new Set(['pending', 'decided', 'expired', 'cancelled']);
+const QUESTION_STATES = new Set(['pending', 'answered', 'expired', 'cancelled']);
+const HANDOFF_STATES = new Set(['open', 'acked', 'pending', 'answered', 'expired', 'cancelled']);
+/**
+ * A wait response is trusted as an outcome only when it is the approval that
+ * was asked about, in a known status. A captive portal's HTML, `{}`, or another
+ * approval must not read as "decided".
+ */
+function validateApprovalWait(value, approvalId) {
+    const status = isRecord(value) ? value['status'] : undefined;
+    if (!isRecord(value)
+        || !sameId(value['id'], approvalId)
+        || typeof status !== 'string'
+        || !APPROVAL_STATUSES.has(status)
+        || !isNullableString(value['decided_at'])
+        // A gate acts on `decision`; a decided approval without one, or a pending
+        // one already stamped decided, is not an outcome it can act on.
+        || (status === 'decided' && !isNonEmptyString(value['decision']))
+        || (status === 'pending' && value['decided_at'] !== null)) {
+        return invalidWaitResponse('approval', approvalId, value, 'status');
     }
+    return value;
+}
+function validateQuestionWait(value, questionId) {
+    const state = isRecord(value) ? value['state'] : undefined;
+    if (!isRecord(value) || !sameId(value['id'], questionId) || typeof state !== 'string' || !QUESTION_STATES.has(state)) {
+        return invalidWaitResponse('question', questionId, value, 'state');
+    }
+    return value;
+}
+function validateHandoffWait(value, handoffId) {
+    const state = isRecord(value) ? value['state'] : undefined;
+    if (!isRecord(value) || !sameId(value['id'], handoffId) || typeof state !== 'string' || !HANDOFF_STATES.has(state)) {
+        return invalidWaitResponse('handoff', handoffId, value, 'state');
+    }
+    return value;
 }
 // --- namespaces -----------------------------------------------------------
 /** Agent credential lifecycle (auth.md flow). */
@@ -290,10 +395,10 @@ class AuthApi {
         const deadline = startedAt + lifetimeMs;
         let transientFailures = 0;
         while (Date.now() < deadline) {
-            this.throwIfPairingAborted(options.signal);
+            throwIfAborted(options.signal);
             try {
                 const status = await this.pairingStatus({ signal: options.signal });
-                this.throwIfPairingAborted(options.signal);
+                throwIfAborted(options.signal);
                 transientFailures = 0;
                 if (status.status === 'active') {
                     if (typeof status.credential !== 'string'
@@ -356,11 +461,6 @@ class AuthApi {
             code: 'pairing_expired',
         });
     }
-    throwIfPairingAborted(signal) {
-        if (signal?.aborted) {
-            throw signal.reason ?? new Error('aborted');
-        }
-    }
     /** Rotate to a fresh credential (same scopes/handle). */
     refresh() {
         return this.http.request('POST', '/api/agent/auth/refresh', { body: {} });
@@ -369,6 +469,23 @@ class AuthApi {
     revoke() {
         return this.http.request('POST', '/api/agent/auth/revoke', { body: {} });
     }
+    /**
+     * What this credential is connected to: the robot, the owner's public id and
+     * name, the home room and room memberships, and the room grant. Check
+     * `owner.id` and `handle` against the account and robot you approved before
+     * sending anything.
+     */
+    connection() {
+        return this.http.request('GET', '/api/agent/connection');
+    }
+    /**
+     * Disconnect this agent: revokes the calling credential and its refresh
+     * credentials. The client keeps the now-revoked token; clear it with
+     * `setToken(null)` or pair again.
+     */
+    disconnect() {
+        return this.http.request('POST', '/api/agent/disconnect', { body: {} });
+    }
 }
 class RoomsApi {
     http;
@@ -446,20 +563,7 @@ class ActionsApi {
         if (actions.length > 16) {
             throw new PingRoomError('A batch may contain at most 16 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);
-            assertQuickActionIcon(action);
-        }
+        assertActionSlots(actions);
         return this.http.request('PUT', `/api/agent/rooms/${enc(inviteCode)}/actions`, {
             body: { actions: actions.map((action) => dropUndefined({ ...action })) },
         });
@@ -475,8 +579,10 @@ class ActionsApi {
     trigger(inviteCode, actionNumber, input = {}) {
         assertActionNumber(actionNumber);
         assertTriggerInput(input);
+        const { body, headers } = splitIdempotencyKey(input);
         return this.http.request('POST', `/api/agent/rooms/${enc(inviteCode)}/actions/${actionNumber}/trigger`, {
-            body: dropUndefined({ ...input }),
+            body: dropUndefined({ ...body }),
+            ...(headers ? { headers } : {}),
         });
     }
     /**
@@ -507,15 +613,7 @@ class ActionsApi {
                 code: 'invalid_request',
             });
         }
-        const seen = new Set();
-        for (const action of input.actions) {
-            assertActionNumber(action.action_number);
-            if (seen.has(action.action_number)) {
-                throw new PingRoomError(`Duplicate action_number ${action.action_number}.`, { code: 'invalid_request' });
-            }
-            seen.add(action.action_number);
-            assertQuickActionIcon(action);
-        }
+        assertActionSlots(input.actions);
         return this.http.request('PUT', `/api/agent/rooms/${enc(inviteCode)}/actions/layout`, {
             body: {
                 base_action_ids: input.base_action_ids,
@@ -649,35 +747,39 @@ class NotificationsApi {
      */
     async *listen(input = {}) {
         let cursor = input.after;
-        if (cursor === undefined) {
-            const head = await this.wait({ timeout: 0, ...(input.signal ? { signal: input.signal } : {}) });
-            cursor = head.cursor;
-            for (const n of head.notifications) {
-                yield n;
-            }
-        }
-        const backoff = input.backoffMs ?? 1000;
+        let headRead = cursor !== undefined;
+        const backoffMs = input.backoffMs ?? 1000;
+        let failures = 0;
         while (!input.signal?.aborted) {
             let result;
             try {
-                result = await this.wait({
-                    after: cursor,
-                    ...(input.timeout !== undefined ? { timeout: input.timeout } : {}),
-                    ...(input.limit !== undefined ? { limit: input.limit } : {}),
-                    ...(input.signal ? { signal: input.signal } : {}),
-                });
+                result = headRead
+                    ? await this.wait({
+                        after: cursor,
+                        ...(input.timeout !== undefined ? { timeout: input.timeout } : {}),
+                        ...(input.limit !== undefined ? { limit: input.limit } : {}),
+                        ...(input.signal ? { signal: input.signal } : {}),
+                    })
+                    // No cursor yet: read the current head (an immediate, empty answer)
+                    // so only pings that land after this call are delivered.
+                    : await this.wait({ timeout: 0, ...(input.signal ? { signal: input.signal } : {}) });
             }
             catch (err) {
                 if (input.signal?.aborted) {
                     return;
                 }
-                if (input.onError) {
-                    input.onError(err);
-                    await sleep(backoff, input.signal);
-                    continue;
+                // A revoked credential or a bad request never heals; only network
+                // failures, deadlines, 429 and 5xx are retried.
+                if (!isTransientError(err)) {
+                    throw err;
                 }
-                throw err;
+                failures += 1;
+                input.onError?.(err);
+                await sleep(transientDelayMs(err, failures, backoffMs), input.signal);
+                continue;
             }
+            failures = 0;
+            headRead = true;
             cursor = result.cursor ?? cursor;
             for (const n of result.notifications) {
                 yield n;
@@ -700,7 +802,11 @@ class AgentsApi {
     ping(handle, ping) {
         requireNonEmpty(handle, 'handle');
         assertPing(ping);
-        return this.http.request('POST', `/api/agent/agents/${enc(handle)}/ping`, { body: dropUndefined({ ...ping }) });
+        const { body, headers } = splitIdempotencyKey(ping);
+        return this.http.request('POST', `/api/agent/agents/${enc(handle)}/ping`, {
+            body: dropUndefined({ ...body }),
+            ...(headers ? { headers } : {}),
+        });
     }
 }
 class ApprovalsApi {
@@ -712,8 +818,10 @@ class ApprovalsApi {
     request(inviteCode, input) {
         requireNonEmpty(input.question, 'question');
         assertStructuredData(input.data);
+        const { body, headers } = splitIdempotencyKey(input);
         return this.http.request('POST', `/api/agent/rooms/${enc(inviteCode)}/approvals`, {
-            body: dropUndefined({ ...input }),
+            body: dropUndefined({ ...body }),
+            ...(headers ? { headers } : {}),
         });
     }
     get(approvalId) {
@@ -727,20 +835,29 @@ class ApprovalsApi {
             ...(input.signal ? { signal: input.signal } : {}),
         });
     }
-    /** Block until the human decides (or the request expires), looping wait() under the hood. */
+    /**
+     * Block until the human decides (or the request expires or is cancelled),
+     * looping wait() under the hood, with polls started at least 1 s apart. A
+     * response that is not this approval in a known status rejects with
+     * `invalid_response`. Network failures, 429 and 5xx are retried with backoff
+     * (honouring `retryAfter`), and reported to `onRetry`, until `signal` aborts
+     * or the outage outlasts the approval's `expires_at` by 5 minutes (15 minutes
+     * of failures while no `expires_at` has been read); that rejects with
+     * `unavailable`. See {@link WaitForOutcomeOptions}.
+     */
     async waitForDecision(approvalId, input = {}) {
-        for (;;) {
-            if (input.signal?.aborted) {
-                throw input.signal.reason ?? new Error('aborted');
-            }
-            const approval = await this.wait(approvalId, input.signal ? { signal: input.signal } : {});
-            if (approval.decided_at !== null || approval.status !== 'pending') {
-                return approval;
-            }
-            // An injected transport can resolve pending polls immediately. Yield
-            // between them so timer-driven cancellation and deadlines can run.
-            await sleep(0, input.signal);
-        }
+        requireNonEmpty(approvalId, 'approvalId');
+        assertOnRetry(input.onRetry);
+        return pollUntilSettled({
+            poll: () => this.wait(approvalId, input.signal ? { signal: input.signal } : {}),
+            validate: (value) => validateApprovalWait(value, approvalId),
+            settled: (approval) => approval.status !== 'pending',
+            expiresAt: (approval) => approval.expires_at,
+            what: `approval ${approvalId}`,
+            minIntervalMs: MIN_WAIT_POLL_INTERVAL_MS,
+            ...(input.signal ? { signal: input.signal } : {}),
+            ...(input.onRetry ? { onRetry: input.onRetry } : {}),
+        });
     }
 }
 /**
@@ -754,18 +871,19 @@ class QuestionsApi {
     constructor(http) {
         this.http = http;
     }
-    /** Ask a Question in a room; returns the pending Question (id + computed expiry). */
+    /**
+     * Ask a Question in a room; returns the pending Question (id + computed
+     * expiry). Pass `resolution_policy: 'all'` to poll the room: everyone asked
+     * votes once, and `results` carries the tally on every read.
+     */
     ask(inviteCode, input) {
         requireNonEmpty(input.prompt, 'prompt');
         assertStructuredData(input.data);
-        const { idempotencyKey, ...body } = input;
-        if (idempotencyKey !== undefined) {
-            requireNonEmpty(idempotencyKey, 'idempotencyKey');
-            assertMaxLength(idempotencyKey, 255, 'idempotencyKey');
-        }
+        assertPollShape(input);
+        const { body, headers } = splitIdempotencyKey(input);
         return this.http.request('POST', `/api/agent/rooms/${enc(inviteCode)}/questions`, {
             body: dropUndefined(body),
-            ...(idempotencyKey !== undefined ? { headers: { 'Idempotency-Key': idempotencyKey } } : {}),
+            ...(headers ? { headers } : {}),
         });
     }
     /** Fetch a Question's current state. */
@@ -783,20 +901,29 @@ class QuestionsApi {
     /**
      * Block until the human answers (or the question expires/cancels), looping
      * wait() under the hood. Returns the resolved Question — inspect `state` and
-     * `answer.value` to branch.
+     * `answer.value` to branch. A poll returns once it closes; its `answer` is the
+     * leading option, or `null` on a tie, and `results` holds the tally.
+     *
+     * Polls start at least 1 s apart. A response that is not this Question in a
+     * known state rejects with `invalid_response`. Network failures, 429 and 5xx
+     * are retried with backoff (honouring `retryAfter`), and reported to
+     * `onRetry`, until `signal` aborts or the outage outlasts the Question's
+     * `expires_at` by 5 minutes (15 minutes of failures while no `expires_at` has
+     * been read); that rejects with `unavailable`. See {@link WaitForOutcomeOptions}.
      */
     async waitForAnswer(questionId, input = {}) {
-        for (;;) {
-            if (input.signal?.aborted) {
-                throw input.signal.reason ?? new Error('aborted');
-            }
-            const question = await this.wait(questionId, input.signal ? { signal: input.signal } : {});
-            if (question.state !== 'pending') {
-                return question;
-            }
-            // Yield between polls so timer-driven cancellation can run (see ApprovalsApi).
-            await sleep(0, input.signal);
-        }
+        requireNonEmpty(questionId, 'questionId');
+        assertOnRetry(input.onRetry);
+        return pollUntilSettled({
+            poll: () => this.wait(questionId, input.signal ? { signal: input.signal } : {}),
+            validate: (value) => validateQuestionWait(value, questionId),
+            settled: (question) => question.state !== 'pending',
+            expiresAt: (question) => question.expires_at,
+            what: `question ${questionId}`,
+            minIntervalMs: MIN_WAIT_POLL_INTERVAL_MS,
+            ...(input.signal ? { signal: input.signal } : {}),
+            ...(input.onRetry ? { onRetry: input.onRetry } : {}),
+        });
     }
     /** List the asker's Questions, optionally filtered by state. */
     async list(input = {}) {
@@ -810,6 +937,21 @@ class QuestionsApi {
         return this.http.request('POST', `/api/agent/questions/${enc(questionId)}/cancel`, { body: {} });
     }
 }
+/**
+ * A poll asks the whole room and counts option votes, so the server refuses it
+ * (422 on `resolution_policy`) alongside a direct scope, a named target, or a
+ * typed answer. Fail before the request instead.
+ */
+function assertPollShape(input) {
+    if (input.resolution_policy !== 'all')
+        return;
+    const target = input.target_user_id;
+    if (input.responder_scope === 'direct'
+        || (target !== undefined && target !== null && target !== '')
+        || (input.text_input !== undefined && input.text_input !== null)) {
+        throw new PingRoomError("A poll (`resolution_policy: 'all'`) asks the whole room with options only; it cannot use `responder_scope: 'direct'`, `target_user_id`, or `text_input`.", { code: 'invalid_request' });
+    }
+}
 /** A bare string option is shorthand for `{ value, label: value }`. */
 function normalizeHandoffOptions(options) {
     return options.map((o) => (typeof o === 'string' ? { value: o, label: o } : o));
@@ -865,20 +1007,28 @@ class HandoffsApi {
      * Block until the handoff resolves (or expires/cancels), looping the bounded
      * long-poll under the hood. `expired`/`cancelled` and a negative answer (e.g.
      * `hold`) all surface as normal terminal results — nothing is thrown for them.
+     *
+     * Polls start at least 2.1 s apart, so a short `timeout` stays under the
+     * route's 30-per-minute limit. A response that is not this handoff in a
+     * known state rejects with `invalid_response`. Network failures, 429 and 5xx
+     * are retried with backoff (honouring `retryAfter`), and reported to
+     * `onRetry`, until `signal` aborts or the outage outlasts the handoff's
+     * `expires_at` by 5 minutes (15 minutes of failures while no `expires_at` has
+     * been read); that rejects with `unavailable`. See {@link WaitForOutcomeOptions}.
      */
     async waitForResult(id, input = {}) {
         requireNonEmpty(id, 'id');
-        for (;;) {
-            if (input.signal?.aborted) {
-                throw input.signal.reason ?? new Error('aborted');
-            }
-            const handoff = await this.wait(id, input);
-            if (isHandoffTerminal(handoff)) {
-                return handoff;
-            }
-            // Yield between polls so timer-driven cancellation can run (see ApprovalsApi).
-            await sleep(0, input.signal);
-        }
+        assertOnRetry(input.onRetry);
+        return pollUntilSettled({
+            poll: () => this.wait(id, input),
+            validate: (value) => validateHandoffWait(value, id),
+            settled: isHandoffTerminal,
+            expiresAt: (handoff) => handoff.expires_at,
+            what: `handoff ${id}`,
+            minIntervalMs: MIN_HANDOFF_POLL_INTERVAL_MS,
+            ...(input.signal ? { signal: input.signal } : {}),
+            ...(input.onRetry ? { onRetry: input.onRetry } : {}),
+        });
     }
     /** List the agent's open handoffs or bounded recent history. */
     async list(input = {}) {
@@ -909,7 +1059,7 @@ class HandoffsApi {
         });
         return this.http.request('POST', '/api/agent/handoffs', {
             body,
-            ...(input.idempotencyKey ? { headers: { 'Idempotency-Key': input.idempotencyKey } } : {}),
+            ...(input.idempotencyKey ? { headers: { 'Idempotency-Key': normalizeIdempotencyKey(input.idempotencyKey) } } : {}),
         });
     }
 }
@@ -963,7 +1113,7 @@ class InboxApi {
                 }), questionId);
                 throwIfAborted(signal);
                 if (question.state === 'pending') {
-                    await sleep(Math.max(0, MIN_INBOX_ACTIVATION_POLL_INTERVAL_MS - (Date.now() - pollStartedAt)), signal);
+                    await sleep(Math.max(0, MIN_HANDOFF_POLL_INTERVAL_MS - (Date.now() - pollStartedAt)), signal);
                     continue;
                 }
                 if (question.state === 'answered' && question.activation_completed === true) {
@@ -1044,11 +1194,11 @@ class LiveApi {
      * Read back a stream this credential started, so a restarted producer can
      * reconcile instead of opening a duplicate.
      *
-     * Resolves null for a 404 ONLY — no stream with that correlation id in the
-     * last 24 hours. Every other failure throws: in particular a 403
-     * `room_not_granted` ({@link RoomScopedErrorCode}), raised when the room is
-     * outside the grant the human gave this agent, propagates rather than being
-     * reported as "no stream".
+     * Resolves null ONLY for a 404 `stream_not_found` — no stream with that
+     * correlation id in the last 24 hours. Every other failure throws: a 404 for
+     * an unknown or deleted room code, and a 403 `room_not_granted`
+     * ({@link RoomScopedErrorCode}) when the room is outside the grant the human
+     * gave this agent, both propagate rather than being reported as "no stream".
      */
     async get(inviteCode, correlationId) {
         requireNonEmpty(inviteCode, 'inviteCode');
@@ -1057,7 +1207,7 @@ class LiveApi {
             return await this.http.request('GET', `/api/agent/rooms/${enc(inviteCode)}/live/${enc(correlationId)}`);
         }
         catch (error) {
-            if (error instanceof PingRoomError && error.status === 404)
+            if (error instanceof PingRoomError && error.status === 404 && error.code === 'stream_not_found')
                 return null;
             throw error;
         }
@@ -1212,12 +1362,26 @@ export class PingRoom {
             body: { code: normalizeRedeemCode(code) },
         });
     }
-    /** Broadcast a ping to every member of a room you own. */
+    /**
+     * Broadcast a ping to every member of a room you own. Pass `idempotencyKey`
+     * and reuse it when retrying after a timeout or network error, so a send
+     * the server already committed is replayed rather than delivered twice.
+     */
     broadcast(inviteCode, ping) {
         assertPing(ping);
+        const { body, headers } = splitIdempotencyKey(ping);
         return this.http.request('POST', `/api/agent/rooms/${enc(inviteCode)}/notifications`, {
-            body: dropUndefined({ ...ping }),
+            body: dropUndefined({ ...body }),
+            ...(headers ? { headers } : {}),
         });
     }
+    /** What a logger or JSON.stringify() sees: the API origin, never the credential. */
+    toJSON() {
+        return this.http.toJSON();
+    }
+    [INSPECT]() {
+        const { baseUrl, token } = this.http.toJSON();
+        return `PingRoom { baseUrl: ${JSON.stringify(baseUrl)}, token: ${token === null ? 'null' : token} }`;
+    }
 }
 //# sourceMappingURL=client.js.map