@pingroom/sdk 0.8.0 → 0.9.0

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":"AAAA,iEAAiE;AAEjE,OAAO,EAAE,iCAAiC,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEhF,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAS1E,OAAO,EACL,4BAA4B,EAC5B,GAAG,EACH,aAAa,EACb,aAAa,GACd,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEvF,MAAM,mCAAmC,GAAG,OAAO,CAAC;AAEpD,SAAS,oBAAoB,CAAC,OAAe,EAAE,OAAgC,EAAE;IAC/E,MAAM,IAAI,aAAa,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,CAAC,CAAC;AAC7E,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAc;IACzC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,WAAW,CAAC,KAAK,IAAI,IAAI,OAAO,KAAK,CAAC,UAAU,CAAC,KAAK,SAAS,EAAE,CAAC;QAC9F,OAAO,oBAAoB,CAAC,2DAA2D,CAAC,CAAC;IAC3F,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAC3B,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC;IACnC,IACE,CAAC,QAAQ,CAAC,IAAI,CAAC;WACZ,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;WAC7B,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,QAAQ;WAChC,CAAC,gBAAgB,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;WACtC,OAAO,IAAI,CAAC,gBAAgB,CAAC,KAAK,SAAS;WAC3C,CAAC,QAAQ,CAAC,QAAQ,CAAC;WACnB,CAAC,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;WACjC,QAAQ,CAAC,MAAM,CAAC,KAAK,UAAU;WAC/B,CAAC,gBAAgB,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;WACrC,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;WACnC,QAAQ,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CACtC,CAAC,QAAQ,CAAC,MAAM,CAAC;eACd,CAAC,gBAAgB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;eAClC,CAAC,gBAAgB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CACtC,CAAC;WACC,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,SAAS;eAC9B,QAAQ,CAAC,OAAO,CAAC,KAAK,UAAU;eAChC,QAAQ,CAAC,OAAO,CAAC,KAAK,SAAS;eAC/B,QAAQ,CAAC,OAAO,CAAC,KAAK,WAAW,CAAC;WACpC,CAAC,gBAAgB,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;WACzC,CAAC,gBAAgB,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,EAC5C,CAAC;QACD,OAAO,oBAAoB,CAAC,8DAA8D,CAAC,CAAC;IAC9F,CAAC;IAED,OAAO,KAA0C,CAAC;AACpD,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAc,EAAE,UAAkB;IAC3D,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,oBAAoB,CAAC,yDAAyD,CAAC,CAAC;IACzF,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IAC7B,IACE,CAAC,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;WAC3B,KAAK,CAAC,IAAI,CAAC,KAAK,UAAU;WAC1B,KAAK,CAAC,MAAM,CAAC,KAAK,UAAU;WAC5B,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,UAAU,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,WAAW,CAAC;WAC7F,CAAC,KAAK,CAAC,sBAAsB,CAAC,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,sBAAsB,CAAC,KAAK,SAAS,CAAC;WACnG,CAAC,KAAK,KAAK,UAAU,IAAI,KAAK,CAAC,sBAAsB,CAAC,KAAK,IAAI,CAAC,EACnE,CAAC;QACD,OAAO,oBAAoB,CAAC,2DAA2D,EAAE;YACvF,WAAW,EAAE,UAAU;YACvB,WAAW,EAAE,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI;YACjE,IAAI,EAAE,OAAO,KAAK,CAAC,MAAM,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI;YAC9D,KAAK,EAAE,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI;SAChD,CAAC,CAAC;IACL,CAAC;IAED,IAAI,KAAK,KAAK,UAAU,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC/B,IACE,CAAC,QAAQ,CAAC,MAAM,CAAC;eACd,CAAC,gBAAgB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;eAClC,CAAC,gBAAgB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;eAClC,CAAC,gBAAgB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;eACjC,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;eACzE,CAAC,gBAAgB,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;eACxC,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,EACnE,CAAC;YACD,OAAO,oBAAoB,CAAC,kEAAkE,EAAE;gBAC9F,EAAE,EAAE,UAAU;gBACd,KAAK;aACN,CAAC,CAAC;QACL,CAAC;QAED,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;QACtC,IACE,QAAQ,CAAC,SAAS,CAAC;eAChB,CAAC,CAAC,gBAAgB,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC,EACvF,CAAC;YACD,OAAO,oBAAoB,CAAC,oDAAoD,EAAE;gBAChF,EAAE,EAAE,UAAU;gBACd,KAAK;aACN,CAAC,CAAC;QACL,CAAC;IACH,CAAC;SAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC;QACrE,OAAO,oBAAoB,CAAC,2DAA2D,EAAE;YACvF,EAAE,EAAE,UAAU;YACd,KAAK;SACN,CAAC,CAAC;IACL,CAAC;IAED,OAAO,KAA2B,CAAC;AACrC,CAAC;AAED,2EAA2E;AAC3E,MAAM,OAAO,QAAQ;IACU;IAA7B,YAA6B,IAAgB;QAAhB,SAAI,GAAJ,IAAI,CAAY;IAAG,CAAC;IAEjD,8EAA8E;IAC9E,MAAM,CAAC,QAA+B,EAAE;QACtC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,yBAAyB,EAAE;YAC1D,IAAI,EAAE,EAAE;YACR,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAClD,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,QAAQ,CAAC,QAAiC,EAAE;QAChD,MAAM,gBAAgB,GAAG,KAAK,CAAC,gBAAgB,IAAI,mCAAmC,CAAC;QACvF,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAC,IAAI,gBAAgB,GAAG,CAAC,EAAE,CAAC;YAC/D,MAAM,IAAI,aAAa,CAAC,0DAA0D,EAAE;gBAClF,IAAI,EAAE,iBAAiB;aACxB,CAAC,CAAC;QACL,CAAC;QAED,MAAM,aAAa,GAAG,GAAsC,EAAE,CAAC,CAC7D,IAAI,iCAAiC,CACnC,mBAAmB,EACnB,sEAAsE,EACtE,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,CACzC,CACF,CAAC;QACF,MAAM,kBAAkB,GAAG,IAAI,eAAe,EAAE,CAAC;QACjD,MAAM,aAAa,GAAG,gBAAgB,KAAK,CAAC;YAC1C,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC,kBAAkB,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC,EAAE,gBAAgB,CAAC,CAAC;QAClF,IAAI,gBAAgB,KAAK,CAAC;YAAE,kBAAkB,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC,CAAC;QAEtE,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM;YACzB,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,MAAM,EAAE,kBAAkB,CAAC,MAAM,CAAC;YACzD,CAAC,CAAC,kBAAkB,CAAC,MAAM,CAAC;QAE9B,IAAI,CAAC;YACH,cAAc,CAAC,MAAM,CAAC,CAAC;YACvB,MAAM,OAAO,GAAG,mBAAmB,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;YACnE,MAAM,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YAEvC,IAAI,QAAQ,GAAG,CAAC,CAAC;YACjB,SAAS,CAAC;gBACR,cAAc,CAAC,MAAM,CAAC,CAAC;gBACvB,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBACjC,IAAI,QAAiB,CAAC;gBACtB,IAAI,CAAC;oBACH,QAAQ,GAAG,iBAAiB,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAClD,KAAK,EACL,uBAAuB,GAAG,CAAC,UAAU,CAAC,OAAO,EAC7C;wBACE,KAAK,EAAE,aAAa,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;wBAChD,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC;wBACvC,MAAM;qBACP,CACF,EAAE,UAAU,CAAC,CAAC;gBACjB,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,mEAAmE;oBACnE,mEAAmE;oBACnE,+DAA+D;oBAC/D,2CAA2C;oBAC3C,cAAc,CAAC,MAAM,CAAC,CAAC;oBACvB,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;wBAC7B,MAAM,KAAK,CAAC;oBACd,CAAC;oBACD,QAAQ,IAAI,CAAC,CAAC;oBACd,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAClB,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,EACjC,4BAA4B,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,aAAa,CAAC,CAC5D,EAAE,MAAM,CAAC,CAAC;oBACX,SAAS;gBACX,CAAC;gBACD,QAAQ,GAAG,CAAC,CAAC;gBACb,cAAc,CAAC,MAAM,CAAC,CAAC;gBAEvB,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;oBACjC,MAAM,KAAK,CACT,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,4BAA4B,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,aAAa,CAAC,CAAC,EACxE,MAAM,CACP,CAAC;oBACF,SAAS;gBACX,CAAC;gBAED,IAAI,QAAQ,CAAC,KAAK,KAAK,UAAU,IAAI,QAAQ,CAAC,oBAAoB,KAAK,IAAI,EAAE,CAAC;oBAC5E,OAAO;wBACL,GAAG,OAAO;wBACV,oBAAoB,EAAE,IAAI;wBAC1B,QAAQ,EAAE,QAAwC;qBACnD,CAAC;gBACJ,CAAC;gBAED,IAAI,QAAQ,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;oBAClC,MAAM,IAAI,iCAAiC,CACzC,6BAA6B,EAC7B,+FAA+F,EAC/F,EAAE,WAAW,EAAE,UAAU,EAAE,oBAAoB,EAAE,QAAQ,CAAC,oBAAoB,IAAI,IAAI,EAAE,CACzF,CAAC;gBACJ,CAAC;gBAED,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS,IAAI,QAAQ,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;oBACnE,MAAM,IAAI,iCAAiC,CACzC,QAAQ,CAAC,KAAK,EACd,2BAA2B,QAAQ,CAAC,KAAK,2CAA2C,EACpF,EAAE,WAAW,EAAE,UAAU,EAAE,oBAAoB,EAAE,QAAQ,CAAC,oBAAoB,IAAI,IAAI,EAAE,CACzF,CAAC;gBACJ,CAAC;gBAED,OAAO,oBAAoB,CAAC,yDAAyD,EAAE;oBACrF,EAAE,EAAE,UAAU;oBACd,KAAK,EAAE,QAAQ,CAAC,KAAK;iBACtB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,qEAAqE;YACrE,sEAAsE;YACtE,sEAAsE;YACtE,cAAc,CAAC,MAAM,CAAC,CAAC;YACvB,MAAM,KAAK,CAAC;QACd,CAAC;gBAAS,CAAC;YACT,IAAI,aAAa,KAAK,IAAI;gBAAE,YAAY,CAAC,aAAa,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;CACF"}

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"}

