@pingroom/sdk 0.7.1 → 0.9.0

package/dist/namespaces/handoffs.d.ts

@@ -0,0 +1,47 @@
+import type { HttpClient } from '../http.js';
+import type { AskInput, Handoff, ListHandoffsInput, RequestAckInput, WaitHandoffInput, WaitForOutcomeOptions } from '../types.js';
+/**
+ * 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 });
+ */
+export declare class HandoffsApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Ask a human to acknowledge (an `ack` handoff). Resolves on the first acknowledgement. */
+    requestAck(input: RequestAckInput): Promise<Handoff>;
+    /**
+     * 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: AskInput): Promise<Handoff>;
+    /** Fetch a handoff's current state. */
+    get(id: string): Promise<Handoff>;
+    /**
+     * 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}.
+     */
+    waitForResult(id: string, input?: WaitHandoffInput & WaitForOutcomeOptions): Promise<Handoff>;
+    /** List the agent's open handoffs or bounded recent history. */
+    list(input?: ListHandoffsInput): Promise<Handoff[]>;
+    /** One bounded long-poll; returns the (possibly still-open) handoff. */
+    private wait;
+    private create;
+}
+//# sourceMappingURL=handoffs.d.ts.map

package/dist/namespaces/handoffs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoffs.d.ts","sourceRoot":"","sources":["../../src/namespaces/handoffs.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAO7C,OAAO,KAAK,EACV,QAAQ,EACR,OAAO,EAGP,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACtB,MAAM,aAAa,CAAC;AA+BrB;;;;;;;;;;;GAWG;AACH,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAE7C,4FAA4F;IAC5F,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC;IAMpD;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAWtC,uCAAuC;IACvC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAKjC;;;;;;;;;;;;OAYG;IACG,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,GAAE,gBAAgB,GAAG,qBAA0B,GAAG,OAAO,CAAC,OAAO,CAAC;IAevG,gEAAgE;IAC1D,IAAI,CAAC,KAAK,GAAE,iBAAsB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAO7D,wEAAwE;IACxE,OAAO,CAAC,IAAI;IAQZ,OAAO,CAAC,MAAM;CAqBf"}

package/dist/namespaces/handoffs.js

@@ -0,0 +1,126 @@
+// `pr.handoffs`: the direct, private agent-to-human loop.
+import { PingRoomError } from '../errors.js';
+import { assertStructuredData, normalizeIdempotencyKey, requireNonEmpty, } from '../internal/guards.js';
+import { pollUntilSettled } from '../internal/retry.js';
+import { MIN_HANDOFF_POLL_INTERVAL_MS, enc, assertOnRetry, dropUndefined, waitTimeoutMs, } from '../internal/request.js';
+import { isRecord, sameId, invalidWaitResponse } from '../internal/validate.js';
+const HANDOFF_STATES = new Set(['open', 'acked', 'pending', 'answered', 'expired', 'cancelled']);
+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;
+}
+/** 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 });
+ */
+export 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) } } : {}),
+        });
+    }
+}
+//# sourceMappingURL=handoffs.js.map

package/dist/namespaces/handoffs.js.map

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

package/dist/namespaces/inbox.d.ts

@@ -0,0 +1,17 @@
+import type { HttpClient } from '../http.js';
+import type { AgentInboxEnsureResult, AgentInboxActivateInput, AgentInboxActivationResult, AgentInboxEnsureInput } from '../types.js';
+/** Setup and activation of the bound human's Agent Inbox delivery room. */
+export declare class InboxApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Replay the viable activation attempt or create its next numbered retry. */
+    ensure(input?: AgentInboxEnsureInput): Promise<AgentInboxEnsureResult>;
+    /**
+     * 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.
+     */
+    activate(input?: AgentInboxActivateInput): Promise<AgentInboxActivationResult>;
+}
+//# sourceMappingURL=inbox.d.ts.map

