@pingroom/sdk 0.8.0 → 0.9.0

package/dist/namespaces/actions.js

@@ -0,0 +1,219 @@
+// `pr.actions`: a room's quick-action slots, pages and presses.
+import { PingRoomError } from '../errors.js';
+import { assertActionNumber, requireNonEmpty, requirePresentString } from '../internal/guards.js';
+import { linkPing } from '../linkPing.js';
+import { locationPing } from '../locationPing.js';
+import { enc, splitIdempotencyKey, dropUndefined } from '../internal/request.js';
+const MAX_TRIGGER_ATTACHMENTS = 4;
+const QUICK_ACTION_PAGE_SIZE = 4;
+const MAX_QUICK_ACTION_PAGES = 4;
+/**
+ * The per-slot checks shared by `updateMany()` and `updateLayout()`: a valid,
+ * present, unique action_number and an icon whenever the slot has a label.
+ * Two entries for one slot would let the last silently win, and the caller
+ * would never learn which of its definitions was stored.
+ */
+function assertActionSlots(actions) {
+    const seen = new Set();
+    for (const action of actions) {
+        assertActionNumber(action.action_number);
+        if (action.action_number === undefined || action.action_number === null) {
+            throw new PingRoomError('`action_number` is required for each action.', { code: 'invalid_request' });
+        }
+        if (seen.has(action.action_number)) {
+            throw new PingRoomError(`Duplicate action_number ${action.action_number}.`, { code: 'invalid_request' });
+        }
+        seen.add(action.action_number);
+        assertQuickActionIcon(action);
+    }
+}
+/**
+ * Mirrors the server's `icon` rule (`present`, `required_with:label`): the emoji
+ * is the half that must be there unless BOTH are empty, which reserves the
+ * slot as disabled.
+ */
+function assertQuickActionIcon(action) {
+    requirePresentString(action.label, 'label');
+    requirePresentString(action.icon, 'icon');
+    if (action.icon.trim() === '' && action.label.trim() !== '') {
+        throw new PingRoomError('`icon` is required when `label` is set; send both empty to disable the slot.', {
+            code: 'invalid_request',
+        });
+    }
+}
+function assertTriggerInput(input) {
+    const data = input.data;
+    if (data !== undefined) {
+        if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+            throw new PingRoomError('`data` must be an object with `location` and/or `url`.', { code: 'invalid_request' });
+        }
+        for (const key of Object.keys(data)) {
+            if (key !== 'location' && key !== 'url') {
+                throw new PingRoomError(`\`data.${key}\` is not accepted on a quick-action press; only location and url are.`, {
+                    code: 'invalid_request',
+                });
+            }
+        }
+        try {
+            if (data.location !== undefined)
+                locationPing(data.location);
+            if (data.url !== undefined)
+                linkPing({ url: data.url });
+        }
+        catch (error) {
+            throw new PingRoomError(error.message, { code: 'invalid_request' });
+        }
+    }
+    if (input.attachment_ids !== undefined) {
+        if (!Array.isArray(input.attachment_ids) || input.attachment_ids.length > MAX_TRIGGER_ATTACHMENTS) {
+            throw new PingRoomError(`\`attachment_ids\` accepts at most ${MAX_TRIGGER_ATTACHMENTS} ids.`, { code: 'invalid_request' });
+        }
+        for (const id of input.attachment_ids)
+            requireNonEmpty(id, 'attachment_ids[]');
+    }
+}
+export class ActionsApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    list(inviteCode) {
+        return this.http.request('GET', `/api/agent/rooms/${enc(inviteCode)}/actions`);
+    }
+    update(inviteCode, actionNumber, input) {
+        assertActionNumber(actionNumber);
+        // A Ping's title is optional — its emoji can be the whole name — so an
+        // empty `label` is a valid update. `icon` is the half that must be there,
+        // unless both are empty: that reserves the slot as disabled.
+        assertQuickActionIcon(input);
+        return this.http.request('PUT', `/api/agent/rooms/${enc(inviteCode)}/actions/${actionNumber}`, {
+            body: dropUndefined({ ...input }),
+        });
+    }
+    /**
+     * Write up to 16 action slots in one request. The server enforces the room owner's plan.
+     * Add new pages in complete groups of four; existing slots may be edited individually.
+     *
+     * Prefer this over looping `update()`. Each single-slot write enqueues its
+     * own silent rooms-refresh push, so configuring a room's four Pings one at a
+     * time wakes room members' devices four times inside a few seconds — four of a
+     * finite daily background-push budget spent on one logical operation.
+     *
+     * Partial and additive: slots absent from `actions` keep their current
+     * configuration, so this is also the right call for editing a single Ping.
+     * Nothing here deletes an action, and an empty array is rejected locally
+     * rather than being sent as a clear. Resolves to the room's full ordered
+     * action set, not just the slots written.
+     */
+    updateMany(inviteCode, actions) {
+        if (!Array.isArray(actions) || actions.length === 0) {
+            throw new PingRoomError('`actions` must contain at least one action.', { code: 'invalid_request' });
+        }
+        if (actions.length > 16) {
+            throw new PingRoomError('A batch may contain at most 16 action slots.', { code: 'invalid_request' });
+        }
+        assertActionSlots(actions);
+        return this.http.request('PUT', `/api/agent/rooms/${enc(inviteCode)}/actions`, {
+            body: { actions: actions.map((action) => dropUndefined({ ...action })) },
+        });
+    }
+    /**
+     * Press a slot. When the action has an `input_type`, pass the matching
+     * detail (`data.location`, `data.url`, or `attachment_ids`) or the server
+     * refuses the press with `422 quick_action_input_required` and sends nothing.
+     * Read `input_type` from `list()` first; pass the action's `id` as
+     * `quick_action_id` to be refused rather than fire the wrong Ping if the
+     * owner moved pages meanwhile.
+     */
+    trigger(inviteCode, actionNumber, input = {}) {
+        assertActionNumber(actionNumber);
+        assertTriggerInput(input);
+        const { body, headers } = splitIdempotencyKey(input);
+        return this.http.request('POST', `/api/agent/rooms/${enc(inviteCode)}/actions/${actionNumber}/trigger`, {
+            body: dropUndefined({ ...body }),
+            ...(headers ? { headers } : {}),
+        });
+    }
+    /**
+     * Replace the room's page layout atomically (room owner on Pro only). See
+     * `UpdateQuickActionLayoutInput` for the snapshot contract; a stale
+     * `base_action_ids` is `409 quick_action_layout_changed`, a page still used
+     * by a time trigger, webhook, agent binding or running live update is
+     * `409 quick_action_page_in_use`. Prefer `deletePage()`, which builds the
+     * body from a fresh read.
+     */
+    updateLayout(inviteCode, input) {
+        if (!Array.isArray(input.base_action_ids)) {
+            throw new PingRoomError('`base_action_ids` must be an array of action ids (may be empty).', { code: 'invalid_request' });
+        }
+        if (!Array.isArray(input.page_order) || input.page_order.length < 1 || input.page_order.length > MAX_QUICK_ACTION_PAGES) {
+            throw new PingRoomError(`\`page_order\` must list 1–${MAX_QUICK_ACTION_PAGES} pages.`, { code: 'invalid_request' });
+        }
+        for (const page of input.page_order) {
+            if (page !== null && (!Number.isInteger(page) || page < 1 || page > MAX_QUICK_ACTION_PAGES)) {
+                throw new PingRoomError('`page_order` entries must be an original page number 1–4 or null for a blank page.', {
+                    code: 'invalid_request',
+                });
+            }
+        }
+        const expected = input.page_order.length * QUICK_ACTION_PAGE_SIZE;
+        if (!Array.isArray(input.actions) || input.actions.length !== expected) {
+            throw new PingRoomError(`\`actions\` must hold exactly ${expected} slots for ${input.page_order.length} page(s).`, {
+                code: 'invalid_request',
+            });
+        }
+        assertActionSlots(input.actions);
+        return this.http.request('PUT', `/api/agent/rooms/${enc(inviteCode)}/actions/layout`, {
+            body: {
+                base_action_ids: input.base_action_ids,
+                page_order: input.page_order,
+                actions: input.actions.map((action) => dropUndefined({ ...action })),
+            },
+        });
+    }
+    /**
+     * Delete one page (1–4) and shift the later pages left, keeping every other
+     * slot's configuration. Reads the current action set first so the layout
+     * snapshot is real, then calls `updateLayout()`. Page 1 can be deleted only
+     * when another page remains.
+     */
+    async deletePage(inviteCode, page) {
+        if (!Number.isInteger(page) || page < 1 || page > MAX_QUICK_ACTION_PAGES) {
+            throw new PingRoomError('`page` must be an integer 1–4.', { code: 'invalid_request' });
+        }
+        const current = await this.list(inviteCode);
+        const stored = [...current].sort((a, b) => a.action_number - b.action_number);
+        const pageCount = Math.max(1, Math.ceil((stored.at(-1)?.action_number ?? 0) / QUICK_ACTION_PAGE_SIZE));
+        if (page > pageCount) {
+            throw new PingRoomError(`The room has ${pageCount} page(s); page ${page} does not exist.`, { code: 'invalid_request' });
+        }
+        if (pageCount === 1) {
+            throw new PingRoomError('A room keeps at least one page; configure its slots instead of deleting it.', {
+                code: 'invalid_request',
+            });
+        }
+        const keep = Array.from({ length: pageCount }, (_, i) => i + 1).filter((p) => p !== page);
+        const byNumber = new Map(stored.map((a) => [a.action_number, a]));
+        const actions = [];
+        keep.forEach((originalPage, index) => {
+            for (let offset = 1; offset <= QUICK_ACTION_PAGE_SIZE; offset++) {
+                const source = byNumber.get((originalPage - 1) * QUICK_ACTION_PAGE_SIZE + offset);
+                actions.push({
+                    action_number: index * QUICK_ACTION_PAGE_SIZE + offset,
+                    label: source?.label ?? '',
+                    icon: source?.icon ?? '',
+                    ...(source?.sound !== undefined ? { sound: source.sound } : {}),
+                    ...(source?.haptic_style !== undefined ? { haptic_style: source.haptic_style } : {}),
+                    ...(source?.requires_ack !== undefined ? { requires_ack: source.requires_ack } : {}),
+                    ...(source?.input_type !== undefined ? { input_type: source.input_type } : {}),
+                });
+            }
+        });
+        return this.updateLayout(inviteCode, {
+            base_action_ids: stored.map((a) => a.id).filter((id) => typeof id === 'string'),
+            page_order: keep,
+            actions,
+        });
+    }
+}
+//# sourceMappingURL=actions.js.map