package/dist/namespaces/notifications.js

@@ -0,0 +1,128 @@
+// `pr.notifications`: history, one-shot waits and the listen() iterator.
+import { PingRoomError } from '../errors.js';
+import { sleep } from '../internal/async.js';
+import { requireNonEmpty } from '../internal/guards.js';
+import { isTransientError, transientDelayMs } from '../internal/retry.js';
+import { isRecord } from '../internal/validate.js';
+import { enc, dropUndefined, MIN_LISTEN_POLL_INTERVAL_MS, waitTimeoutMs } from '../internal/request.js';
+/**
+ * A 2xx that is not a wait answer (a captive portal's HTML, a proxy's error
+ * page served as 200) must not end `listen()` with a bare TypeError, nor
+ * advance its cursor.
+ */
+function validateListenResult(value, requireCursor) {
+    if (!isRecord(value)
+        || !Array.isArray(value['notifications'])
+        || value['notifications'].some((notification) => !isRecord(notification))
+        || (value['cursor'] === undefined ? requireCursor : typeof value['cursor'] !== 'string')) {
+        throw new PingRoomError('PingRoom returned an invalid notifications wait response.', {
+            code: 'invalid_response',
+        });
+    }
+    return value;
+}
+export 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;
+            // The head read is an immediate answer by design; only polls ahead of
+            // the cursor are spaced.
+            const polledForward = headRead;
+            const pollStartedAt = Date.now();
+            try {
+                // The head read exists to obtain a cursor, so it must carry one.
+                result = validateListenResult(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 } : {}) }), !headRead);
+            }
+            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(Math.max(transientDelayMs(err, failures, backoffMs), MIN_LISTEN_POLL_INTERVAL_MS - (Date.now() - pollStartedAt)), 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). After an empty answer also keep polls a floor apart, so
+            // `timeout: 0` or an early-answering proxy cannot spin the loop.
+            const spacingMs = polledForward && result.notifications.length === 0
+                ? Math.max(0, MIN_LISTEN_POLL_INTERVAL_MS - (Date.now() - pollStartedAt))
+                : 0;
+            await sleep(spacingMs, input.signal);
+        }
+    }
+}
+//# sourceMappingURL=notifications.js.map