package/dist/namespaces/inbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox.d.ts","sourceRoot":"","sources":["../../src/namespaces/inbox.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,OAAO,KAAK,EACV,sBAAsB,EACtB,uBAAuB,EAEvB,0BAA0B,EAC1B,qBAAqB,EAEtB,MAAM,aAAa,CAAC;AA8GrB,2EAA2E;AAC3E,qBAAa,QAAQ;IACP,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAE7C,8EAA8E;IAC9E,MAAM,CAAC,KAAK,GAAE,qBAA0B,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAO1E;;;;;OAKG;IACG,QAAQ,CAAC,KAAK,GAAE,uBAA4B,GAAG,OAAO,CAAC,0BAA0B,CAAC;CA+GzF"}

package/dist/namespaces/inbox.js

@@ -0,0 +1,192 @@
+// `pr.inbox`: setting up and activating the human's Agent Inbox.
+import { PingRoomActivationIncompleteError, PingRoomError } from '../errors.js';
+import { combineSignals, sleep, throwIfAborted } from '../internal/async.js';
+import { isTransientError, transientDelayMs } from '../internal/retry.js';
+import { MIN_HANDOFF_POLL_INTERVAL_MS, enc, dropUndefined, waitTimeoutMs, } from '../internal/request.js';
+import { isRecord, isNonEmptyString, isNullableString } from '../internal/validate.js';
+const DEFAULT_INBOX_ACTIVATION_TIMEOUT_MS = 120_000;
+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;
+}
+/** Setup and activation of the bound human's Agent Inbox delivery room. */
+export 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;
+            let failures = 0;
+            for (;;) {
+                throwIfAborted(signal);
+                const pollStartedAt = Date.now();
+                let question;
+                try {
+                    question = validateInboxWait(await this.http.request('GET', `/api/agent/handoffs/${enc(questionId)}/wait`, {
+                        query: dropUndefined({ timeout: input.timeout }),
+                        timeoutMs: waitTimeoutMs(input.timeout),
+                        signal,
+                    }), questionId);
+                }
+                catch (error) {
+                    // A dropped connection, a request deadline, a 429 (each wait route
+                    // has its own 30/min bucket per human) or a 5xx is not an outcome:
+                    // retry it like every other wait, inside the overall deadline.
+                    // Anything else is permanent and surfaces.
+                    throwIfAborted(signal);
+                    if (!isTransientError(error)) {
+                        throw error;
+                    }
+                    failures += 1;
+                    await sleep(Math.max(transientDelayMs(error, failures), MIN_HANDOFF_POLL_INTERVAL_MS - (Date.now() - pollStartedAt)), signal);
+                    continue;
+                }
+                failures = 0;
+                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);
+        }
+    }
+}
+//# sourceMappingURL=inbox.js.map

package/dist/namespaces/inbox.js.map

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

package/dist/namespaces/live.d.ts

@@ -0,0 +1,57 @@
+import type { HttpClient } from '../http.js';
+import type { LiveClaimAction, LiveClaimResult, LiveStatusPing, LiveStatusResult, LiveStatusSnapshot } from '../liveStatus.js';
+/**
+ * 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.
+ */
+export declare class LiveApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Send one stream ping — start, update, or end, chosen by `live_status.state`
+     * and whether the correlation already exists.
+     */
+    push(inviteCode: string, ping: LiveStatusPing): Promise<LiveStatusResult>;
+    /**
+     * 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".
+     */
+    get(inviteCode: string, correlationId: string): Promise<LiveStatusSnapshot | null>;
+    /**
+     * Act on a "Who's on it?" request as the human this credential acts for:
+     * `claim` takes an open request (anyone but its asker), `release` lets go of
+     * one you hold, `done` finishes it (its claimer, or its asker at any time) and
+     * `cancel` withdraws it (its asker, or a room owner or admin).
+     *
+     * `release` returns the request to `open` only while it can still be taken.
+     * Past its deadline (or four hours after it was made, when it has none) it
+     * ends the request as `expired` instead: a 200 whose `claim.status` is
+     * `expired` and whose `state` is `failed`, with `claim.by` and `claim.at`
+     * `null`. It is not an error, and the asker hears "No one took it". No other
+     * action resolves that way.
+     *
+     * `notificationId` is the request's `notification_id`, from the `push()`
+     * result or `notifications.list()`. It needs only room membership, not room
+     * ownership, and the `pingroom:live:write` scope.
+     *
+     * Repeating your own last action resolves with `idempotent: true`. A refusal
+     * throws `PingRoomError`: `claim_conflict` (409), `claim_own_request` (422),
+     * `claim_private_rooms_only` (422), `claim_not_found` (404) or `forbidden`
+     * (403). On 409 and 422 `error.body` is a `LiveClaimRefusal` carrying the
+     * request as it stands, so you can say who got it first.
+     * A malformed or mismatched success throws `invalid_response`; the SDK
+     * never repeats the transition POST automatically.
+     */
+    claim(inviteCode: string, notificationId: string, action: LiveClaimAction): Promise<LiveClaimResult>;
+}
+//# sourceMappingURL=live.d.ts.map

