@pingroom/sdk 0.8.0 → 0.9.0

package/dist/client.js

@@ -1,1310 +1,27 @@
-import { PingRoomActivationIncompleteError, PingRoomError } from './errors.js';
 import { HttpClient } from './http.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 { normalizeRedeemCode } from './internal/guards.js';
 import { McpClient } from './mcp.js';
+import { enc, splitIdempotencyKey, dropUndefined, assertPing } from './internal/request.js';
+import { AuthApi } from './namespaces/auth.js';
+import { RoomsApi } from './namespaces/rooms.js';
+import { ActionsApi } from './namespaces/actions.js';
+import { WebhooksApi } from './namespaces/webhooks.js';
+import { NotificationsApi } from './namespaces/notifications.js';
+import { AttachmentsApi } from './namespaces/attachments.js';
+import { ApprovalsApi } from './namespaces/approvals.js';
+import { QuestionsApi } from './namespaces/questions.js';
+import { HandoffsApi } from './namespaces/handoffs.js';
+import { InboxApi } from './namespaces/inbox.js';
+import { ProfileApi } from './namespaces/profile.js';
+import { LiveApi } from './namespaces/live.js';
+import { DirectoryApi } from './namespaces/directory.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;
-const QUICK_ACTION_PAGE_SIZE = 4;
-const MAX_QUICK_ACTION_PAGES = 4;
-/** 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;
-const DEFAULT_INBOX_ACTIVATION_TIMEOUT_MS = 120_000;
-/**
- * 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)) {
-        if (v !== undefined) {
-            out[k] = v;
-        }
-    }
-    return out;
-}
-/**
- * Mirrors the server's `icon` rule (`present`, `required_with:label`): the emoji
- * is the half that must be there unless BOTH are empty, which reserves the
- * slot as disabled.
- */
-function assertQuickActionIcon(action) {
-    requirePresentString(action.label, 'label');
-    requirePresentString(action.icon, 'icon');
-    if (action.icon.trim() === '' && action.label.trim() !== '') {
-        throw new PingRoomError('`icon` is required when `label` is set; send both empty to disable the slot.', {
-            code: 'invalid_request',
-        });
-    }
-}
-function assertTriggerInput(input) {
-    const data = input.data;
-    if (data !== undefined) {
-        if (data === null || typeof data !== 'object' || Array.isArray(data)) {
-            throw new PingRoomError('`data` must be an object with `location` and/or `url`.', { code: 'invalid_request' });
-        }
-        for (const key of Object.keys(data)) {
-            if (key !== 'location' && key !== 'url') {
-                throw new PingRoomError(`\`data.${key}\` is not accepted on a quick-action press; only location and url are.`, {
-                    code: 'invalid_request',
-                });
-            }
-        }
-        try {
-            if (data.location !== undefined)
-                locationPing(data.location);
-            if (data.url !== undefined)
-                linkPing({ url: data.url });
-        }
-        catch (error) {
-            throw new PingRoomError(error.message, { code: 'invalid_request' });
-        }
-    }
-    if (input.attachment_ids !== undefined) {
-        if (!Array.isArray(input.attachment_ids) || input.attachment_ids.length > MAX_TRIGGER_ATTACHMENTS) {
-            throw new PingRoomError(`\`attachment_ids\` accepts at most ${MAX_TRIGGER_ATTACHMENTS} ids.`, { code: 'invalid_request' });
-        }
-        for (const id of input.attachment_ids)
-            requireNonEmpty(id, 'attachment_ids[]');
-    }
-}
-function attachmentByteLength(content) {
-    if (content instanceof Blob)
-        return content.size;
-    if (typeof content === 'string')
-        return new TextEncoder().encode(content).byteLength;
-    return content.byteLength;
-}
-function assertPing(ping) {
-    requireNonEmpty(ping.message, 'message');
-    // The invite code does not expose room visibility. Permit the public-room
-    // ceiling locally; Laravel applies 120 for private and 160 for public rooms.
-    assertMaxLength(ping.message, MAX_PUBLIC_PING_MESSAGE_LENGTH, 'message');
-    assertMaxLength(ping.title, MAX_PING_TITLE_LENGTH, 'title');
-    assertActionNumber(ping.action_number);
-    assertStructuredData(ping.data);
-}
-function waitTimeoutMs(seconds) {
-    return (seconds ?? DEFAULT_WAIT_SECONDS) * 1000 + LONG_POLL_BUFFER_MS;
-}
-function isRecord(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-function isNonEmptyString(value) {
-    return typeof value === 'string' && value.trim() !== '';
-}
-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 });
-}
-function validateInboxEnsure(value) {
-    if (!isRecord(value) || value['onboarded'] !== true || typeof value['replayed'] !== 'boolean') {
-        return invalidInboxResponse('PingRoom returned an invalid Agent Inbox ensure response.');
-    }
-    const room = value['room'];
-    const question = value['question'];
-    if (!isRecord(room)
-        || !isNonEmptyString(room['id'])
-        || typeof room['name'] !== 'string'
-        || !isNonEmptyString(room['invite_code'])
-        || typeof room['is_agent_inbox'] !== 'boolean'
-        || !isRecord(question)
-        || !isNonEmptyString(question['id'])
-        || question['kind'] !== 'question'
-        || !isNonEmptyString(question['prompt'])
-        || !Array.isArray(question['options'])
-        || question['options'].some((option) => (!isRecord(option)
-            || !isNonEmptyString(option['value'])
-            || !isNonEmptyString(option['label'])))
-        || (question['state'] !== 'pending'
-            && question['state'] !== 'answered'
-            && question['state'] !== 'expired'
-            && question['state'] !== 'cancelled')
-        || !isNullableString(question['expires_at'])
-        || !isNullableString(question['created_at'])) {
-        return invalidInboxResponse('PingRoom returned an incomplete Agent Inbox ensure response.');
-    }
-    return value;
-}
-function validateInboxWait(value, expectedId) {
-    if (!isRecord(value)) {
-        return invalidInboxResponse('PingRoom returned an invalid Agent Inbox wait response.');
-    }
-    const state = value['state'];
-    if (!isNonEmptyString(value['id'])
-        || value['id'] !== expectedId
-        || value['kind'] !== 'question'
-        || (state !== 'pending' && state !== 'answered' && state !== 'expired' && state !== 'cancelled')
-        || (value['activation_completed'] !== undefined && typeof value['activation_completed'] !== 'boolean')
-        || (state !== 'answered' && value['activation_completed'] === true)) {
-        return invalidInboxResponse('PingRoom returned a mismatched Agent Inbox wait response.', {
-            expected_id: expectedId,
-            received_id: typeof value['id'] === 'string' ? value['id'] : null,
-            kind: typeof value['kind'] === 'string' ? value['kind'] : null,
-            state: typeof state === 'string' ? state : null,
-        });
-    }
-    if (state === 'answered') {
-        const answer = value['answer'];
-        if (!isRecord(answer)
-            || !isNullableString(answer['value'])
-            || !isNullableString(answer['label'])
-            || !isNullableString(answer['text'])
-            || (!isNonEmptyString(answer['value']) && !isNonEmptyString(answer['text']))
-            || !isNullableString(answer['answered_at'])
-            || (answer['responder'] !== null && !isRecord(answer['responder']))) {
-            return invalidInboxResponse('PingRoom returned an answered activation without a valid answer.', {
-                id: expectedId,
-                state,
-            });
-        }
-        const responder = answer['responder'];
-        if (isRecord(responder)
-            && (!isNullableString(responder['id']) || !isNullableString(responder['display_name']))) {
-            return invalidInboxResponse('PingRoom returned an invalid activation responder.', {
-                id: expectedId,
-                state,
-            });
-        }
-    }
-    else if (value['answer'] !== undefined && value['answer'] !== null) {
-        return invalidInboxResponse('PingRoom returned an answer for an unresolved activation.', {
-            id: expectedId,
-            state,
-        });
-    }
-    return value;
-}
-/** 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). */
-class AuthApi {
-    http;
-    constructor(http) {
-        this.http = http;
-    }
-    /** Register an agent. Anonymous or via an identity assertion (ID-JAG / verified email). Public. */
-    register(params) {
-        requireNonEmpty(params.type, 'type');
-        return this.http.request('POST', '/api/agent/auth', { auth: false, body: dropUndefined({ ...params }) });
-    }
-    /** Begin claiming a pre-claim credential onto a human account; emails an OTP. */
-    claimStart(params) {
-        requireNonEmpty(params.email, 'email');
-        return this.http.request('POST', '/api/agent/auth/claim/start', { body: { email: params.email } });
-    }
-    /** Complete the claim with the emailed OTP; returns an active credential + handle. */
-    claimComplete(params) {
-        requireNonEmpty(params.email, 'email');
-        requireNonEmpty(params.otp, 'otp');
-        return this.http.request('POST', '/api/agent/auth/claim/complete', { body: dropUndefined({ ...params }) });
-    }
-    /**
-     * Register a pending agent and create a short-lived link that opens the
-     * 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 previousToken = this.http.getToken();
-        const pending = await this.register({
-            type: 'anonymous',
-            ...(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: {},
-            });
-        }
-        catch (error) {
-            if (this.http.getToken() === pending.credential) {
-                this.http.setToken(previousToken);
-            }
-            throw error;
-        }
-    }
-    /** Read the current state of an app pairing using the pending credential. */
-    pairingStatus(options = {}) {
-        return this.http.request('GET', '/api/agent/auth/pair/status', { signal: options.signal });
-    }
-    /**
-     * Wait until the person approves in PingRoom, or the short-lived link
-     * expires. Transient network, 429, and 5xx failures are retried inside the
-     * server-provided lifetime. On success the client immediately starts using
-     * the active credential returned by the server.
-     */
-    async waitForPairing(pairing, options = {}) {
-        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 startedAt = Date.now();
-        const deadline = startedAt + lifetimeMs;
-        let transientFailures = 0;
-        while (Date.now() < deadline) {
-            throwIfAborted(options.signal);
-            try {
-                const status = await this.pairingStatus({ signal: options.signal });
-                throwIfAborted(options.signal);
-                transientFailures = 0;
-                if (status.status === 'active') {
-                    if (typeof status.credential !== 'string'
-                        || status.credential.trim() === ''
-                        || status.credential_type !== 'active'
-                        || (status.expires_in !== null
-                            && (typeof status.expires_in !== 'number'
-                                || !Number.isFinite(status.expires_in)
-                                || status.expires_in < 0))
-                        // 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() === ''))) {
-                        throw new PingRoomError('PingRoom returned an incomplete approved pairing.', {
-                            code: 'pairing_invalid_response',
-                            body: { status: status.status },
-                        });
-                    }
-                    this.http.setToken(status.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.', {
-                        code: 'pairing_expired',
-                    });
-                }
-            }
-            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'
-                        || error.status === 429
-                        || error.status >= 500)) {
-                    transientFailures += 1;
-                    const backoffMs = Math.min(intervalMs * 2 ** Math.max(0, transientFailures - 3), 30_000);
-                    await sleep(Math.max(0, Math.min(backoffMs, deadline - Date.now())), options.signal);
-                    continue;
-                }
-                throw error;
-            }
-            await sleep(Math.max(0, Math.min(intervalMs, deadline - Date.now())), options.signal);
-        }
-        throw new PingRoomError('The PingRoom pairing link expired before it was approved.', {
-            code: 'pairing_expired',
-        });
-    }
-    /** Rotate to a fresh credential (same scopes/handle). */
-    refresh() {
-        return this.http.request('POST', '/api/agent/auth/refresh', { body: {} });
-    }
-    /** Revoke the current credential. */
-    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;
-    constructor(http) {
-        this.http = http;
-    }
-    icons() {
-        return this.http.request('GET', '/api/agent/room-icons');
-    }
-    list() {
-        return this.http.request('GET', '/api/agent/rooms');
-    }
-    get(inviteCode) {
-        return this.http.request('GET', `/api/agent/rooms/${enc(inviteCode)}`);
-    }
-    create(input) {
-        requireNonEmpty(input.name, 'name');
-        return this.http.request('POST', '/api/agent/rooms', { body: dropUndefined({ ...input }) });
-    }
-    createPublic(input) {
-        requireNonEmpty(input.name, 'name');
-        requireNonEmpty(input.handle, 'handle');
-        // The server takes the location trio all-or-nothing; a partial set is a
-        // 422 on a field the caller may not have meant to send at all.
-        const present = [input.location_name, input.location_latitude, input.location_longitude].filter((v) => v !== undefined).length;
-        if (present !== 0 && present !== 3) {
-            throw new PingRoomError('Send `location_name`, `location_latitude` and `location_longitude` together, or none of them.', {
-                code: 'invalid_request',
-            });
-        }
-        return this.http.request('POST', '/api/agent/rooms/public', { body: dropUndefined({ ...input }) });
-    }
-    join(input) {
-        requireNonEmpty(input.invite_code, 'invite_code');
-        return this.http.request('POST', '/api/agent/rooms/join', { body: dropUndefined({ ...input }) });
-    }
-}
-class ActionsApi {
-    http;
-    constructor(http) {
-        this.http = http;
-    }
-    list(inviteCode) {
-        return this.http.request('GET', `/api/agent/rooms/${enc(inviteCode)}/actions`);
-    }
-    update(inviteCode, actionNumber, input) {
-        assertActionNumber(actionNumber);
-        // A Ping's title is optional — its emoji can be the whole name — so an
-        // empty `label` is a valid update. `icon` is the half that must be there,
-        // unless both are empty: that reserves the slot as disabled.
-        assertQuickActionIcon(input);
-        return this.http.request('PUT', `/api/agent/rooms/${enc(inviteCode)}/actions/${actionNumber}`, {
-            body: dropUndefined({ ...input }),
-        });
-    }
-    /**
-     * Write up to 16 action slots in one request. The server enforces the room owner's plan.
-     * Add new pages in complete groups of four; existing slots may be edited individually.
-     *
-     * 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 room members' devices 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 > 16) {
-            throw new PingRoomError('A batch may contain at most 16 action slots.', { code: 'invalid_request' });
-        }
-        assertActionSlots(actions);
-        return this.http.request('PUT', `/api/agent/rooms/${enc(inviteCode)}/actions`, {
-            body: { actions: actions.map((action) => dropUndefined({ ...action })) },
-        });
-    }
-    /**
-     * Press a slot. When the action has an `input_type`, pass the matching
-     * detail (`data.location`, `data.url`, or `attachment_ids`) or the server
-     * refuses the press with `422 quick_action_input_required` and sends nothing.
-     * Read `input_type` from `list()` first; pass the action's `id` as
-     * `quick_action_id` to be refused rather than fire the wrong Ping if the
-     * owner moved pages meanwhile.
-     */
-    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({ ...body }),
-            ...(headers ? { headers } : {}),
-        });
-    }
-    /**
-     * Replace the room's page layout atomically (room owner on Pro only). See
-     * `UpdateQuickActionLayoutInput` for the snapshot contract; a stale
-     * `base_action_ids` is `409 quick_action_layout_changed`, a page still used
-     * by a time trigger, webhook, agent binding or running live update is
-     * `409 quick_action_page_in_use`. Prefer `deletePage()`, which builds the
-     * body from a fresh read.
-     */
-    updateLayout(inviteCode, input) {
-        if (!Array.isArray(input.base_action_ids)) {
-            throw new PingRoomError('`base_action_ids` must be an array of action ids (may be empty).', { code: 'invalid_request' });
-        }
-        if (!Array.isArray(input.page_order) || input.page_order.length < 1 || input.page_order.length > MAX_QUICK_ACTION_PAGES) {
-            throw new PingRoomError(`\`page_order\` must list 1–${MAX_QUICK_ACTION_PAGES} pages.`, { code: 'invalid_request' });
-        }
-        for (const page of input.page_order) {
-            if (page !== null && (!Number.isInteger(page) || page < 1 || page > MAX_QUICK_ACTION_PAGES)) {
-                throw new PingRoomError('`page_order` entries must be an original page number 1–4 or null for a blank page.', {
-                    code: 'invalid_request',
-                });
-            }
-        }
-        const expected = input.page_order.length * QUICK_ACTION_PAGE_SIZE;
-        if (!Array.isArray(input.actions) || input.actions.length !== expected) {
-            throw new PingRoomError(`\`actions\` must hold exactly ${expected} slots for ${input.page_order.length} page(s).`, {
-                code: 'invalid_request',
-            });
-        }
-        assertActionSlots(input.actions);
-        return this.http.request('PUT', `/api/agent/rooms/${enc(inviteCode)}/actions/layout`, {
-            body: {
-                base_action_ids: input.base_action_ids,
-                page_order: input.page_order,
-                actions: input.actions.map((action) => dropUndefined({ ...action })),
-            },
-        });
-    }
-    /**
-     * Delete one page (1–4) and shift the later pages left, keeping every other
-     * slot's configuration. Reads the current action set first so the layout
-     * snapshot is real, then calls `updateLayout()`. Page 1 can be deleted only
-     * when another page remains.
-     */
-    async deletePage(inviteCode, page) {
-        if (!Number.isInteger(page) || page < 1 || page > MAX_QUICK_ACTION_PAGES) {
-            throw new PingRoomError('`page` must be an integer 1–4.', { code: 'invalid_request' });
-        }
-        const current = await this.list(inviteCode);
-        const stored = [...current].sort((a, b) => a.action_number - b.action_number);
-        const pageCount = Math.max(1, Math.ceil((stored.at(-1)?.action_number ?? 0) / QUICK_ACTION_PAGE_SIZE));
-        if (page > pageCount) {
-            throw new PingRoomError(`The room has ${pageCount} page(s); page ${page} does not exist.`, { code: 'invalid_request' });
-        }
-        if (pageCount === 1) {
-            throw new PingRoomError('A room keeps at least one page; configure its slots instead of deleting it.', {
-                code: 'invalid_request',
-            });
-        }
-        const keep = Array.from({ length: pageCount }, (_, i) => i + 1).filter((p) => p !== page);
-        const byNumber = new Map(stored.map((a) => [a.action_number, a]));
-        const actions = [];
-        keep.forEach((originalPage, index) => {
-            for (let offset = 1; offset <= QUICK_ACTION_PAGE_SIZE; offset++) {
-                const source = byNumber.get((originalPage - 1) * QUICK_ACTION_PAGE_SIZE + offset);
-                actions.push({
-                    action_number: index * QUICK_ACTION_PAGE_SIZE + offset,
-                    label: source?.label ?? '',
-                    icon: source?.icon ?? '',
-                    ...(source?.sound !== undefined ? { sound: source.sound } : {}),
-                    ...(source?.haptic_style !== undefined ? { haptic_style: source.haptic_style } : {}),
-                    ...(source?.requires_ack !== undefined ? { requires_ack: source.requires_ack } : {}),
-                    ...(source?.input_type !== undefined ? { input_type: source.input_type } : {}),
-                });
-            }
-        });
-        return this.updateLayout(inviteCode, {
-            base_action_ids: stored.map((a) => a.id).filter((id) => typeof id === 'string'),
-            page_order: keep,
-            actions,
-        });
-    }
-}
-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. */
-    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) {
-        requireNonEmpty(notificationId, 'notificationId');
-        return this.http.request('GET', `/api/agent/notifications/${enc(notificationId)}`);
-    }
-    /**
-     * One bounded long-poll for an ack-required ping. The returned state may
-     * still be `open` when the hold timeout elapses; call again to keep waiting.
-     */
-    waitForAcknowledgement(notificationId, input = {}) {
-        requireNonEmpty(notificationId, 'notificationId');
-        return this.http.request('GET', `/api/agent/notifications/${enc(notificationId)}/ack/wait`, {
-            query: dropUndefined({ timeout: input.timeout }),
-            timeoutMs: waitTimeoutMs(input.timeout),
-            ...(input.signal ? { signal: input.signal } : {}),
-        });
-    }
-    /** One long-poll: resolves as soon as new pings land, or with an empty list at timeout. */
-    wait(input = {}) {
-        return this.http.request('GET', '/api/agent/notifications/wait', {
-            query: dropUndefined({ after: input.after, timeout: input.timeout, limit: input.limit }),
-            timeoutMs: waitTimeoutMs(input.timeout),
-            ...(input.signal ? { signal: input.signal } : {}),
-        });
-    }
-    /**
-     * Continuous real-time inbound: an async iterator that long-polls in a loop,
-     * advancing the cursor, yielding each new ping. Stops when `signal` aborts.
-     *
-     *   for await (const ping of pr.notifications.listen({ signal })) { ... }
-     */
-    async *listen(input = {}) {
-        let cursor = input.after;
-        let headRead = cursor !== undefined;
-        const backoffMs = input.backoffMs ?? 1000;
-        let failures = 0;
-        while (!input.signal?.aborted) {
-            let result;
-            try {
-                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;
-                }
-                // A revoked credential or a bad request never heals; only network
-                // failures, deadlines, 429 and 5xx are retried.
-                if (!isTransientError(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;
-            }
-            // Yield between polls so timer-driven cancellation can run (see ApprovalsApi).
-            await sleep(0, input.signal);
-        }
-    }
-}
-class AgentsApi {
-    http;
-    constructor(http) {
-        this.http = http;
-    }
-    /**
-     * @deprecated Retired server-side — always fails with 410
-     * `cross_account_ping_retired`. An agent can only reach the account that
-     * connected it; to reach anyone else, post into a room you both belong to.
-     */
-    ping(handle, ping) {
-        requireNonEmpty(handle, 'handle');
-        assertPing(ping);
-        const { body, headers } = splitIdempotencyKey(ping);
-        return this.http.request('POST', `/api/agent/agents/${enc(handle)}/ping`, {
-            body: dropUndefined({ ...body }),
-            ...(headers ? { headers } : {}),
-        });
-    }
-}
-class ApprovalsApi {
-    http;
-    constructor(http) {
-        this.http = http;
-    }
-    /** Ask the human you act for to decide; returns the pending approval. */
-    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({ ...body }),
-            ...(headers ? { headers } : {}),
-        });
-    }
-    get(approvalId) {
-        return this.http.request('GET', `/api/agent/approvals/${enc(approvalId)}`);
-    }
-    /** One long-poll for the decision; returns the (possibly still-pending) approval. */
-    wait(approvalId, input = {}) {
-        return this.http.request('GET', `/api/agent/approvals/${enc(approvalId)}/wait`, {
-            query: dropUndefined({ timeout: input.timeout }),
-            timeoutMs: waitTimeoutMs(input.timeout),
-            ...(input.signal ? { signal: input.signal } : {}),
-        });
-    }
-    /**
-     * 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 = {}) {
-        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 } : {}),
-        });
-    }
-}
-/**
- * The general human-in-the-loop primitive: ask a human a question with 2–4
- * options (or a short typed answer) and block until they tap an answer. An
- * {@link ApprovalsApi | approval} is the two-option case; reach for questions
- * when you need more choices, a typed reply, or room-scope answering.
- */
-class QuestionsApi {
-    http;
-    constructor(http) {
-        this.http = http;
-    }
-    /**
-     * 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);
-        assertPollShape(input);
-        const { body, headers } = splitIdempotencyKey(input);
-        return this.http.request('POST', `/api/agent/rooms/${enc(inviteCode)}/questions`, {
-            body: dropUndefined(body),
-            ...(headers ? { headers } : {}),
-        });
-    }
-    /** Fetch a Question's current state. */
-    get(questionId) {
-        return this.http.request('GET', `/api/agent/questions/${enc(questionId)}`);
-    }
-    /** One long-poll for the answer; returns the (possibly still-pending) Question. */
-    wait(questionId, input = {}) {
-        return this.http.request('GET', `/api/agent/questions/${enc(questionId)}/wait`, {
-            query: dropUndefined({ timeout: input.timeout }),
-            timeoutMs: waitTimeoutMs(input.timeout),
-            ...(input.signal ? { signal: input.signal } : {}),
-        });
-    }
-    /**
-     * 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. 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 = {}) {
-        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 = {}) {
-        const res = await this.http.request('GET', '/api/agent/questions', {
-            query: dropUndefined({ state: input.state }),
-        });
-        return res.questions ?? [];
-    }
-    /** Withdraw a still-pending Question (409 if it already resolved). */
-    cancel(questionId) {
-        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));
-}
-/** Terminal states never change again — the wait loop can stop as soon as one lands. */
-function isHandoffTerminal(handoff) {
-    const s = handoff.state;
-    return s === 'acked' || s === 'answered' || s === 'expired' || s === 'cancelled';
-}
-/**
- * The Handoff façade: the Agent → one-human loop. Always DIRECT (exactly one
- * human) and PRIVATE (no other room member can read it). Backed by the ack and
- * question primitives, so its {@link Handoff.state | state} space is their union
- * — kept DISTINCT per {@link Handoff.kind | kind}. A negative answer to a
- * question handoff (e.g. `hold`) is a SUCCESSFUL `answered` result, not an error.
- *
- *   const task = await pr.handoffs.requestAck({ prompt, idempotencyKey });
- *   const result = await pr.handoffs.waitForResult(task.id);
- *
- *   const q = await pr.handoffs.ask({ prompt, options: ['deploy', 'hold'], idempotencyKey });
- */
-class HandoffsApi {
-    http;
-    constructor(http) {
-        this.http = http;
-    }
-    /** Ask a human to acknowledge (an `ack` handoff). Resolves on the first acknowledgement. */
-    requestAck(input) {
-        requireNonEmpty(input.prompt, 'prompt');
-        assertStructuredData(input.data);
-        return this.create('ack', input);
-    }
-    /**
-     * Ask a human a multi-option question (a `question` handoff). Resolves on the
-     * first tapped answer. Bare-string options normalize to `{ value, label }`.
-     */
-    ask(input) {
-        requireNonEmpty(input.prompt, 'prompt');
-        assertStructuredData(input.data);
-        if (!Array.isArray(input.options) || input.options.length < 2 || input.options.length > 4) {
-            throw new PingRoomError('`options` must contain between 2 and 4 entries for a question handoff.', {
-                code: 'invalid_request',
-            });
-        }
-        return this.create('question', input, normalizeHandoffOptions(input.options));
-    }
-    /** Fetch a handoff's current state. */
-    get(id) {
-        requireNonEmpty(id, 'id');
-        return this.http.request('GET', `/api/agent/handoffs/${enc(id)}`);
-    }
-    /**
-     * 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');
-        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 = {}) {
-        const res = await this.http.request('GET', '/api/agent/handoffs', {
-            query: dropUndefined({ state: input.state }),
-        });
-        return res.handoffs ?? [];
-    }
-    /** One bounded long-poll; returns the (possibly still-open) handoff. */
-    wait(id, input) {
-        return this.http.request('GET', `/api/agent/handoffs/${enc(id)}/wait`, {
-            query: dropUndefined({ timeout: input.timeout }),
-            timeoutMs: waitTimeoutMs(input.timeout),
-            ...(input.signal ? { signal: input.signal } : {}),
-        });
-    }
-    create(kind, input, options) {
-        const body = dropUndefined({
-            kind,
-            prompt: input.prompt,
-            audience: { type: 'direct', user_id: input.target ?? 'me' },
-            expires_in: input.expiresIn,
-            urgency: input.urgency,
-            options,
-            correlation_id: input.correlationId,
-            reply_to: input.replyTo,
-            data: input.data,
-        });
-        return this.http.request('POST', '/api/agent/handoffs', {
-            body,
-            ...(input.idempotencyKey ? { headers: { 'Idempotency-Key': normalizeIdempotencyKey(input.idempotencyKey) } } : {}),
-        });
-    }
-}
-/** Setup and activation of the bound human's Agent Inbox delivery room. */
-class InboxApi {
-    http;
-    constructor(http) {
-        this.http = http;
-    }
-    /** Replay the viable activation attempt or create its next numbered retry. */
-    ensure(input = {}) {
-        return this.http.request('POST', '/api/agent/inbox/ensure', {
-            body: {},
-            ...(input.signal ? { signal: input.signal } : {}),
-        });
-    }
-    /**
-     * Ensure the bound human's Agent Inbox, then block on its onboarding
-     * Question until the server confirms activation, it expires/cancels, or the
-     * overall deadline elapses. Pairing remains a separate operation so adopting
-     * a credential never silently waits for a phone response.
-     */
-    async activate(input = {}) {
-        const overallTimeoutMs = input.overallTimeoutMs ?? DEFAULT_INBOX_ACTIVATION_TIMEOUT_MS;
-        if (!Number.isFinite(overallTimeoutMs) || overallTimeoutMs < 0) {
-            throw new PingRoomError('`overallTimeoutMs` must be a non-negative finite number.', {
-                code: 'invalid_request',
-            });
-        }
-        const deadlineError = () => (new PingRoomActivationIncompleteError('deadline_exceeded', 'Agent Inbox activation did not complete before the overall deadline.', { overall_timeout_ms: overallTimeoutMs }));
-        const deadlineController = new AbortController();
-        const deadlineTimer = overallTimeoutMs === 0
-            ? null
-            : setTimeout(() => deadlineController.abort(deadlineError()), overallTimeoutMs);
-        if (overallTimeoutMs === 0)
-            deadlineController.abort(deadlineError());
-        const signal = input.signal
-            ? combineSignals(input.signal, deadlineController.signal)
-            : deadlineController.signal;
-        try {
-            throwIfAborted(signal);
-            const ensured = validateInboxEnsure(await this.ensure({ signal }));
-            const questionId = ensured.question.id;
-            for (;;) {
-                throwIfAborted(signal);
-                const pollStartedAt = Date.now();
-                const question = validateInboxWait(await this.http.request('GET', `/api/agent/handoffs/${enc(questionId)}/wait`, {
-                    query: dropUndefined({ timeout: input.timeout }),
-                    timeoutMs: waitTimeoutMs(input.timeout),
-                    signal,
-                }), questionId);
-                throwIfAborted(signal);
-                if (question.state === 'pending') {
-                    await sleep(Math.max(0, MIN_HANDOFF_POLL_INTERVAL_MS - (Date.now() - pollStartedAt)), signal);
-                    continue;
-                }
-                if (question.state === 'answered' && question.activation_completed === true) {
-                    return {
-                        ...ensured,
-                        activation_completed: true,
-                        question: question,
-                    };
-                }
-                if (question.state === 'answered') {
-                    throw new PingRoomActivationIncompleteError('answered_without_completion', 'The onboarding Question was answered without verified native phone receipt before the answer.', { question_id: questionId, activation_completed: question.activation_completed ?? null });
-                }
-                if (question.state === 'expired' || question.state === 'cancelled') {
-                    throw new PingRoomActivationIncompleteError(question.state, `The onboarding Question ${question.state} before Agent Inbox activation completed.`, { question_id: questionId, activation_completed: question.activation_completed ?? null });
-                }
-                return invalidInboxResponse('PingRoom returned an invalid terminal activation state.', {
-                    id: questionId,
-                    state: question.state,
-                });
-            }
-        }
-        catch (error) {
-            // A custom fetch implementation may reject with a generic AbortError
-            // instead of the signal's richer reason. Preserve caller cancellation
-            // and the activation-specific deadline error at this public boundary.
-            throwIfAborted(signal);
-            throw error;
-        }
-        finally {
-            if (deadlineTimer !== null)
-                clearTimeout(deadlineTimer);
-        }
-    }
-}
-class ProfileApi {
-    http;
-    constructor(http) {
-        this.http = http;
-    }
-    /**
-     * Set this agent's own avatar (from the bot avatar set) — the robot face
-     * its pings and Questions wear. Never touches the bound human's profile
-     * picture. Returns `{ ok, avatar_id, avatar_url }`.
-     */
-    setAvatar(avatarId) {
-        requireNonEmpty(avatarId, 'avatarId');
-        return this.http.request('POST', '/api/agent/profile/avatar', { body: { avatar_id: avatarId } });
-    }
-    /** Rotate the agent's handle — the kill-switch for a leaked handle. */
-    rotateHandle() {
-        return this.http.request('POST', '/api/agent/profile/handle/rotate', { body: {} });
-    }
-}
-/**
- * Live-status streams — a self-updating card on the room members' lock screen.
- *
- * Requires the `pingroom:live:write` scope. Free accounts get a small daily
- * budget of NEW streams; updates and the terminal ping of an open stream are
- * never charged, so a card can never be quota-blocked into hanging open. A
- * first ping that is already `done`/`failed` is a new stream and is charged.
- */
-class LiveApi {
-    http;
-    constructor(http) {
-        this.http = http;
-    }
-    /**
-     * Send one stream ping — start, update, or end, chosen by `live_status.state`
-     * and whether the correlation already exists.
-     */
-    push(inviteCode, ping) {
-        requireNonEmpty(inviteCode, 'inviteCode');
-        requireNonEmpty(ping.correlation_id, 'correlation_id');
-        assertStructuredData(ping.data);
-        return this.http.request('POST', `/api/agent/rooms/${enc(inviteCode)}/live`, { body: ping });
-    }
-    /**
-     * Read back a stream this credential started, so a restarted producer can
-     * reconcile instead of opening a duplicate.
-     *
-     * 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');
-        requireNonEmpty(correlationId, 'correlationId');
-        try {
-            return await this.http.request('GET', `/api/agent/rooms/${enc(inviteCode)}/live/${enc(correlationId)}`);
-        }
-        catch (error) {
-            if (error instanceof PingRoomError && error.status === 404 && error.code === 'stream_not_found')
-                return null;
-            throw error;
-        }
-    }
-}
-/**
- * Private files that a Ping or Question can carry.
- *
- * Upload first, then pass the returned ids to `broadcast()` / `questions.ask()`
- * as `attachment_ids`. Bytes never travel over MCP or a JSON ping body. An
- * upload that is never attached expires on its own after 24 hours.
- * Each file must be 1 byte–5 MiB with an md/pdf/html/txt/jpg/jpeg/png/zip filename;
- * a Ping or Question accepts at most four ids.
- *
- * Uploading requires the bound account to hold Pro (the API answers 402
- * `pro_required` otherwise). Reading and deleting are not gated.
- */
-class AttachmentsApi {
-    http;
-    constructor(http) {
-        this.http = http;
-    }
-    /** Upload one file and get back the id a send can claim. */
-    upload(input) {
-        requireNonEmpty(input.filename, 'filename');
-        // The server answers an oversized body with 413 before reading it; refuse
-        // locally so no bytes travel for a file that can never be accepted.
-        if (attachmentByteLength(input.content) > ATTACHMENT_MAX_BYTES) {
-            return Promise.reject(new PingRoomError('Attachments are at most 5 MiB each.', { code: 'attachment_too_large', status: 413 }));
-        }
-        const body = new FormData();
-        body.append('file', toAttachmentBlob(input), input.filename);
-        return this.http
-            .request('POST', '/api/agent/attachments', {
-            body,
-            ...(input.signal ? { signal: input.signal } : {}),
-        })
-            .then((res) => res.attachment);
-    }
-    /**
-     * Raw bytes for an attachment this credential is allowed to see. Returns the
-     * undecoded Response so a caller can stream it, or read text/arrayBuffer.
-     */
-    content(attachmentId, signal) {
-        requireNonEmpty(attachmentId, 'attachmentId');
-        return this.http.raw('GET', `/api/agent/attachments/${enc(attachmentId)}/content`, {
-            ...(signal ? { signal } : {}),
-        });
-    }
-    /**
-     * The listing of a `.zip`'s contents, recorded when it was uploaded.
-     *
-     * Resolves null for a non-archive, and for an archive whose central
-     * directory did not parse. Nothing decompresses the file to produce this, so
-     * the declared sizes are what the archive claims, not verified output.
-     */
-    manifest(attachmentId, signal) {
-        requireNonEmpty(attachmentId, 'attachmentId');
-        return this.http
-            .request('GET', `/api/agent/attachments/${enc(attachmentId)}/manifest`, { ...(signal ? { signal } : {}) })
-            .then((res) => res.manifest ?? null);
-    }
-    /** Discard an upload that has not been attached to a ping yet. */
-    delete(attachmentId) {
-        requireNonEmpty(attachmentId, 'attachmentId');
-        return this.http.request('DELETE', `/api/agent/attachments/${enc(attachmentId)}`);
-    }
-}
-/** Normalise the three accepted content shapes into one multipart part. */
-function toAttachmentBlob(input) {
-    const type = input.contentType ?? '';
-    if (input.content instanceof Blob) {
-        return type ? new Blob([input.content], { type }) : input.content;
-    }
-    // Copy into a plain ArrayBuffer: a Uint8Array view may be a window onto a
-    // larger (or SharedArrayBuffer-backed) buffer, which Blob would not accept.
-    const parts = typeof input.content === 'string'
-        ? [input.content]
-        : [new Uint8Array(input.content).slice().buffer];
-    return new Blob(parts, type ? { type } : undefined);
-}
-/** Public, unauthenticated agent directory. */
-class DirectoryApi {
-    http;
-    constructor(http) {
-        this.http = http;
-    }
-    list(input = {}) {
-        return this.http.request('GET', '/api/agents/directory', {
-            auth: false,
-            query: dropUndefined({ ...input }),
-        });
-    }
-    get(handle) {
-        return this.http.request('GET', `/api/agents/directory/${enc(handle)}`, { auth: false });
-    }
-}
 // --- main client ----------------------------------------------------------
 export class PingRoom {
     auth;
@@ -1313,7 +30,6 @@ export class PingRoom {
     actions;
     notifications;
     attachments;
-    agents;
     approvals;
     questions;
     handoffs;
@@ -1339,7 +55,6 @@ export class PingRoom {
         this.actions = new ActionsApi(this.http);
         this.notifications = new NotificationsApi(this.http);
         this.attachments = new AttachmentsApi(this.http);
-        this.agents = new AgentsApi(this.http);
         this.approvals = new ApprovalsApi(this.http);
         this.questions = new QuestionsApi(this.http);
         this.handoffs = new HandoffsApi(this.http);