package/dist/namespaces/notifications.js.map

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

package/dist/namespaces/profile.d.ts

@@ -0,0 +1,19 @@
+import type { HttpClient } from '../http.js';
+import type { RotateHandleResult } from '../types.js';
+export declare class ProfileApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * 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: string): Promise<{
+        ok: boolean;
+        avatar_id: string;
+        avatar_url: string;
+    }>;
+    /** Rotate the agent's handle — the kill-switch for a leaked handle. */
+    rotateHandle(): Promise<RotateHandleResult>;
+}
+//# sourceMappingURL=profile.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../../src/namespaces/profile.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAE7C;;;;OAIG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAK5F,uEAAuE;IACvE,YAAY,IAAI,OAAO,CAAC,kBAAkB,CAAC;CAG5C"}

package/dist/namespaces/profile.js

@@ -0,0 +1,22 @@
+// `pr.profile`: this agent's own avatar and handle.
+import { requireNonEmpty } from '../internal/guards.js';
+export 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: {} });
+    }
+}
+//# sourceMappingURL=profile.js.map

package/dist/namespaces/profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.js","sourceRoot":"","sources":["../../src/namespaces/profile.ts"],"names":[],"mappings":"AAAA,oDAAoD;AAGpD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD,MAAM,OAAO,UAAU;IACQ;IAA7B,YAA6B,IAAgB;QAAhB,SAAI,GAAJ,IAAI,CAAY;IAAG,CAAC;IAEjD;;;;OAIG;IACH,SAAS,CAAC,QAAgB;QACxB,eAAe,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,2BAA2B,EAAE,EAAE,IAAI,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;IACnG,CAAC;IAED,uEAAuE;IACvE,YAAY;QACV,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,kCAAkC,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IACrF,CAAC;CACF"}