package/dist/namespaces/live.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live.d.ts","sourceRoot":"","sources":["../../src/namespaces/live.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAGf,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,kBAAkB,CAAC;AAqC1B;;;;;;;GAOG;AACH,qBAAa,OAAO;IACN,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAE7C;;;OAGG;IACH,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAOzE;;;;;;;;;OASG;IACG,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAcxF;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;CAYrG"}

package/dist/namespaces/live.js

@@ -0,0 +1,116 @@
+// `pr.live`: live-status streams.
+import { PingRoomError } from '../errors.js';
+import { assertStructuredData, requireNonEmpty } from '../internal/guards.js';
+import { enc } from '../internal/request.js';
+import { isNonEmptyString, isRecord, sameId } from '../internal/validate.js';
+/**
+ * What each action's 200 receipt may say, as `[claim.status, stream state]`
+ * pairs. `release` has two: letting go reopens a request that can still be
+ * taken, but a request past its deadline (or four hours old with none) ends as
+ * `expired` with stream state `failed`, exactly as time ends an open one. That
+ * is still a 200, and a retry replays it. Only `release` can end that way.
+ */
+const CLAIM_OUTCOMES = {
+    claim: [['claimed', 'running']],
+    release: [['open', 'running'], ['expired', 'failed']],
+    done: [['done', 'done']],
+    cancel: [['cancelled', 'failed']],
+};
+function validateClaimResult(value, notificationId, action) {
+    const expected = CLAIM_OUTCOMES[action];
+    const claim = isRecord(value) ? value['claim'] : undefined;
+    const party = isRecord(claim) ? claim['by'] : undefined;
+    if (!isRecord(value) || !sameId(value['notification_id'], notificationId)
+        || !isNonEmptyString(value['correlation_id']) || typeof value['idempotent'] !== 'boolean'
+        || !isRecord(claim) || !expected
+        || !expected.some(([status, state]) => claim['status'] === status && value['state'] === state)
+        || typeof claim['late'] !== 'boolean'
+        || !(party === null || isRecord(party) && isNonEmptyString(party['id']) && typeof party['name'] === 'string')
+        || !(claim['at'] === null || typeof claim['at'] === 'number' && Number.isFinite(claim['at']))) {
+        throw new PingRoomError('PingRoom returned an invalid claim transition receipt.', {
+            code: 'invalid_response',
+            body: { expected_notification_id: notificationId, action },
+        });
+    }
+    return value;
+}
+/**
+ * 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.
+ */
+export 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;
+        }
+    }
+    /**
+     * Act on a "Who's on it?" request as the human this credential acts for:
+     * `claim` takes an open request (anyone but its asker), `release` lets go of
+     * one you hold, `done` finishes it (its claimer, or its asker at any time) and
+     * `cancel` withdraws it (its asker, or a room owner or admin).
+     *
+     * `release` returns the request to `open` only while it can still be taken.
+     * Past its deadline (or four hours after it was made, when it has none) it
+     * ends the request as `expired` instead: a 200 whose `claim.status` is
+     * `expired` and whose `state` is `failed`, with `claim.by` and `claim.at`
+     * `null`. It is not an error, and the asker hears "No one took it". No other
+     * action resolves that way.
+     *
+     * `notificationId` is the request's `notification_id`, from the `push()`
+     * result or `notifications.list()`. It needs only room membership, not room
+     * ownership, and the `pingroom:live:write` scope.
+     *
+     * Repeating your own last action resolves with `idempotent: true`. A refusal
+     * throws `PingRoomError`: `claim_conflict` (409), `claim_own_request` (422),
+     * `claim_private_rooms_only` (422), `claim_not_found` (404) or `forbidden`
+     * (403). On 409 and 422 `error.body` is a `LiveClaimRefusal` carrying the
+     * request as it stands, so you can say who got it first.
+     * A malformed or mismatched success throws `invalid_response`; the SDK
+     * never repeats the transition POST automatically.
+     */
+    claim(inviteCode, notificationId, action) {
+        requireNonEmpty(inviteCode, 'inviteCode');
+        requireNonEmpty(notificationId, 'notificationId');
+        if (typeof action !== 'string' || !Object.hasOwn(CLAIM_OUTCOMES, action)) {
+            throw new PingRoomError('`action` must be claim, release, done or cancel.', { code: 'invalid_request' });
+        }
+        return this.http.request('POST', `/api/agent/rooms/${enc(inviteCode)}/live/${enc(notificationId)}/claim`, { body: { action } }).then((value) => validateClaimResult(value, notificationId, action));
+    }
+}
+//# sourceMappingURL=live.js.map

