@pingroom/sdk 0.2.0 → 0.4.0

package/dist/client.js

@@ -1,11 +1,19 @@
+import { PingRoomActivationIncompleteError, PingRoomError } from './errors.js';
 import { HttpClient } from './http.js';
-import { sleep } from './internal/async.js';
+import { combineSignals, sleep } from './internal/async.js';
 import { assertActionNumber, assertStructuredData, requireNonEmpty } 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;
+const DEFAULT_INBOX_ACTIVATION_TIMEOUT_MS = 120_000;
+const MIN_INBOX_ACTIVATION_POLL_INTERVAL_MS = 2100;
 function envBaseUrl() {
     const proc = globalThis.process;
     return proc?.env?.['PINGROOM_API_URL'] || proc?.env?.['PINGROOM_BASE_URL'] || undefined;
@@ -30,6 +38,101 @@ function assertPing(ping) {
 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';
+}
+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;
+}
+function throwIfAborted(signal) {
+    if (signal.aborted) {
+        throw signal.reason ?? new Error('aborted');
+    }
+}
 // --- namespaces -----------------------------------------------------------
 /** Agent credential lifecycle (auth.md flow). */
 class AuthApi {
@@ -53,6 +156,107 @@ class AuthApi {
         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 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.
+     */
+    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 },
+            });
+        }
+        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 deadline = Date.now() + lifetimeMs;
+        let transientFailures = 0;
+        while (Date.now() < deadline) {
+            this.throwIfPairingAborted(options.signal);
+            try {
+                const status = await this.pairingStatus({ signal: options.signal });
+                this.throwIfPairingAborted(options.signal);
+                transientFailures = 0;
+                if (status.status === 'active') {
+                    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))
+                        || !status.room
+                        || 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);
+                    const { status: _status, ...credential } = status;
+                    return 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
+                    && (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',
+        });
+    }
+    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: {} });
@@ -119,6 +323,23 @@ class NotificationsApi {
     list(input = {}) {
         return this.http.request('GET', '/api/agent/notifications', { query: dropUndefined({ ...input }) });
     }
+    /** 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', {
@@ -176,7 +397,11 @@ class AgentsApi {
     constructor(http) {
         this.http = http;
     }
-    /** Direct agent-to-agent ping, addressed by the target's handle. */
+    /**
+     * @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);
@@ -279,6 +504,192 @@ class QuestionsApi {
         return this.http.request('POST', `/api/agent/questions/${enc(questionId)}/cancel`, { body: {} });
     }
 }
+/** 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.
+     */
+    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;
+            }
+        }
+    }
+    /** 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': 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_INBOX_ACTIVATION_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) {
@@ -294,6 +705,102 @@ class ProfileApi {
         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 are never charged, so a
+ * card can never be quota-blocked into hanging open.
+ */
+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. Returns null when there is no
+     * such stream in the last 24 hours.
+     */
+    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)
+                return null;
+            throw error;
+        }
+    }
+}
+/**
+ * Private files that a ping 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.
+ *
+ * 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');
+        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 } : {}),
+        });
+    }
+    /** 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;
@@ -316,9 +823,13 @@ export class PingRoom {
     rooms;
     actions;
     notifications;
+    attachments;
     agents;
     approvals;
     questions;
+    handoffs;
+    inbox;
+    live;
     profile;
     directory;
     mcp;
@@ -337,9 +848,13 @@ export class PingRoom {
         this.rooms = new RoomsApi(this.http);
         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);
+        this.inbox = new InboxApi(this.http);
+        this.live = new LiveApi(this.http);
         this.profile = new ProfileApi(this.http);
         this.directory = new DirectoryApi(this.http);
         this.mcp = new McpClient(this.http);