@recursiv/sdk 0.7.55 → 0.7.57

package/README.md

@@ -75,7 +75,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | Resource | Key methods |
 |----------|------------|
 | `r.agents` | `create`, `update`, `chat`, `chatStream`, `retryChatStream`, `grantProjectAccess`, `conversations` |
-| `r.e2ee` | `status`, `registerDevice`, `devices`, `revokeDevice`, `publishKeyPackages`, `keyPackageStatus`, `claimKeyPackage`, `appendEvent`, `events`, `acknowledge` (flag-gated E2EE v2 transport) |
+| `r.e2ee` | `status`, `registerDevice`, `devices`, `revokeDevice`, `publishKeyPackages`, `keyPackageStatus`, `claimKeyPackage`, `appendEvent`, `events`, `acknowledge`, `conversations`; device linking by scan: `createLink`, `link`, `scannedLink`, `approveLink`, `completeLink`, `linkProgress`, `cancelLink` (flag-gated E2EE v2 transport; its doorbell is `r.realtime.onE2eeEvent`, which carries a small message's stored ciphertext to the owner's own sockets; link and device changes arrive on `r.realtime.onE2eeLink` and `onE2eeDevices`) |
 | `r.brain` | `sendMessage` |
 | `r.commands` | `execute`, `gatePrompt` |
 | `r.projectBrain` | `tasks`, `decisions`, `milestones`, `completeTask`, `usage` |
@@ -115,7 +115,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | `r.admin` | User management, stats, content reports (`listReports`, `resolveReport`, `dismissReport`) |
 | `r.dispatcher` | Task queue, claims, signals, outcomes, webhooks |
 | `r.goals` | Org goals with task rollups (group dispatcher tasks) |