package/dist/namespaces/actions.js.map

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

package/dist/namespaces/approvals.d.ts

@@ -0,0 +1,23 @@
+import type { HttpClient } from '../http.js';
+import type { Approval, ApprovalInput, WaitApprovalInput, WaitForOutcomeOptions } from '../types.js';
+export declare class ApprovalsApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Ask the human you act for to decide; returns the pending approval. */
+    request(inviteCode: string, input: ApprovalInput): Promise<Approval>;
+    get(approvalId: string): Promise<Approval>;
+    /** One long-poll for the decision; returns the (possibly still-pending) approval. */
+    wait(approvalId: string, input?: WaitApprovalInput): Promise<Approval>;
+    /**
+     * Block until the human decides (or the request expires or is cancelled),
+     * looping wait() under the hood, with polls started at least 2.1 s apart. A
+     * response that is not this approval in a known status rejects with
+     * `invalid_response`. Network failures, 429 and 5xx are retried with backoff
+     * (honouring `retryAfter`), and reported to `onRetry`, until `signal` aborts
+     * or the outage outlasts the approval's `expires_at` by 5 minutes (15 minutes
+     * of failures while no `expires_at` has been read); that rejects with
+     * `unavailable`. See {@link WaitForOutcomeOptions}.
+     */
+    waitForDecision(approvalId: string, input?: WaitForOutcomeOptions): Promise<Approval>;
+}
+//# sourceMappingURL=approvals.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.d.ts","sourceRoot":"","sources":["../../src/namespaces/approvals.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,OAAO,KAAK,EACV,QAAQ,EACR,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACtB,MAAM,aAAa,CAAC;AA0CrB,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAE7C,yEAAyE;IACzE,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC;IAUpE,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI1C,qFAAqF;IACrF,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,GAAE,iBAAsB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAQ1E;;;;;;;;;OASG;IACG,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,GAAE,qBAA0B,GAAG,OAAO,CAAC,QAAQ,CAAC;CAchG"}

