@pingroom/sdk 0.8.0 → 0.9.0

package/dist/namespaces/auth.js

@@ -0,0 +1,242 @@
+// `pr.auth`: registration, claim, app pairing and the credential lifecycle.
+import { PingRoomError } from '../errors.js';
+import { sleep, throwIfAborted } from '../internal/async.js';
+import { requireNonEmpty } from '../internal/guards.js';
+import { dropUndefined } from '../internal/request.js';
+import { isRecord } from '../internal/validate.js';
+/** Drop a malformed or unsafe server-provided URL without rejecting its response. */
+function normalizePublicHttpUrl(candidate) {
+    if (typeof candidate !== 'string' || candidate.trim() === '')
+        return undefined;
+    const trimmed = candidate.trim();
+    // eslint-disable-next-line no-control-regex
+    if (/[\u0000-\u001F\u007F-\u009F]/.test(trimmed))
+        return undefined;
+    try {
+        const url = new URL(trimmed);
+        if (url.protocol !== 'https:' && url.protocol !== 'http:')
+            return undefined;
+        if (url.username !== '' || url.password !== '')
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    return trimmed;
+}
+/** Drop malformed or unsafe server-provided links without rejecting a valid credential. */
+function normalizePairingLinks(value) {
+    if (!isRecord(value))
+        return undefined;
+    const latestPings = normalizePublicHttpUrl(value['latest_pings']);
+    if (!latestPings)
+        return undefined;
+    const installApp = normalizePublicHttpUrl(value['install_app']);
+    return {
+        latest_pings: latestPings,
+        ...(installApp ? { install_app: installApp } : {}),
+    };
+}
+/** Agent credential lifecycle (auth.md flow). */
+export class AuthApi {
+    http;
+    pairing = null;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Register an agent. Anonymous or via an identity assertion (ID-JAG / verified email). Public. */
+    register(params) {
+        requireNonEmpty(params.type, 'type');
+        return this.http.request('POST', '/api/agent/auth', { auth: false, body: dropUndefined({ ...params }) });
+    }
+    /** Begin claiming a pre-claim credential onto a human account; emails an OTP. */
+    claimStart(params) {
+        requireNonEmpty(params.email, 'email');
+        return this.http.request('POST', '/api/agent/auth/claim/start', { body: { email: params.email } });
+    }
+    /** Complete the claim with the emailed OTP; returns an active credential + handle. */
+    claimComplete(params) {
+        requireNonEmpty(params.email, 'email');
+        requireNonEmpty(params.otp, 'otp');
+        return this.http.request('POST', '/api/agent/auth/claim/complete', { body: dropUndefined({ ...params }) });
+    }
+    /**
+     * Register a pending agent and create a short-lived link that opens the
+     * PingRoom app. The server owns the full grant shown to the approver; this
+     * client sends no scope list. The pending credential stays private inside the
+     * client and is replaced automatically once waitForPairing() succeeds. If the
+     * client already held a credential, it is put back when the pairing expires
+     * or the wait is aborted, so a re-pairing that never completes leaves the
+     * client on the working credential rather than the dead pending one.
+     */
+    async startPairing(params = {}) {
+        const previousToken = this.http.getToken();
+        const pending = await this.register({
+            type: 'anonymous',
+            ...(params.agent_label ? { agent_label: params.agent_label } : {}),
+        });
+        this.http.setToken(pending.credential);
+        try {
+            const started = await this.http.request('POST', '/api/agent/auth/pair/start', {
+                body: {},
+            });
+            // A second pairing started while the first is still pending falls back
+            // to the credential beneath it, not to the first pairing's pending one.
+            this.pairing = {
+                pairToken: started.pair_token,
+                pending: pending.credential,
+                previous: this.pairing !== null && this.pairing.pending === previousToken
+                    ? this.pairing.previous
+                    : previousToken,
+            };
+            return started;
+        }
+        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. When the link expires or the
+     * wait is aborted, the credential the client held before startPairing() is
+     * restored; calling waitForPairing() again after an abort resumes the same
+     * pairing.
+     */
+    async waitForPairing(pairing, options = {}) {
+        const tracked = this.pairing !== null && this.pairing.pairToken === pairing.pair_token
+            ? this.pairing
+            : null;
+        if (tracked !== null && this.http.getToken() === tracked.previous) {
+            // Resuming after an abort put the earlier credential back.
+            this.http.setToken(tracked.pending);
+        }
+        try {
+            const paired = await this.pollPairing(pairing, options);
+            if (tracked !== null && this.pairing === tracked)
+                this.pairing = null;
+            return paired;
+        }
+        catch (error) {
+            if (tracked !== null && this.pairing === tracked) {
+                const expired = error instanceof PingRoomError && error.code === 'pairing_expired';
+                if (expired || options.signal?.aborted === true) {
+                    if (this.http.getToken() === tracked.pending)
+                        this.http.setToken(tracked.previous);
+                }
+                // An expired pairing cannot be resumed; an aborted one can.
+                if (expired)
+                    this.pairing = null;
+            }
+            throw error;
+        }
+    }
+    async pollPairing(pairing, options) {
+        const lifetimeMs = Math.max(1, Number(pairing.expires_in) || 900) * 1000;
+        const requestedInterval = options.pollIntervalMs ?? pairing.poll_interval_ms;
+        const intervalMs = Math.min(Math.max(Number(requestedInterval) || 1500, 1000), 10_000);
+        const startedAt = Date.now();
+        const deadline = startedAt + lifetimeMs;
+        let transientFailures = 0;
+        while (Date.now() < deadline) {
+            throwIfAborted(options.signal);
+            try {
+                const status = await this.pairingStatus({ signal: options.signal });
+                throwIfAborted(options.signal);
+                transientFailures = 0;
+                if (status.status === 'active') {
+                    if (typeof status.credential !== 'string'
+                        || status.credential.trim() === ''
+                        || status.credential_type !== 'active'
+                        || (status.expires_in !== null
+                            && (typeof status.expires_in !== 'number'
+                                || !Number.isFinite(status.expires_in)
+                                || status.expires_in < 0))
+                        // A null/absent `room` is valid when the account has no eligible
+                        // private delivery room (and on older servers). Only a room that is
+                        // present but malformed is a broken response.
+                        || (status.room != null
+                            && (typeof status.room.invite_code !== 'string'
+                                || status.room.invite_code.trim() === ''))) {
+                        throw new PingRoomError('PingRoom returned an incomplete approved pairing.', {
+                            code: 'pairing_invalid_response',
+                            body: { status: status.status },
+                        });
+                    }
+                    this.http.setToken(status.credential);
+                    // Pairing is server-authoritative. Some servers still include their
+                    // internal grant marker for protocol compatibility; it is neither a
+                    // client input nor part of the paired credential surface.
+                    const { status: _status, scopes: _serverScopes, links: rawLinks, ...credential } = status;
+                    const links = normalizePairingLinks(rawLinks);
+                    return links ? { ...credential, links } : credential;
+                }
+                if (status.status === 'expired') {
+                    throw new PingRoomError('The PingRoom pairing link expired before it was approved.', {
+                        code: 'pairing_expired',
+                    });
+                }
+            }
+            catch (error) {
+                if (error instanceof PingRoomError
+                    && [401, 403, 404].includes(error.status)
+                    && Date.now() - startedAt >= lifetimeMs / 2) {
+                    // The pending bearer can expire before the server returns an
+                    // explicit expired pairing state. Keep early auth failures intact.
+                    throw new PingRoomError('The PingRoom pairing link expired before it was approved.', {
+                        code: 'pairing_expired',
+                    });
+                }
+                if (error instanceof PingRoomError
+                    && (error.code === 'network_error'
+                        || error.code === 'timeout'
+                        || error.status === 429
+                        || error.status >= 500)) {
+                    transientFailures += 1;
+                    const backoffMs = Math.min(intervalMs * 2 ** Math.max(0, transientFailures - 3), 30_000);
+                    await sleep(Math.max(0, Math.min(backoffMs, deadline - Date.now())), options.signal);
+                    continue;
+                }
+                throw error;
+            }
+            await sleep(Math.max(0, Math.min(intervalMs, deadline - Date.now())), options.signal);
+        }
+        throw new PingRoomError('The PingRoom pairing link expired before it was approved.', {
+            code: 'pairing_expired',
+        });
+    }
+    /** Rotate to a fresh credential (same scopes/handle). */
+    refresh() {
+        return this.http.request('POST', '/api/agent/auth/refresh', { body: {} });
+    }
+    /** Revoke the current credential. */
+    revoke() {
+        return this.http.request('POST', '/api/agent/auth/revoke', { body: {} });
+    }
+    /**
+     * What this credential is connected to: the robot, the owner's public id and
+     * name, the home room and room memberships, and the room grant. Check
+     * `owner.id` and `handle` against the account and robot you approved before
+     * sending anything.
+     */
+    connection() {
+        return this.http.request('GET', '/api/agent/connection');
+    }
+    /**
+     * Disconnect this agent: revokes the calling credential and its refresh
+     * credentials. The client keeps the now-revoked token; clear it with
+     * `setToken(null)` or pair again.
+     */
+    disconnect() {
+        return this.http.request('POST', '/api/agent/disconnect', { body: {} });
+    }
+}
+//# sourceMappingURL=auth.js.map

package/dist/namespaces/auth.js.map

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

package/dist/namespaces/directory.d.ts

@@ -0,0 +1,10 @@
+import type { HttpClient } from '../http.js';
+import type { DirectoryEntry, DirectoryListInput, DirectoryProfile, Paginated } from '../types.js';
+/** Public, unauthenticated agent directory. */
+export declare class DirectoryApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(input?: DirectoryListInput): Promise<Paginated<DirectoryEntry>>;
+    get(handle: string): Promise<DirectoryProfile>;
+}
+//# sourceMappingURL=directory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"directory.d.ts","sourceRoot":"","sources":["../../src/namespaces/directory.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGnG,+CAA+C;AAC/C,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAE7C,IAAI,CAAC,KAAK,GAAE,kBAAuB,GAAG,OAAO,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;IAOxE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAG/C"}

package/dist/namespaces/directory.js

@@ -0,0 +1,19 @@
+// `pr.directory`: the public agent directory.
+import { enc, dropUndefined } from '../internal/request.js';
+/** Public, unauthenticated agent directory. */
+export class DirectoryApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    list(input = {}) {
+        return this.http.request('GET', '/api/agents/directory', {
+            auth: false,
+            query: dropUndefined({ ...input }),
+        });
+    }
+    get(handle) {
+        return this.http.request('GET', `/api/agents/directory/${enc(handle)}`, { auth: false });
+    }
+}
+//# sourceMappingURL=directory.js.map

package/dist/namespaces/directory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory.js","sourceRoot":"","sources":["../../src/namespaces/directory.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAI9C,OAAO,EAAE,GAAG,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D,+CAA+C;AAC/C,MAAM,OAAO,YAAY;IACM;IAA7B,YAA6B,IAAgB;QAAhB,SAAI,GAAJ,IAAI,CAAY;IAAG,CAAC;IAEjD,IAAI,CAAC,QAA4B,EAAE;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,uBAAuB,EAAE;YACvD,IAAI,EAAE,KAAK;YACX,KAAK,EAAE,aAAa,CAAC,EAAE,GAAG,KAAK,EAAE,CAAC;SACnC,CAAC,CAAC;IACL,CAAC;IAED,GAAG,CAAC,MAAc;QAChB,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,yBAAyB,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3F,CAAC;CACF"}

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