@recursiv/sdk 0.7.54 → 0.7.57

package/dist/resources/auth.js

@@ -1,4 +1,4 @@
-import { AuthenticationError, RateLimitError, RecursivError, ValidationError } from '../errors.js';
+import { AuthenticationError, LegacyHandoffError, RateLimitError, RecursivError, ValidationError } from '../errors.js';
 /**
  * Better Auth's anti-CSRF middleware requires an Origin header when the
  * request carries cookies or otherwise looks browser-initiated. We only
@@ -89,6 +89,14 @@ function serverErrorInfo(body) {
                 : undefined,
     };
 }
+/** Seconds from a Retry-After header given in seconds; null when absent or not a number. */
+function retryAfterHeaderSeconds(res) {
+    const raw = res.headers.get('retry-after');
+    if (!raw)
+        return null;
+    const seconds = Number(raw);
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds : null;
+}
 /** Normalize the flat, nested-object, and legacy nested-string auth errors. */
 function serverError(body, fallback) {
     const record = (body ?? {});
@@ -634,10 +642,16 @@ export class AuthResource {
         const res = await this.fetchWithTimeout(`${this.baseOrigin}/api/auth/sign-out`, {
             method: 'POST',
             headers: {
+                // Better Auth refuses a POST without a JSON Content-Type (415
+                // UNSUPPORTED_MEDIA_TYPE) before its handler runs, and on the Node
+                // server every POST carries a body stream, even an empty one. Without
+                // these two lines no sign-out ever reached the session.
+                'Content-Type': 'application/json',
                 ...originHeader(this.baseOrigin),
                 Authorization: `Bearer ${sessionToken}`,
                 Cookie: `better-auth.session_token=${sessionToken}`,
             },
+            body: '{}',
         });
         if (!res.ok) {
             let body = {};
@@ -762,53 +776,96 @@ export class AuthResource {
     /**
      * Exchange a legacy Minds session (the OAuth access token or minds_sess JWT
      * the legacy mobile app stored) for a session on this stack. Only answers
-     * during the cutover window; every failure means "show the OTP screen".
+     * during the cutover window.
      *
-     * A legacy token is single-use: after one successful exchange the server
-     * answers `legacy_token_used`, so erase the stored legacy token as soon as
-     * this resolves and never retry it.
+     * A failure throws `LegacyHandoffError` with the HTTP status (0 when no
+     * response arrived), the server's code and its Retry-After. Only
+     * `legacy_token_used` and `legacy_token_invalid` mean the legacy session can
+     * never be exchanged; forget it then. Anything else (`legacy_unavailable`,
+     * `legacy_handoff_in_progress`, a rate limit, a closed window, an account
+     * not moved yet, no response at all) leaves it worth trying again: keep it.
+     *
+     * `attemptId` is a random id (22 to 128 URL-safe characters) the caller
+     * keeps with the legacy session and sends with every exchange of it. The
+     * server binds its single-use claim to it, so a retry after a lost answer is
+     * answered again instead of refused. `refreshToken` is the legacy OAuth
+     * refresh token; the server redeems it only when the access token cannot
+     * prove the session by itself. `timeoutMs` bounds this call, body included
+     * (default: the client's timeout). With an `attemptId`, the answer carries
+     * `apiKeyDescription`: the description to give the API key made with it.
      */
-    async legacyHandoff(legacyToken, appContext) {
-        const res = await this.fetchWithTimeout(`${this.baseOrigin}/api/auth/legacy-handoff`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                ...originHeader(this.baseOrigin),
-                ...(appContext?.projectId ? { 'x-recursiv-app-project': appContext.projectId } : {}),
-                ...(appContext?.organizationId
-                    ? { 'x-recursiv-app-organization': appContext.organizationId }
-                    : {}),
-            },
-            body: JSON.stringify({ legacy_token: legacyToken }),
-        });
-        let data = null;
+    async legacyHandoff(legacyToken, options = {}) {
+        const body = { legacy_token: legacyToken };
+        if (options.attemptId)
+            body.attempt_id = options.attemptId;
+        if (options.refreshToken)
+            body.legacy_refresh_token = options.refreshToken;
+        const timeoutMs = typeof options.timeoutMs === 'number' && options.timeoutMs > 0 ? options.timeoutMs : this.timeout;
+        const fail = (status, code, message, retryAfter = null) => new LegacyHandoffError(status, { type: 'auth_error', code, message, ...(retryAfter !== null ? { retry_after: retryAfter } : {}) });
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
         try {
-            data = await res.json();
-        }
-        catch {
-            data = null;
-        }
-        if (!res.ok) {
-            const { code, message } = serverErrorInfo(data);
-            throw new AuthenticationError({
-                type: 'auth_error',
-                message: message || `Legacy handoff failed: HTTP ${res.status}`,
-                code: code || 'legacy_handoff_failed',
-            });
+            let res;
+            try {
+                res = await fetch(`${this.baseOrigin}/api/auth/legacy-handoff`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        ...originHeader(this.baseOrigin),
+                        ...(options.projectId ? { 'x-recursiv-app-project': options.projectId } : {}),
+                        ...(options.organizationId ? { 'x-recursiv-app-organization': options.organizationId } : {}),
+                    },
+                    body: JSON.stringify(body),
+                    signal: controller.signal,
+                });
+            }
+            catch (err) {
+                if (controller.signal.aborted)
+                    throw fail(0, 'timeout', `Legacy handoff timed out after ${timeoutMs}ms`);
+                const detail = err instanceof Error ? err.message : String(err);
+                throw fail(0, 'network_error', `Legacy handoff failed before a response arrived (${detail})`);
+            }
+            let data = null;
+            try {
+                data = await res.json();
+            }
+            catch {
+                if (controller.signal.aborted)
+                    throw fail(0, 'timeout', `Legacy handoff timed out after ${timeoutMs}ms`);
+                data = null;
+            }
+            if (!res.ok) {
+                const { code, message } = serverErrorInfo(data);
+                throw fail(res.status, code || 'legacy_handoff_failed', message || `Legacy handoff failed: HTTP ${res.status}`, retryAfterHeaderSeconds(res));
+            }
+            const token = this.extractToken(res, data);
+            if (!token || typeof data?.user?.id !== 'string') {
+                throw fail(res.status, 'legacy_handoff_failed', 'Legacy handoff returned no session');
+            }
+            const answer = { token, user: data.user };
+            if (typeof data.api_key_description === 'string' && data.api_key_description)
+                answer.apiKeyDescription = data.api_key_description;
+            return answer;
         }
-        const token = this.extractToken(res, data);
-        if (!token) {
-            throw new AuthenticationError({ type: 'auth_error', message: 'Legacy handoff returned no session', code: 'legacy_handoff_failed' });
+        finally {
+            clearTimeout(timer);
         }
-        return { token, user: data.user };
     }
-    /** legacyHandoff, then the app API key, exactly like verifyOtpAndCreateKey. */
-    async legacyHandoffAndCreateKey(legacyToken, keyInput) {
+    /**
+     * legacyHandoff, then the app API key, exactly like verifyOtpAndCreateKey.
+     * Pass the same `attemptId` (kept with the legacy session) on every call:
+     * a retry after the key step failed is then answered again instead of
+     * refused, and the key is made with the description the answer names.
+     */
+    async legacyHandoffAndCreateKey(legacyToken, keyInput, options = {}) {
         const session = await this.legacyHandoff(legacyToken, {
             projectId: keyInput.projectId,
             organizationId: keyInput.organizationId,
+            attemptId: options.attemptId,
+            refreshToken: options.refreshToken,
+            timeoutMs: options.timeoutMs,
         });
-        const key = await this.createApiKeyOrRetireSession(keyInput, session);
+        const key = await this.createApiKeyOrRetireSession(session.apiKeyDescription && !keyInput.description ? { ...keyInput, description: session.apiKeyDescription } : keyInput, session);
         return { apiKey: key.key, apiKeyId: key.id, user: session.user, session };
     }
     /**
@@ -844,9 +901,13 @@ export class AuthResource {
             method: 'POST',
             credentials: 'include',
             headers: {
+                // JSON Content-Type and body, as in signOut: without them Better Auth
+                // answers 415 before the endpoint runs.
+                'Content-Type': 'application/json',
                 ...originHeader(this.baseOrigin),
                 Authorization: `Bearer ${sessionToken}`,
             },
+            body: '{}',
         });
         let data = null;
         try {

package/dist/resources/commands.d.ts

@@ -6,6 +6,7 @@ interface GatePromptMessage {
 }
 interface GatePromptInput {
     messages: GatePromptMessage[];
+    /** @deprecated Ignored: the server always runs its own gate model. Still accepted so older callers validate. */
     model?: string;
 }
 interface GatePromptResult {
@@ -20,7 +21,13 @@ interface Attachment {
 interface ExecutePromptInput {
     prompt: string;
     current_screen?: string;
+    /**
+     * Organization to run under (its AI provider settings and billing). Must be one
+     * you are a member of on your network that the API key may reach, or the
+     * request fails with 403.
+     */
     org_slug?: string | null;
+    /** @deprecated Ignored: the organization's AI provider settings, or the platform default, pick the model. Kept so older callers validate. */
     model?: string;
     locale?: string;
     attachments?: Attachment[];
@@ -32,7 +39,13 @@ interface ExecutePromptResult {
 export declare class CommandsResource {
     private client;
     constructor(client: HttpClient);
-    /** Run the gatekeeper prompt to evaluate an idea for access */
+    /**
+     * Recursiv's own signup gate: evaluates a visitor's pitch for access to Recursiv.
+     * Not a moderation or guardrail API. It answers only for keys on the platform's
+     * networks (PLATFORM_SIGNUP_NETWORK_SLUGS) and returns 404 anywhere else, including
+     * an app's own network. Calls that reach the model share one global daily budget
+     * (GATE_PROMPT_DAILY_LLM_CALLS) with Recursiv's signup page.
+     */
     gatePrompt(input: GatePromptInput): Promise<SingleResponse<GatePromptResult>>;
     /** Execute a command prompt with AI */
     execute(input: ExecutePromptInput): Promise<SingleResponse<ExecutePromptResult>>;

package/dist/resources/commands.js

@@ -3,7 +3,13 @@ export class CommandsResource {
     constructor(client) {
         this.client = client;
     }
-    /** Run the gatekeeper prompt to evaluate an idea for access */
+    /**
+     * Recursiv's own signup gate: evaluates a visitor's pitch for access to Recursiv.
+     * Not a moderation or guardrail API. It answers only for keys on the platform's
+     * networks (PLATFORM_SIGNUP_NETWORK_SLUGS) and returns 404 anywhere else, including
+     * an app's own network. Calls that reach the model share one global daily budget
+     * (GATE_PROMPT_DAILY_LLM_CALLS) with Recursiv's signup page.
+     */
     gatePrompt(input) {
         return this.client.post('/commands/gate-prompt', input);
     }

package/dist/resources/e2ee.d.ts

@@ -11,6 +11,15 @@ export interface E2eeDevice {
     isRoot: boolean;
     status: 'active' | 'revoked' | string;
     revokedAt: string | null;
+    /** When the relay registered the device (the relay's clock). Absent on relays before 0.7.57. */
+    createdAt?: string;
+    /**
+     * When the device last fetched events, to the hour. Only in your own
+     * directory (`devices()` without `user_id`); null for another account's
+     * devices, when unknown, or when the relay cannot say. Absent on relays
+     * before 0.7.57.
+     */
+    lastSeenAt?: string | null;
 }
 /** Opaque `recursiv-mls-v2-draft1` envelope with base64 MLS bytes. */
 export interface E2eeEnvelope {
@@ -30,6 +39,33 @@ export interface E2eeEvent {
     welcome: string | null;
     createdAt: string;
 }
+/**
+ * The realtime `e2ee:event` doorbell (`r.realtime.onE2eeEvent`), sent after
+ * every append to an encrypted conversation to each member account's sockets.
+ * It never carries plaintext and has no ordering authority.
+ *
+ * `event` is present only for a small application message (an ordinary or a
+ * quiet one; never a commit, never a Welcome, never one whose envelope is over
+ * 16 KB), and only on a socket whose credential could read it with `events()`:
+ * one authenticated by the account owner's session or by an owner key whose
+ * app or organization binding reaches the conversation. A socket opened with
+ * an agent-scoped key gets the content-free form only. When present it is the
+ * stored event exactly as `events()` returns it, JSON byte for byte.
+ *
+ * With the shared engine, hand `event` to `applyPushed(conversationId, event)`
+ * on the device session: it applies the event without a relay read when it is
+ * the next one this device expects, and syncs otherwise. Without `event`, sync.
+ */
+export interface E2eeRealtimeEvent {
+    conversationId: string;
+    /** The relay sequence the append was stored at. */
+    seq: number;
+    /** The stored event, when this socket may carry it (see above). */
+    event?: E2eeEvent & {
+        kind: 'application';
+        welcome: null;
+    };
+}
 /** One-time key packages a device still has to hand out. */
 export interface E2eeKeyPackageStatus {
     /** Unclaimed packages that have not expired. Once this reaches 0 nobody can add the device to a new conversation. */
@@ -37,12 +73,6 @@ export interface E2eeKeyPackageStatus {
     /** Of `available`, how many expire within 7 days. */
     expiringSoon: number;
 }
-/**
- * E2EE v2 ciphertext transport. The server relays envelopes and public
- * credentials only; encryption happens in the shared core on each device.
- * Requires the `e2eeV2` network feature flag and a key acting as the account
- * owner (agent-scoped keys are refused). The realm is the network id.
- */
 /** A reserved encrypted attachment object: PUT exactly `length` bytes of ciphertext to `uploadUrl`, then complete it. */
 export interface E2eeObjectUpload {
     reference: string;
@@ -56,9 +86,111 @@ export interface E2eeObjectDownload {
     downloadUrl: string;
     length: number;
 }
+/**
+ * Why this account cannot use the E2EE relay on its network:
+ * - `network_off`: the network has not turned E2EE v2 on.
+ * - `not_allowlisted`: it is on, but only for pilot accounts, and this is not one.
+ */
+export type E2eeStatusReason = 'network_off' | 'not_allowlisted';
+/** Whether the calling account is admitted to the E2EE relay on its network. */
+export interface E2eeStatus {
+    /**
+     * True: this account may enroll devices, publish key packages, send, and
+     * start encryption in an eligible direct conversation. False: the relay is
+     * frozen for it. Conversations that already carry encryption stay readable
+     * (fetch, acknowledge, object downloads), its own devices can be listed and
+     * revoked, and nothing new can be sent or enrolled. It never falls back to
+     * plaintext.
+     */
+    enabled: boolean;
+    /** Present only when `enabled` is false. Treat any unrecognised reason as off. */
+    reason?: E2eeStatusReason;
+    /**
+     * True when this relay can link a new device by scanning (`createLink`).
+     * False or absent: offer the codes fallback only as a choice the person
+     * makes, never switch to it on their behalf.
+     */
+    links?: boolean;
+}
+/** A device link's state. An open link past `expiresAt` reads as `cancelled` with `cancelledBy: 'expired'`. */
+export type E2eeLinkState = 'open' | 'approved' | 'completed' | 'cancelled';
+/** Why a link was cancelled. */
+export type E2eeLinkCancelledBy = 'creator' | 'superseded' | 'declined' | 'expired';
+/** How far the approving device has got adding the new device to the account's encrypted chats. */
+export interface E2eeLinkProgress {
+    done: number;
+    total: number;
+    joined: number;
+    notHeld: number;
+    failed: number;
+}
+/**
+ * A device link (spec RCV1): the relay's short-lived mailbox between a new
+ * device, which shows a QR code, and an approved device of the same account,
+ * which scans it and posts an approval only the new device can verify. The
+ * relay stores public data only and is not trusted for integrity: the engine
+ * checks the approval's tag, the chain and the directory itself.
+ */
+export interface E2eeLink {
+    /** 128 random bits as unpadded base64url (22 characters); the QR carries these bytes. */
+    id: string;
+    state: E2eeLinkState;
+    deviceName: string;
+    signingKey: string;
+    /** The new device's self-reported label. Chosen by whoever made the link: never show it as the app's own words. */
+    label: string | null;
+    createdAt: string;
+    expiresAt: string;
+    /** The relay's clock when it answered: count down with `expiresAt - now`, never the device's own clock. */
+    now: string;
+    scannedAt: string | null;
+    /** Another link of this account is open (another sign-in is linking too). */
+    otherOpen: boolean;
+    cancelledBy: E2eeLinkCancelledBy | null;
+    /** The approval body and its tag: only for the sign-in that created the link, null for everyone else. */
+    approval: string | null;
+    tag: string | null;
+    approverDeviceId: string | null;
+    progress: E2eeLinkProgress | null;
+    lastConversationId: string | null;
+    needPackages: boolean;
+}
+/**
+ * The realtime `e2ee:link` event (`r.realtime.onE2eeLink`): a link changed.
+ * Content-free; read the link with `link(id)`. There is never an `open` event.
+ */
+export interface E2eeLinkRealtimeEvent {
+    linkId: string;
+    state: 'scanned' | 'approved' | 'completed' | 'progress' | 'cancelled';
+}
+/**
+ * The realtime `e2ee:devices` event (`r.realtime.onE2eeDevices`): `packages`
+ * when one of the account's devices can now be claimed (it published after
+ * having none, or after a claim for it failed); `revoked` when one was revoked.
+ */
+export interface E2eeDevicesRealtimeEvent {
+    deviceId: string;
+    reason: 'packages' | 'revoked';
+}
+/**
+ * E2EE v2 ciphertext transport. The server relays envelopes and public
+ * credentials only; encryption happens in the shared core on each device.
+ * Requires the `e2eeV2` network feature flag and a key acting as the account
+ * owner (agent-scoped keys are refused). The realm is the network id.
+ */
 export declare class E2eeResource {
     private client;
     constructor(client: HttpClient);
+    /**
+     * Whether this account is admitted to encrypted chat on its network, without
+     * attempting a relay call. `{ enabled: true }`, or `{ enabled: false, reason }`
+     * with `reason` `'network_off'` or `'not_allowlisted'`. Only the caller's own
+     * account is described; the network comes from the key or session. Enrolling
+     * a device still needs an accepted two-person DM (or an already-encrypted
+     * conversation) in this key's scope. Agent-scoped keys get
+     * `agent_key_not_allowed`.
+     */
+    status(): Promise<SingleResponse<E2eeStatus>>;
     /** Register this device's public identity and its signed approval chain. */
     registerDevice(input: {
         device_name: string;
@@ -96,12 +228,28 @@ export declare class E2eeResource {
         bytes: string;
         device: E2eeDevice;
     }>>;
+    /**
+     * Append one MLS envelope to an encrypted conversation.
+     *
+     * `silent: true` marks a message that changes an earlier one (a reaction,
+     * an edit, a delete for everyone): the relay sends no push (so no unread
+     * badge either) and does not move the conversation up the chat list. The
+     * `e2ee:event` doorbell still rings exactly as for any message: on the
+     * sockets of every member, the sender's own account included, except
+     * across a block. So every listener hears a quiet event, not only an open
+     * thread: a chat list that pulls on the doorbell pulls it too, and should
+     * leave the row where it is once it has decrypted a reaction, an edit or a
+     * delete. A commit ignores the flag. The relay learns only that the event
+     * is quiet; the flag is not stored. A relay that predates it drops the
+     * key, so the event is simply not quiet there.
+     */
     appendEvent(conversationId: string, input: {
         device_id: string;
         envelope: E2eeEnvelope;
         welcome?: string;
         welcome_for_device_id?: string;
         expected_commit_seq?: number;
+        silent?: boolean;
     }): Promise<SingleResponse<{
         seq: number;
         duplicate: boolean;
@@ -149,4 +297,71 @@ export declare class E2eeResource {
         reference: string;
         deleted: boolean;
     }>>;
+    /**
+     * Start linking this new, not yet registered device: `POST /e2ee/links`.
+     * Answers the open link (180 s on the relay's clock). A new link cancels
+     * this sign-in's previous open link. `label` is 1-48 letters, numbers,
+     * spaces and `. , ' ( ) + -`; reserved words are refused (`invalid_label`).
+     * Not retried: a 5xx is answered at once, and the caller decides.
+     */
+    createLink(input: {
+        device_name: string;
+        signing_key: string;
+        label?: string;
+    }): Promise<SingleResponse<E2eeLink>>;
+    /** Read a link: `GET /e2ee/links/:id`. `approval` and `tag` only for the sign-in that created it. Not retried: poll instead. */
+    link(id: string): Promise<SingleResponse<E2eeLink>>;
+    /** The approving device scanned the code: once per link, it keeps the link open 120 s past the scan. */
+    scannedLink(id: string, input: {
+        device_id: string;
+    }): Promise<SingleResponse<E2eeLink>>;
+    /**
+     * Post the approval body and its tag, once. Retry-safe: the same approving
+     * device is answered 200 on an approved or completed link. The answer never
+     * carries the approval or tag.
+     */
+    approveLink(id: string, input: {
+        device_id: string;
+        approval: string;
+        tag: string;
+    }): Promise<SingleResponse<E2eeLink>>;
+    /** The new device, now registered, finished: the sign-in that created the link only. */
+    completeLink(id: string, input: {
+        device_id: string;
+    }): Promise<SingleResponse<E2eeLink>>;
+    /** The approving device, from the sign-in that approved, reports how many chats it has added the new device to. */
+    linkProgress(id: string, input: {
+        device_id: string;
+        done: number;
+        total: number;
+        joined: number;
+        not_held: number;
+        failed: number;
+        last_conversation_id?: string;
+        need_packages?: boolean;
+    }): Promise<SingleResponse<E2eeLink>>;
+    /**
+     * Cancel a link. The sign-in that created it cancels it while open or
+     * approved; an active device of the account declines an open one with
+     * `{ device_id, reason: 'declined' }`, and once the link is scanned only
+     * from the sign-in that scanned it.
+     */
+    cancelLink(id: string, input?: {
+        device_id?: string;
+        reason?: 'cancelled' | 'declined';
+    }): Promise<SingleResponse<E2eeLink>>;
+    /**
+     * The ids of the encrypted conversations this account belongs to, in this
+     * key's scope, ordered by id: pass `next` as `after` for the next page
+     * (`limit` 1-200, default 100).
+     */
+    conversations(params?: {
+        after?: string;
+        limit?: number;
+    }): Promise<{
+        data: {
+            conversationId: string;
+        }[];
+        next: string | null;
+    }>;
 }

package/dist/resources/e2ee.js

@@ -1,8 +1,26 @@
+/**
+ * E2EE v2 ciphertext transport. The server relays envelopes and public
+ * credentials only; encryption happens in the shared core on each device.
+ * Requires the `e2eeV2` network feature flag and a key acting as the account
+ * owner (agent-scoped keys are refused). The realm is the network id.
+ */
 export class E2eeResource {
     client;
     constructor(client) {
         this.client = client;
     }
+    /**
+     * Whether this account is admitted to encrypted chat on its network, without
+     * attempting a relay call. `{ enabled: true }`, or `{ enabled: false, reason }`
+     * with `reason` `'network_off'` or `'not_allowlisted'`. Only the caller's own
+     * account is described; the network comes from the key or session. Enrolling
+     * a device still needs an accepted two-person DM (or an already-encrypted
+     * conversation) in this key's scope. Agent-scoped keys get
+     * `agent_key_not_allowed`.
+     */
+    status() {
+        return this.client.get('/e2ee/status');
+    }
     /** Register this device's public identity and its signed approval chain. */
     registerDevice(input) {
         return this.client.post('/e2ee/devices', input);
@@ -28,6 +46,21 @@ export class E2eeResource {
     claimKeyPackage(input) {
         return this.client.post('/e2ee/key-packages/claim', input);
     }
+    /**
+     * Append one MLS envelope to an encrypted conversation.
+     *
+     * `silent: true` marks a message that changes an earlier one (a reaction,
+     * an edit, a delete for everyone): the relay sends no push (so no unread
+     * badge either) and does not move the conversation up the chat list. The
+     * `e2ee:event` doorbell still rings exactly as for any message: on the
+     * sockets of every member, the sender's own account included, except
+     * across a block. So every listener hears a quiet event, not only an open
+     * thread: a chat list that pulls on the doorbell pulls it too, and should
+     * leave the row where it is once it has decrypted a reaction, an edit or a
+     * delete. A commit ignores the flag. The relay learns only that the event
+     * is quiet; the flag is not stored. A relay that predates it drops the
+     * key, so the event is simply not quiet there.
+     */
     appendEvent(conversationId, input) {
         // Retries are safe: the server is idempotent on (conversation, device, event id).
         return this.client.post(`/e2ee/conversations/${encodeURIComponent(conversationId)}/events`, input, { retry: true });
@@ -58,4 +91,61 @@ export class E2eeResource {
     deleteObject(objectId, params) {
         return this.client.delete(`/e2ee/objects/${encodeURIComponent(objectId)}?device_id=${encodeURIComponent(params.device_id)}`);
     }
+    // ── Device links (spec RCV1 §6) ──
+    // Names match the engine's optional transport methods, so `r.e2ee` can be
+    // passed to the engine as its transport unchanged. Link refusals are 409
+    // (`link_limit`, `no_root`, `already_registered`, `conflict`), never 429;
+    // `invalid_label` is 400; `storage_unavailable` is a temporary 503: keep
+    // polling until the link's `expiresAt`.
+    /**
+     * Start linking this new, not yet registered device: `POST /e2ee/links`.
+     * Answers the open link (180 s on the relay's clock). A new link cancels
+     * this sign-in's previous open link. `label` is 1-48 letters, numbers,
+     * spaces and `. , ' ( ) + -`; reserved words are refused (`invalid_label`).
+     * Not retried: a 5xx is answered at once, and the caller decides.
+     */
+    createLink(input) {
+        return this.client.post('/e2ee/links', input, { retry: false });
+    }
+    /** Read a link: `GET /e2ee/links/:id`. `approval` and `tag` only for the sign-in that created it. Not retried: poll instead. */
+    link(id) {
+        return this.client.get(`/e2ee/links/${encodeURIComponent(id)}`, undefined, { retry: false });
+    }
+    /** The approving device scanned the code: once per link, it keeps the link open 120 s past the scan. */
+    scannedLink(id, input) {
+        return this.client.post(`/e2ee/links/${encodeURIComponent(id)}/scanned`, input);
+    }
+    /**
+     * Post the approval body and its tag, once. Retry-safe: the same approving
+     * device is answered 200 on an approved or completed link. The answer never
+     * carries the approval or tag.
+     */
+    approveLink(id, input) {
+        return this.client.post(`/e2ee/links/${encodeURIComponent(id)}/approve`, input, { retry: true });
+    }
+    /** The new device, now registered, finished: the sign-in that created the link only. */
+    completeLink(id, input) {
+        return this.client.post(`/e2ee/links/${encodeURIComponent(id)}/complete`, input);
+    }
+    /** The approving device, from the sign-in that approved, reports how many chats it has added the new device to. */
+    linkProgress(id, input) {
+        return this.client.post(`/e2ee/links/${encodeURIComponent(id)}/progress`, input);
+    }
+    /**
+     * Cancel a link. The sign-in that created it cancels it while open or
+     * approved; an active device of the account declines an open one with
+     * `{ device_id, reason: 'declined' }`, and once the link is scanned only
+     * from the sign-in that scanned it.
+     */
+    cancelLink(id, input) {
+        return this.client.post(`/e2ee/links/${encodeURIComponent(id)}/cancel`, input ?? {});
+    }
+    /**
+     * The ids of the encrypted conversations this account belongs to, in this
+     * key's scope, ordered by id: pass `next` as `after` for the next page
+     * (`limit` 1-200, default 100).
+     */
+    conversations(params) {
+        return this.client.get('/e2ee/conversations', params);
+    }
 }

package/dist/resources/human-input.d.ts

@@ -15,6 +15,7 @@ export interface RequestHumanInputInput {
 export interface HumanInputRequest {
     conversation_id: string;
     message_id: string;
+    human_ask_id: string | null;
     /** Where to read the answer. MCP is stateless, so the agent polls. */
     poll: string;
     poll_after_seconds: number;
@@ -45,7 +46,9 @@ export declare class HumanInputResource {
     private client;
     constructor(client: HttpClient);
     /** Raise a blocking question and notify the human wherever they are. */
-    request(input: RequestHumanInputInput): Promise<SingleResponse<HumanInputRequest>>;
+    request(input: RequestHumanInputInput, options?: {
+        requestId?: string;
+    }): Promise<SingleResponse<HumanInputRequest>>;
     /** Has the human answered yet? */
     answers(conversationId: string): Promise<SingleResponse<HumanInputAnswers>>;
 }

package/dist/resources/human-input.js

@@ -17,9 +17,13 @@ export class HumanInputResource {
         this.client = client;
     }
     /** Raise a blocking question and notify the human wherever they are. */
-    request(input) {
-        // This write is not idempotent. A lost response must not replay the ask.
-        return this.client.post('/human-input', input, { retry: false });
+    request(input, options) {
+        // Never automatically replay: chat delivery may have committed before a
+        // response was lost, even when a keyed workspace ask was recorded once.
+        // Callers can reuse a requestId with the exact same input after an
+        // uncertain response. The server claims it against the durable
+        // organization-owned ask row; changed fields need a new requestId.
+        return this.client.post('/human-input', input, { retry: false, idempotencyKey: options?.requestId });
     }
     /** Has the human answered yet? */
     answers(conversationId) {