package/dist/namespaces/approvals.js

@@ -0,0 +1,78 @@
+// `pr.approvals`: two-option human-in-the-loop decisions.
+import { assertStructuredData, requireNonEmpty } from '../internal/guards.js';
+import { pollUntilSettled } from '../internal/retry.js';
+import { MIN_WAIT_POLL_INTERVAL_MS, enc, splitIdempotencyKey, assertOnRetry, dropUndefined, waitTimeoutMs, } from '../internal/request.js';
+import { isRecord, isNonEmptyString, isNullableString, sameId, invalidWaitResponse, } from '../internal/validate.js';
+const APPROVAL_STATUSES = new Set(['pending', 'decided', 'expired', 'cancelled']);
+/**
+ * A wait response is trusted as an outcome only when it is the approval that
+ * was asked about, in a known status. A captive portal's HTML, `{}`, or another
+ * approval must not read as "decided".
+ */
+function validateApprovalWait(value, approvalId) {
+    const status = isRecord(value) ? value['status'] : undefined;
+    if (!isRecord(value)
+        || !sameId(value['id'], approvalId)
+        || typeof status !== 'string'
+        || !APPROVAL_STATUSES.has(status)
+        || !isNullableString(value['decided_at'])
+        // A gate acts on `decision`; a decided approval without one, or a pending
+        // one already stamped decided, is not an outcome it can act on.
+        || (status === 'decided' && !isNonEmptyString(value['decision']))
+        || (status === 'pending' && value['decided_at'] !== null)) {
+        return invalidWaitResponse('approval', approvalId, value, 'status');
+    }
+    return value;
+}
+export class ApprovalsApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Ask the human you act for to decide; returns the pending approval. */
+    request(inviteCode, input) {
+        requireNonEmpty(input.question, 'question');
+        assertStructuredData(input.data);
+        const { body, headers } = splitIdempotencyKey(input);
+        return this.http.request('POST', `/api/agent/rooms/${enc(inviteCode)}/approvals`, {
+            body: dropUndefined({ ...body }),
+            ...(headers ? { headers } : {}),
+        });
+    }
+    get(approvalId) {
+        return this.http.request('GET', `/api/agent/approvals/${enc(approvalId)}`);
+    }
+    /** One long-poll for the decision; returns the (possibly still-pending) approval. */
+    wait(approvalId, input = {}) {
+        return this.http.request('GET', `/api/agent/approvals/${enc(approvalId)}/wait`, {
+            query: dropUndefined({ timeout: input.timeout }),
+            timeoutMs: waitTimeoutMs(input.timeout),
+            ...(input.signal ? { signal: input.signal } : {}),
+        });
+    }
+    /**
+     * Block until the human decides (or the request expires or is cancelled),
+     * looping wait() under the hood, with polls started at least 2.1 s apart. A
+     * response that is not this approval in a known status rejects with
+     * `invalid_response`. Network failures, 429 and 5xx are retried with backoff
+     * (honouring `retryAfter`), and reported to `onRetry`, until `signal` aborts
+     * or the outage outlasts the approval's `expires_at` by 5 minutes (15 minutes
+     * of failures while no `expires_at` has been read); that rejects with
+     * `unavailable`. See {@link WaitForOutcomeOptions}.
+     */
+    async waitForDecision(approvalId, input = {}) {
+        requireNonEmpty(approvalId, 'approvalId');
+        assertOnRetry(input.onRetry);
+        return pollUntilSettled({
+            poll: () => this.wait(approvalId, input.signal ? { signal: input.signal } : {}),
+            validate: (value) => validateApprovalWait(value, approvalId),
+            settled: (approval) => approval.status !== 'pending',
+            expiresAt: (approval) => approval.expires_at,
+            what: `approval ${approvalId}`,
+            minIntervalMs: MIN_WAIT_POLL_INTERVAL_MS,
+            ...(input.signal ? { signal: input.signal } : {}),
+            ...(input.onRetry ? { onRetry: input.onRetry } : {}),
+        });
+    }
+}
+//# sourceMappingURL=approvals.js.map