-| `r.protocols` | Private Minds safety: `sourceControls` (current enablement and saved choices; filter with `control`, each item may carry a `display` label), `setSourceControl`, `onSourceControlChange`, `reportSource`. Delegated accounts: `nativeSocialAccounts`, `startNativeSocialConnection`, `finishNativeSocialConnection`, `disconnectNativeSocialAccount`. Native follows: `nativeFollowStates` (every connected account's state for one source, one read), `nativeFollowState`, `prepareNativeFollow`, `submitNativeFollow`, `nativeFollowStatus` (native following or pending approval, distinct from a Minds feed subscription; preserve the complete signed Nostr list). Native reposts and undo: `nativeRepostState`, `prepareNativeRepost`, `submitNativeRepost`, `nativeRepostStatus` (public posts, explicit approval, connected account, no uncertain retries). Native likes and unlikes: `nativeLikeState`, `prepareNativeLike`, `submitNativeLike`, `nativeLikeStatus` (connected authority, app enablement and explicit approval; resume pending actions instead of duplicating them). Reviewed replies and optional linked posts: `prepareNativeReply`, `submitNativeReply`, `nativeReplyStatus`, `nativeReplyHistory`, `prepareNativeReplyRemoval`, `removeNativeReply` (require deployed API support and app enablement). Keyless shared post links: `sharedNetworks(projectId)`, `getSharedConversation(projectId, { protocol, post, readRef? })`. Member public reading: `searchPublicPosts` (selected account required for Bluesky/ActivityPub; public Nostr search), `getConnectedSocialConversation` (preserve result readerAccountId/readRef), `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; radar stories: `getPublicRadarStory` (one story by id with its posts; one that has left the radar comes with its archived copy and the live story it continues as), keyless `getSharedRadarStory(projectId, { cluster })` and `getSharedRadarPosts(projectId, { cluster })` (keyless reads carry images and videos only from outlets and members marked `visitorMedia`; signed-in reads keep all media, so a share card uses only those); private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. `list` returns bounded adapter `maturity`, `limitations`, and exhaustive `supported`/`planned`/`unsupported` implementation capabilities (not provider health or enablement); settings, candidate refresh/status, search, and read-only quarantined candidate review via `listCandidates` / `getCandidate` |
+| `r.protocols` | Private Minds safety: `sourceControls` (current enablement and saved choices; filter with `control`, each item may carry a `display` label), `setSourceControl`, `onSourceControlChange`, `reportSource`. Delegated accounts: `nativeSocialAccounts`, `startNativeSocialConnection`, `finishNativeSocialConnection`, `disconnectNativeSocialAccount`. Native follows: `nativeFollowStates` (every connected account's state for one source, one read), `nativeFollowState`, `prepareNativeFollow`, `submitNativeFollow`, `nativeFollowStatus` (native following or pending approval, distinct from a Minds feed subscription; preserve the complete signed Nostr list). Native reposts and undo: `nativeRepostState`, `prepareNativeRepost`, `submitNativeRepost`, `nativeRepostStatus` (public posts, explicit approval, connected account, no uncertain retries). Native likes and unlikes: `nativeLikeState`, `prepareNativeLike`, `submitNativeLike`, `nativeLikeStatus` (connected authority, app enablement and explicit approval; resume pending actions instead of duplicating them). Reviewed replies and optional linked posts: `prepareNativeReply`, `submitNativeReply`, `nativeReplyStatus`, `nativeReplyHistory`, `prepareNativeReplyRemoval`, `removeNativeReply` (require deployed API support and app enablement). Keyless shared post links: `sharedNetworks(projectId)`, `getSharedConversation(projectId, { protocol, post, readRef? })`. Member public reading: `searchPublicPosts` (selected account required for Bluesky/ActivityPub; public Nostr search), `getConnectedSocialConversation` (preserve result readerAccountId/readRef), `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; radar stories: `getPublicRadarStory` (one story by id with its posts; one that has left the radar comes with its archived copy and the live story it continues as; the id may be a World Today edition story's, and the answer then names it in `editionStory` under the story's radar id), keyless `getSharedRadarStory(projectId, { cluster })` and `getSharedRadarPosts(projectId, { cluster })` (keyless reads carry images and videos only from outlets and members marked `visitorMedia`; signed-in reads keep all media, so a share card uses only those); private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. `list` returns bounded adapter `maturity`, `limitations`, and exhaustive `supported`/`planned`/`unsupported` implementation capabilities (not provider health or enablement); settings, candidate refresh/status, search, and read-only quarantined candidate review via `listCandidates` / `getCandidate` |
 
 Full reference: see [llm.md](./llm.md) (ships with this package) or the type definitions in `dist/`.
 
@@ -351,7 +351,7 @@ import {
   AuthorizationError,   // 403 — API key lacks required scope
   NotFoundError,        // 404
   ValidationError,      // 400 — check error.details
-  RateLimitError,       // 429 — includes retryAfter, upgradeUrl
+  RateLimitError,       // 429 — includes retryAfter, resetAt, scope, upgradeUrl
   ConflictError,        // 409
 } from '@recursiv/sdk'
 
@@ -364,7 +364,7 @@ try {
 }
 ```
 
-Auto-retry is built in. 429 and 5xx responses retry with exponential backoff (configurable via `maxRetries`, default 2).
+Auto-retry is built in. 429 and 5xx responses retry with exponential backoff (configurable via `maxRetries`, default 2). A 429 with `X-RateLimit-Scope: action` refuses one member action past its budget and is never retried: its `RateLimitError` has `scope: 'action'` and `resetAt` (a `Date`, when that action's budget reopens).
 
 ## Pagination
 

package/dist/client.js

@@ -1,4 +1,4 @@
-import { RecursivError, AuthenticationError, AuthorizationError, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, errorBodyFromResponse, httpStatusMessage, } from './errors.js';
+import { RecursivError, AuthenticationError, AuthorizationError, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, errorBodyFromResponse, httpStatusMessage, isActionRateLimitScope, rateLimitDetailsFromResponse, } from './errors.js';
 const DEFAULT_BASE_URL = 'https://api.recursiv.io/api/v1';
 export class HttpClient {
     #apiKey;
@@ -59,6 +59,13 @@ export class HttpClient {
             if (response.status === 429 || response.status >= 500) {
                 if (attempt === this.maxRetries)
                     return response;
+                // X-RateLimit-Scope: action refuses this one action (a post, a follow,
+                // a report) past the member's budget. The API is not busy: the same
+                // request is refused again until the budget reopens, or, sent late,
+                // becomes a write the member saw refused. The caller gets the 429 now,
+                // with RateLimitError.scope and resetAt.
+                if (response.status === 429 && isActionRateLimitScope(response.headers))
+                    return response;
                 const retryAfter = response.headers.get('retry-after');
                 const delay = retryAfter
                     ? parseInt(retryAfter, 10) * 1000
@@ -163,7 +170,7 @@ export class HttpClient {
             case 409:
                 throw new ConflictError(err);
             case 429:
-                throw new RateLimitError(err);
+                throw new RateLimitError(err, rateLimitDetailsFromResponse(response.headers, err));
             default:
                 throw new RecursivError(response.status, err);
         }

package/dist/errors.d.ts

@@ -50,9 +50,36 @@ export declare class InsufficientCreditsError extends RecursivError {
     readonly upgradeUrl: string;
     constructor(body: ApiErrorBody['error']);
 }
+/** What a 429 says beyond its body: which budget refused it, and when that budget reopens. */
+export interface RateLimitDetails {
+    /**
+     * `'action'` when the server refused one member action past its budget
+     * (a post, a follow, a report: `X-RateLimit-Scope: action`). Only that
+     * action is refused, the rest of the API is not busy, and sending it again
+     * before `resetAt` is refused again. `undefined` for any other 429.
+     */
+    scope?: 'action';
+    /**
+     * When the refused budget reopens, for showing in the member's local time.
+     * From `X-RateLimit-Reset`, else `Retry-After`, else the body's
+     * `retry_after`; `undefined` when none of them says.
+     */
+    resetAt?: Date;
+}
+/** Whether a response's headers mark its 429 as refusing one action (`X-RateLimit-Scope: action`). */
+export declare function isActionRateLimitScope(headers: Pick<Headers, 'get'> | null | undefined): boolean;
+/**
+ * The scope and reset of a 429, read from its headers, and from the body's
+ * `retry_after` (seconds) when neither reset header was sent.
+ */
+export declare function rateLimitDetailsFromResponse(headers: Pick<Headers, 'get'> | null | undefined, body?: Pick<ApiErrorBody['error'], 'retry_after'>, now?: number): RateLimitDetails;
 export declare class RateLimitError extends RecursivError {
     readonly upgradeUrl: string;
-    constructor(body: ApiErrorBody['error']);
+    /** `'action'` when only this one action was refused (see RateLimitDetails.scope); otherwise undefined. */
+    readonly scope?: 'action';
+    /** When the refused budget reopens (see RateLimitDetails.resetAt); undefined when the server did not say. */
+    readonly resetAt?: Date;
+    constructor(body: ApiErrorBody['error'], details?: RateLimitDetails);
 }
 export declare class ConflictError extends RecursivError {
     constructor(body: ApiErrorBody['error']);

package/dist/errors.js

@@ -110,11 +110,70 @@ export class InsufficientCreditsError extends RecursivError {
         this.message += `\n  Upgrade: ${this.upgradeUrl}`;
     }
 }
+/** Whether a response's headers mark its 429 as refusing one action (`X-RateLimit-Scope: action`). */
+export function isActionRateLimitScope(headers) {
+    return headers?.get?.('x-ratelimit-scope')?.trim().toLowerCase() === 'action';
+}
+// A bare number below this is seconds from now, not an epoch (1e9 s is 2001-09-09).
+const EPOCH_SECONDS_FLOOR = 1e9;
+// A bare number at or above this is epoch milliseconds (1e12 ms is 2001-09-09).
+const EPOCH_MS_FLOOR = 1e12;
+function dateOrUndefined(ms) {
+    return Number.isFinite(ms) ? new Date(ms) : undefined;
+}
+/** X-RateLimit-Reset: epoch seconds from Recursiv; epoch ms, seconds from now or an ISO/HTTP date elsewhere. */
+function resetFromRateLimitReset(raw, now) {
+    const value = raw?.trim();
+    if (!value)
+        return undefined;
+    if (/^\d+(\.\d+)?$/.test(value)) {
+        const n = Number(value);
+        if (n >= EPOCH_MS_FLOOR)
+            return dateOrUndefined(n);
+        if (n >= EPOCH_SECONDS_FLOOR)
+            return dateOrUndefined(n * 1000);
+        return dateOrUndefined(now + n * 1000);
+    }
+    return dateOrUndefined(Date.parse(value));
+}
+/** Retry-After: seconds from now, or an HTTP date. */
+function resetFromRetryAfter(raw, now) {
+    const value = raw?.trim();
+    if (!value)
+        return undefined;
+    if (/^\d+$/.test(value))
+        return dateOrUndefined(now + Number(value) * 1000);
+    return dateOrUndefined(Date.parse(value));
+}
+/**
+ * The scope and reset of a 429, read from its headers, and from the body's
+ * `retry_after` (seconds) when neither reset header was sent.
+ */
+export function rateLimitDetailsFromResponse(headers, body, now = Date.now()) {
+    const retryAfterSeconds = body?.retry_after;
+    const resetAt = resetFromRateLimitReset(headers?.get?.('x-ratelimit-reset'), now)
+        ?? resetFromRetryAfter(headers?.get?.('retry-after'), now)
+        ?? (typeof retryAfterSeconds === 'number' && retryAfterSeconds >= 0
+            ? dateOrUndefined(now + retryAfterSeconds * 1000)
+            : undefined);
+    const details = {};
+    if (isActionRateLimitScope(headers))
+        details.scope = 'action';
+    if (resetAt)
+        details.resetAt = resetAt;
+    return details;
+}
 export class RateLimitError extends RecursivError {
     upgradeUrl;
-    constructor(body) {
+    /** `'action'` when only this one action was refused (see RateLimitDetails.scope); otherwise undefined. */
+    scope;
+    /** When the refused budget reopens (see RateLimitDetails.resetAt); undefined when the server did not say. */
+    resetAt;
+    constructor(body, details = {}) {
         super(429, body);
         this.name = 'RateLimitError';
+        this.scope = details.scope;
+        this.resetAt = details.resetAt;
         this.upgradeUrl = body?.upgrade_url || body.details?.upgrade_url || 'https://recursiv.io/pricing';
         // Append upgrade hint for free tier users
         if (body.message?.includes('free tier') ||

package/dist/index.d.ts

@@ -154,7 +154,7 @@ export { UsersResource } from './resources/users.js';
 export { CommunitiesResource } from './resources/communities.js';
 export { ChatResource } from './resources/chat.js';
 export { E2eeResource } from './resources/e2ee.js';
-export type { E2eeDevice, E2eeEnvelope, E2eeEvent, E2eeKeyPackageStatus, E2eeObjectDownload, E2eeObjectUpload, E2eeStatus, E2eeStatusReason } from './resources/e2ee.js';
+export type { E2eeDevice, E2eeDevicesRealtimeEvent, E2eeEnvelope, E2eeEvent, E2eeKeyPackageStatus, E2eeLink, E2eeLinkCancelledBy, E2eeLinkProgress, E2eeLinkRealtimeEvent, E2eeLinkState, E2eeObjectDownload, E2eeObjectUpload, E2eeRealtimeEvent, E2eeStatus, E2eeStatusReason, } from './resources/e2ee.js';
 export { ProjectsResource } from './resources/projects.js';
 export { AgentsResource, SUPPORTED_MODELS } from './resources/agents.js';
 export { EvidenceResource } from './resources/evidence.js';
@@ -240,7 +240,8 @@ export { TemplatesResource } from './resources/templates.js';
 export type { Template, CreateTemplateInput, UpdateTemplateInput, ListTemplatesParams } from './resources/templates.js';
 export { MediaResource } from './resources/media.js';
 export type { GenerateImageInput, GeneratedImage, ImageProvider } from './resources/media.js';
-export { RecursivError, AuthenticationError, AuthorizationError, LegacyHandoffError, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, } from './errors.js';
+export { RecursivError, AuthenticationError, AuthorizationError, LegacyHandoffError, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, isActionRateLimitScope, } from './errors.js';
+export type { RateLimitDetails } from './errors.js';
 export { parseSSE } from './lib/sse.js';
 export * from './lib/webhooks.js';
 export type * from './types.js';

package/dist/index.js

@@ -277,6 +277,6 @@ export { HumanInputResource } from './resources/human-input.js';
 export { SwarmsResource } from './resources/swarms.js';
 export { TemplatesResource } from './resources/templates.js';
 export { MediaResource } from './resources/media.js';
-export { RecursivError, AuthenticationError, AuthorizationError, LegacyHandoffError, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, } from './errors.js';
+export { RecursivError, AuthenticationError, AuthorizationError, LegacyHandoffError, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, isActionRateLimitScope, } from './errors.js';
 export { parseSSE } from './lib/sse.js';
 export * from './lib/webhooks.js';

package/dist/realtime.d.ts

@@ -1,5 +1,6 @@
 import type { Socket } from 'socket.io-client';
 import { HttpClient } from './client.js';
+import type { E2eeDevicesRealtimeEvent, E2eeLinkRealtimeEvent, E2eeRealtimeEvent } from './resources/e2ee.js';
 export interface ChatMessageEvent {
     id: string;
     conversationId: string;
@@ -145,7 +146,8 @@ export declare class RealtimeClient {
      * replacement. Returns an unsubscribe function.
      *
      * Server events include `notification`, `feed_update`,
-     * `conversation_created`, `chat_message`, `chat_typing` and `agent_thinking`.
+     * `conversation_created`, `chat_message`, `chat_typing`, `agent_thinking`,
+     * `e2ee:event`, `e2ee:link` and `e2ee:devices`.
      */
     on<T = unknown>(event: string, listener: (payload: T) => void): () => void;
     /** Join a conversation room now, and again after every reconnect, until you leave it. */
@@ -157,4 +159,25 @@ export declare class RealtimeClient {
     onMessageDelete(callback: (msg: ChatMessageDeleteEvent) => void): (() => void) | undefined;
     onTyping(callback: (event: TypingEvent) => void): (() => void) | undefined;
     onAgentThinking(callback: (event: AgentThinkingEvent) => void): (() => void) | undefined;
+    /**
+     * The E2EE doorbell after each append to an encrypted conversation this
+     * account belongs to: `{ conversationId, seq }`, plus the stored `event`
+     * when this socket may carry it (see E2eeRealtimeEvent). Pass `event` to the
+     * engine's `applyPushed`; without one, sync the conversation.
+     */
+    onE2eeEvent(callback: (event: E2eeRealtimeEvent) => void): () => void;
+    /**
+     * A device link of this account changed: `{ linkId, state }`, state
+     * `scanned`, `approved`, `completed`, `progress` (at most once a second) or
+     * `cancelled`. Only on sockets opened by a sign-in with the link's exact
+     * binding; there is never an event when a link opens. Read the link with
+     * `r.e2ee.link(linkId)`; poll as well, since an event can be missed.
+     */
+    onE2eeLink(callback: (event: E2eeLinkRealtimeEvent) => void): () => void;
+    /**
+     * One of this account's devices changed in a way the others act on:
+     * `{ deviceId, reason: 'packages' }` when it can now be claimed, or
+     * `{ deviceId, reason: 'revoked' }`.
+     */
+    onE2eeDevices(callback: (event: E2eeDevicesRealtimeEvent) => void): () => void;
 }

package/dist/realtime.js

@@ -368,7 +368,8 @@ export class RealtimeClient {
      * replacement. Returns an unsubscribe function.
      *
      * Server events include `notification`, `feed_update`,
-     * `conversation_created`, `chat_message`, `chat_typing` and `agent_thinking`.
+     * `conversation_created`, `chat_message`, `chat_typing`, `agent_thinking`,
+     * `e2ee:event`, `e2ee:link` and `e2ee:devices`.
      */
     on(event, listener) {
         // Every call is its own subscription, even for a function that is already
@@ -425,4 +426,31 @@ export class RealtimeClient {
     onAgentThinking(callback) {
         return this.on('agent_thinking', callback);
     }
+    /**
+     * The E2EE doorbell after each append to an encrypted conversation this
+     * account belongs to: `{ conversationId, seq }`, plus the stored `event`
+     * when this socket may carry it (see E2eeRealtimeEvent). Pass `event` to the
+     * engine's `applyPushed`; without one, sync the conversation.
+     */
+    onE2eeEvent(callback) {
+        return this.on('e2ee:event', callback);
+    }
+    /**
+     * A device link of this account changed: `{ linkId, state }`, state
+     * `scanned`, `approved`, `completed`, `progress` (at most once a second) or
+     * `cancelled`. Only on sockets opened by a sign-in with the link's exact
+     * binding; there is never an event when a link opens. Read the link with
+     * `r.e2ee.link(linkId)`; poll as well, since an event can be missed.
+     */
+    onE2eeLink(callback) {
+        return this.on('e2ee:link', callback);
+    }
+    /**
+     * One of this account's devices changed in a way the others act on:
+     * `{ deviceId, reason: 'packages' }` when it can now be claimed, or
+     * `{ deviceId, reason: 'revoked' }`.
+     */
+    onE2eeDevices(callback) {
+        return this.on('e2ee:devices', callback);
+    }
 }

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. */
@@ -69,6 +105,72 @@ export interface E2eeStatus {
     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
@@ -195,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

@@ -91,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/protocols.d.ts

@@ -970,8 +970,22 @@ export interface SocialPost {
     replyCount: number | null;
     likeCount: number | null;
     repostCount: number | null;
+    /** Posts quoting this one, only where the provider reports it (Bluesky's AppView, Mastodon 4.5 and later). Absent when unknown. */
+    quoteCount?: number;
     /**
-     * When the counts were read from the source network. Present only on a post a category feed served
+     * Who counted the numbers above: `appview` (Bluesky's AppView, across the network), `instance_local`
+     * (one Fediverse server's view of the post) or `provider_reported` (a third party's unsigned figures,
+     * Primal's for Nostr: show them as reported by Primal, never as verified). Absent when the post has no counts.
+     */
+    countsOrigin?: 'appview' | 'instance_local' | 'provider_reported';
+    /**
+     * Nostr: distinct people, never the author, behind the signed zap receipts the provider returned for
+     * the note (each receipt and its zap request signature-checked). A lower bound; sats are not counted.
+     */
+    distinctZappers?: number;
+    /**
+     * When the counts were read from the source network, at the earliest (they can be up to one index
+     * snapshot interval newer, never older). Present only on a post a category feed served
      * from the open-network index, whose copy can be older than the page (the server refreshes counts
      * older than 15 minutes when the provider answers in time). Absent: the counts are from this read.
      */
@@ -995,6 +1009,15 @@ export interface SocialPost {
     } | {
         state: 'unavailable';
     };
+    /**
+     * Present, and only then, when the ActivityPub author opted out of indexing (`noindex`,
+     * `indexable: false`, or #nobot, #noindex or #noai in their bio). The keyless trends, trend-feed and
+     * radar reads leave such posts out, and no post served from the source index is one. The keyless
+     * author-feed and conversation reads (a profile or a post someone opened) and member reads of a
+     * provider window still return them with this mark, so an app should never re-share or promote one
+     * to signed-out visitors.
+     */
+    authorOptOut?: true;
 }
 export interface SocialPostSearch {
     items: SocialPost[];
@@ -1243,6 +1266,11 @@ export interface SocialRadarStory {
         id: string;
         label: string;
     } | null;
+    /**
+     * Present when the story was asked for by a World Today edition story's id: the radar story that edition story
+     * seeded, and `id` is its radar id, the address to link to. A server that cannot resolve edition story ids answers 400.
+     */
+    editionStory?: string;
 }
 /** Read options for callers that hold their own deadline, such as a discovery page. */
 export interface SocialReadOptions {
@@ -1352,7 +1380,7 @@ export declare class ProtocolsResource {
     getSharedRadarPosts(projectId: string, params: {
         cluster: string;
     }): Promise<SingleResponse<SocialRadarPosts>>;
-    /** One radar story by id with its posts, without a key: a story page or shared link in one call. */
+    /** One radar story by id with its posts, without a key: a story page or shared link in one call. `cluster` may be a World Today edition story's id. */
     getSharedRadarStory(projectId: string, params: {
         cluster: string;
     }): Promise<SingleResponse<SocialRadarStory>>;
@@ -1417,7 +1445,10 @@ export declare class ProtocolsResource {
     getPublicRadarPosts(params: {
         cluster: string;
     }, options?: SocialReadOptions): Promise<SingleResponse<SocialRadarPosts>>;
-    /** One radar story by id with its posts under the app's own key; `status` tells an aged-out story from an unknown one. */
+    /**
+     * One radar story by id with its posts under the app's own key; `status` tells an aged-out story from an unknown one.
+     * `cluster` may be a World Today edition story's id (see SocialRadarStory.editionStory).
+     */
     getPublicRadarStory(params: {
         cluster: string;
     }, options?: SocialReadOptions): Promise<SingleResponse<SocialRadarStory>>;

package/dist/resources/protocols.js

@@ -113,7 +113,7 @@ export class ProtocolsResource {
     getSharedRadarPosts(projectId, params) {
         return this.client.get(`/protocols/public/${encodeURIComponent(projectId)}/radar/posts`, { cluster: params.cluster });
     }
-    /** One radar story by id with its posts, without a key: a story page or shared link in one call. */
+    /** One radar story by id with its posts, without a key: a story page or shared link in one call. `cluster` may be a World Today edition story's id. */
     getSharedRadarStory(projectId, params) {
         return this.client.get(`/protocols/public/${encodeURIComponent(projectId)}/radar/story`, { cluster: params.cluster });
     }
@@ -181,7 +181,10 @@ export class ProtocolsResource {
     getPublicRadarPosts(params, options) {
         return this.client.get('/protocols/social/radar/posts', { cluster: params.cluster }, ...readOptions(options));
     }
-    /** One radar story by id with its posts under the app's own key; `status` tells an aged-out story from an unknown one. */
+    /**
+     * One radar story by id with its posts under the app's own key; `status` tells an aged-out story from an unknown one.
+     * `cluster` may be a World Today edition story's id (see SocialRadarStory.editionStory).
+     */
     getPublicRadarStory(params, options) {
         return this.client.get('/protocols/social/radar/story', { cluster: params.cluster }, ...readOptions(options));
     }

package/llm.md

@@ -516,6 +516,22 @@ await r.e2ee.appendEvent(conversationId, { device_id: device.id, envelope }); //
 await r.e2ee.appendEvent(conversationId, { device_id: device.id, envelope: reaction, silent: true }); // no push, no move up the chat list; every member's doorbell still rings
 const { data: page } = await r.e2ee.events(conversationId, { device_id: device.id, after_seq: 0 });
 await r.e2ee.acknowledge(conversationId, { device_id: device.id, seq: page.headSeq });
+// Doorbell after every append: { conversationId, seq, event? }. `event` (a small application message, as events() returns it) comes only to a socket of the owner's session or an owner key, never an agent-scoped key.
+r.realtime.onE2eeEvent(({ conversationId, event }) => (event ? controller.applyPushed(conversationId, event) : controller.sync(conversationId)));
+```
+
+Link a new device by scanning (0.7.57; `status()` reports `links: true` when the relay can). The new device N shows the link id in a QR code; an approved device A of the same account scans it. The relay is a short-lived mailbox (180 s, 120 s more once scanned; one open link per sign-in, at most 3 per account; 10 creates per sign-in and 20 per account an hour, refused with 409 `link_limit`, never 429). `approval` and `tag` go only to the sign-in that created the link. Reserved labels get 400 `invalid_label`; a 503 `storage_unavailable` is temporary, so keep polling until `expiresAt`. Own devices carry `createdAt` and `lastSeenAt`.
+
+```ts
+const { data: link } = await r.e2ee.createLink({ device_name, signing_key, label: 'Pixel 9' }); // on N; count down with expiresAt - now
+await r.e2ee.scannedLink(link.id, { device_id: a.id });                                          // on A, after the scan
+await r.e2ee.approveLink(link.id, { device_id: a.id, approval, tag });                           // retry-safe
+const { data: mine } = await r.e2ee.link(link.id);                                               // N polls, or on r.realtime.onE2eeLink(({ linkId, state }) => ...)
+await r.e2ee.completeLink(link.id, { device_id: n.id });                                         // N, once registered
+await r.e2ee.linkProgress(link.id, { device_id: a.id, done: 3, total: 7, joined: 3, not_held: 0, failed: 0, last_conversation_id });
+await r.e2ee.cancelLink(link.id, { device_id: a.id, reason: 'declined' });                       // "I didn't start this"
+const { data: ids, next } = await r.e2ee.conversations({ limit: 200 });                          // encrypted chat ids, keyset-paged
+r.realtime.onE2eeDevices(({ deviceId, reason }) => {}); // 'packages': it can be claimed now; 'revoked'
 ```
 
 ### r.realtime — WebSocket Chat Client
@@ -551,7 +567,7 @@ unsub()
 const off = r.realtime.on('notification', (n) => refreshBadge(n))
 ```
 
-Events: `onMessage`, `onMessageEdit`, `onMessageDelete`, `onTyping`, `onAgentThinking`, `on(event, fn)`
+Events: `onMessage`, `onMessageEdit`, `onMessageDelete`, `onTyping`, `onAgentThinking`, `onE2eeEvent`, `onE2eeLink`, `onE2eeDevices`, `on(event, fn)`
 
 Reconnects on its own (transport drops, token expiry, refused handshakes) with jittered backoff and a fresh single-use token per attempt; listeners and joined rooms carry over, so no app-side reconnect shim is needed. It stops only on `disconnect()` or a 401/403 from the token source. `connect()` is safe to call repeatedly.
 
@@ -809,10 +825,10 @@ Pagination: pass `limit` and `offset`. Check `meta.has_more`.
 | `AuthorizationError` | 403 | API key lacks required scope |
 | `NotFoundError` | 404 | Resource doesn't exist or no access |
 | `ValidationError` | 400 | Invalid input (check `error.details`) |
-| `RateLimitError` | 429 | Rate limit hit (`error.retryAfter` seconds) |
+| `RateLimitError` | 429 | Rate limit hit (`retryAfter` seconds, `resetAt` Date, `scope`) |
 | `ConflictError` | 409 | Resource already exists |
 
-Auto-retry on 429/5xx built in (exponential backoff, default `maxRetries: 2`). Member actions with a per-member budget are sent once and never auto-retried: `reports.create`, `moderation.appeal` and `protocols.reportSource` throw the 429 at once (`RateLimitError`, `message` is member-facing, `retryAfter` = seconds until the window opens; a budget refusal carries `X-RateLimit-Scope: action` and no `Retry-After` header).
+Auto-retry on 429/5xx built in (exponential backoff, default `maxRetries: 2`), except a 429 with `X-RateLimit-Scope: action` (one member action past its budget): never retried, `RateLimitError.scope === 'action'`, `resetAt` = when it reopens; show it on that action, do not pause the app. Member actions with a per-member budget are sent once and never auto-retried: `reports.create`, `moderation.appeal` and `protocols.reportSource` throw the 429 at once (`RateLimitError`, `message` is member-facing, `retryAfter` = seconds until the window opens; a budget refusal carries `X-RateLimit-Scope: action` and no `Retry-After` header).
 
 ### Idempotency
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recursiv/sdk",
-  "version": "0.7.55",
+  "version": "0.7.57",
   "description": "TypeScript SDK for the Recursiv API",
   "license": "FSL-1.1-ALv2",
   "type": "module",