package/dist/namespaces/live.js.map

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

package/dist/namespaces/notifications.d.ts

@@ -0,0 +1,25 @@
+import type { HttpClient } from '../http.js';
+import type { AcknowledgementWaitResult, AgentNotification, ListNotificationsInput, ListenInput, NotificationDetail, NotificationHistoryEntry, Paginated, WaitForAcknowledgementInput, WaitInput, WaitResult } from '../types.js';
+export declare class NotificationsApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Paginated list (polling fallback). Prefer wait()/listen() for real-time. */
+    list(input?: ListNotificationsInput): Promise<Paginated<NotificationHistoryEntry>>;
+    /** Fetch one visible notification, including its current acknowledgement state. */
+    getNotification(notificationId: string): Promise<NotificationDetail>;
+    /**
+     * 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: string, input?: WaitForAcknowledgementInput): Promise<AcknowledgementWaitResult>;
+    /** One long-poll: resolves as soon as new pings land, or with an empty list at timeout. */
+    wait(input?: WaitInput): Promise<WaitResult>;
+    /**
+     * 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 })) { ... }
+     */
+    listen(input?: ListenInput): AsyncGenerator<AgentNotification, void, void>;
+}
+//# sourceMappingURL=notifications.d.ts.map

package/dist/namespaces/notifications.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.d.ts","sourceRoot":"","sources":["../../src/namespaces/notifications.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAK7C,OAAO,KAAK,EACV,yBAAyB,EACzB,iBAAiB,EACjB,sBAAsB,EACtB,WAAW,EACX,kBAAkB,EAClB,wBAAwB,EACxB,SAAS,EACT,2BAA2B,EAC3B,SAAS,EACT,UAAU,EACX,MAAM,aAAa,CAAC;AAsBrB,qBAAa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAE7C,+EAA+E;IACzE,IAAI,CAAC,KAAK,GAAE,sBAA2B,GAAG,OAAO,CAAC,SAAS,CAAC,wBAAwB,CAAC,CAAC;IAc5F,mFAAmF;IACnF,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAKpE;;;OAGG;IACH,sBAAsB,CACpB,cAAc,EAAE,MAAM,EACtB,KAAK,GAAE,2BAAgC,GACtC,OAAO,CAAC,yBAAyB,CAAC;IASrC,2FAA2F;IAC3F,IAAI,CAAC,KAAK,GAAE,SAAc,GAAG,OAAO,CAAC,UAAU,CAAC;IAQhD;;;;;OAKG;IACI,MAAM,CAAC,KAAK,GAAE,WAAgB,GAAG,cAAc,CAAC,iBAAiB,EAAE,IAAI,EAAE,IAAI,CAAC;CAuDtF"}