package/dist/namespaces/approvals.js.map

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

package/dist/namespaces/attachments.d.ts

@@ -0,0 +1,37 @@
+import type { HttpClient } from '../http.js';
+import type { Attachment, ZipManifest, UploadAttachmentInput } from '../types.js';
+/**
+ * Private files that a Ping or Question can carry.
+ *
+ * Upload first, then pass the returned ids to `broadcast()` / `questions.ask()`
+ * as `attachment_ids`. Bytes never travel inside a JSON ping body (the MCP
+ * `upload_attachment` tool takes only small files, about 90 KiB, as base64). An
+ * upload that is never attached expires on its own after 24 hours.
+ * Each file must be 1 byte–5 MiB with an md/pdf/html/txt/jpg/jpeg/png/zip filename;
+ * a Ping or Question accepts at most four ids.
+ *
+ * Uploading requires the bound account to hold Pro (the API answers 402
+ * `pro_required` otherwise). Reading and deleting are not gated.
+ */
+export declare class AttachmentsApi {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Upload one file and get back the id a send can claim. */
+    upload(input: UploadAttachmentInput): Promise<Attachment>;
+    /**
+     * Raw bytes for an attachment this credential is allowed to see. Returns the
+     * undecoded Response so a caller can stream it, or read text/arrayBuffer.
+     */
+    content(attachmentId: string, signal?: AbortSignal): Promise<Response>;
+    /**
+     * The listing of a `.zip`'s contents, recorded when it was uploaded.
+     *
+     * Resolves null for a non-archive, and for an archive whose central
+     * directory did not parse. Nothing decompresses the file to produce this, so
+     * the declared sizes are what the archive claims, not verified output.
+     */
+    manifest(attachmentId: string, signal?: AbortSignal): Promise<ZipManifest | null>;
+    /** Discard an upload that has not been attached to a ping yet. */
+    delete(attachmentId: string): Promise<void>;
+}
+//# sourceMappingURL=attachments.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../../src/namespaces/attachments.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAYlF;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,UAAU;IAE7C,4DAA4D;IAC5D,MAAM,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,UAAU,CAAC;IAqBzD;;;OAGG;IACH,OAAO,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC;IAOtE;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAWjF,kEAAkE;IAClE,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAI5C"}

package/dist/namespaces/attachments.js

@@ -0,0 +1,91 @@
+// `pr.attachments`: upload, read and discard private files.
+import { PingRoomError } from '../errors.js';
+import { requireNonEmpty } from '../internal/guards.js';
+import { enc } from '../internal/request.js';
+/** Server cap per uploaded file; a larger body is a 413 the server answers before reading it. */
+const ATTACHMENT_MAX_BYTES = 5 * 1024 * 1024;
+function attachmentByteLength(content) {
+    if (content instanceof Blob)
+        return content.size;
+    if (typeof content === 'string')
+        return new TextEncoder().encode(content).byteLength;
+    return content.byteLength;
+}
+/**
+ * Private files that a Ping or Question can carry.
+ *
+ * Upload first, then pass the returned ids to `broadcast()` / `questions.ask()`
+ * as `attachment_ids`. Bytes never travel inside a JSON ping body (the MCP
+ * `upload_attachment` tool takes only small files, about 90 KiB, as base64). An
+ * upload that is never attached expires on its own after 24 hours.
+ * Each file must be 1 byte–5 MiB with an md/pdf/html/txt/jpg/jpeg/png/zip filename;
+ * a Ping or Question accepts at most four ids.
+ *
+ * Uploading requires the bound account to hold Pro (the API answers 402
+ * `pro_required` otherwise). Reading and deleting are not gated.
+ */
+export class AttachmentsApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Upload one file and get back the id a send can claim. */
+    upload(input) {
+        requireNonEmpty(input.filename, 'filename');
+        // The server answers an oversized body with 413 before reading it; refuse
+        // locally so no bytes travel for a file that can never be accepted.
+        if (attachmentByteLength(input.content) > ATTACHMENT_MAX_BYTES) {
+            return Promise.reject(new PingRoomError('Attachments are at most 5 MiB each.', { code: 'attachment_too_large', status: 413 }));
+        }
+        const body = new FormData();
+        body.append('file', toAttachmentBlob(input), input.filename);
+        return this.http
+            .request('POST', '/api/agent/attachments', {
+            body,
+            ...(input.signal ? { signal: input.signal } : {}),
+        })
+            .then((res) => res.attachment);
+    }
+    /**
+     * Raw bytes for an attachment this credential is allowed to see. Returns the
+     * undecoded Response so a caller can stream it, or read text/arrayBuffer.
+     */
+    content(attachmentId, signal) {
+        requireNonEmpty(attachmentId, 'attachmentId');
+        return this.http.raw('GET', `/api/agent/attachments/${enc(attachmentId)}/content`, {
+            ...(signal ? { signal } : {}),
+        });
+    }
+    /**
+     * The listing of a `.zip`'s contents, recorded when it was uploaded.
+     *
+     * Resolves null for a non-archive, and for an archive whose central
+     * directory did not parse. Nothing decompresses the file to produce this, so
+     * the declared sizes are what the archive claims, not verified output.
+     */
+    manifest(attachmentId, signal) {
+        requireNonEmpty(attachmentId, 'attachmentId');
+        return this.http
+            .request('GET', `/api/agent/attachments/${enc(attachmentId)}/manifest`, { ...(signal ? { signal } : {}) })
+            .then((res) => res.manifest ?? null);
+    }
+    /** Discard an upload that has not been attached to a ping yet. */
+    delete(attachmentId) {
+        requireNonEmpty(attachmentId, 'attachmentId');
+        return this.http.request('DELETE', `/api/agent/attachments/${enc(attachmentId)}`);
+    }
+}
+/** Normalise the three accepted content shapes into one multipart part. */
+function toAttachmentBlob(input) {
+    const type = input.contentType ?? '';
+    if (input.content instanceof Blob) {
+        return type ? new Blob([input.content], { type }) : input.content;
+    }
+    // Copy into a plain ArrayBuffer: a Uint8Array view may be a window onto a
+    // larger (or SharedArrayBuffer-backed) buffer, which Blob would not accept.
+    const parts = typeof input.content === 'string'
+        ? [input.content]
+        : [new Uint8Array(input.content).slice().buffer];
+    return new Blob(parts, type ? { type } : undefined);
+}
+//# sourceMappingURL=attachments.js.map

package/dist/namespaces/attachments.js.map

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

package/dist/namespaces/auth.d.ts

@@ -0,0 +1,58 @@
+import type { HttpClient } from '../http.js';
+import type { AgentConnectionInfo, AgentDisconnectResult, Credential, ClaimCompleteParams, ClaimStartParams, RegisterParams, PairingStart, PairingStatus, PairedCredential, StartPairingParams, WaitForPairingOptions } from '../types.js';
+/** Agent credential lifecycle (auth.md flow). */
+export declare class AuthApi {
+    private readonly http;
+    private pairing;
+    constructor(http: HttpClient);
+    /** Register an agent. Anonymous or via an identity assertion (ID-JAG / verified email). Public. */
+    register(params: RegisterParams): Promise<Credential>;
+    /** Begin claiming a pre-claim credential onto a human account; emails an OTP. */
+    claimStart(params: ClaimStartParams): Promise<{
+        message: string;
+        expires_in: number;
+    }>;
+    /** Complete the claim with the emailed OTP; returns an active credential + handle. */
+    claimComplete(params: ClaimCompleteParams): Promise<Credential>;
+    /**
+     * 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.
+     */
+    startPairing(params?: StartPairingParams): Promise<PairingStart>;
+    /** Read the current state of an app pairing using the pending credential. */
+    pairingStatus(options?: Pick<WaitForPairingOptions, 'signal'>): Promise<PairingStatus>;
+    /**
+     * 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.
+     */
+    waitForPairing(pairing: PairingStart, options?: WaitForPairingOptions): Promise<PairedCredential>;
+    private pollPairing;
+    /** Rotate to a fresh credential (same scopes/handle). */
+    refresh(): Promise<Credential>;
+    /** Revoke the current credential. */
+    revoke(): Promise<void>;
+    /**
+     * 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(): Promise<AgentConnectionInfo>;
+    /**
+     * 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(): Promise<AgentDisconnectResult>;
+}
+//# sourceMappingURL=auth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/namespaces/auth.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,OAAO,KAAK,EACV,mBAAmB,EACnB,qBAAqB,EACrB,UAAU,EACV,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,qBAAqB,EACtB,MAAM,aAAa,CAAC;AA2CrB,iDAAiD;AACjD,qBAAa,OAAO;IAGN,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,OAAO,CAA+B;gBAEjB,IAAI,EAAE,UAAU;IAE7C,mGAAmG;IACnG,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC;IAKrD,iFAAiF;IACjF,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAKtF,sFAAsF;IACtF,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC;IAM/D;;;;;;;;OAQG;IACG,YAAY,CAAC,MAAM,GAAE,kBAAuB,GAAG,OAAO,CAAC,YAAY,CAAC;IA8B1E,6EAA6E;IAC7E,aAAa,CAAC,OAAO,GAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,CAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAI1F;;;;;;;;OAQG;IACG,cAAc,CAClB,OAAO,EAAE,YAAY,EACrB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,gBAAgB,CAAC;YAyBd,WAAW;IAwFzB,yDAAyD;IACzD,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC;IAI9B,qCAAqC;IACrC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvB;;;;;OAKG;IACH,UAAU,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAI1C;;;;OAIG;IACH,UAAU,IAAI,OAAO,CAAC,qBAAqB,CAAC;CAG7C"}