@recursiv/sdk 0.7.54 → 0.7.55

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` | `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` (flag-gated E2EE v2 transport) |
 | `r.brain` | `sendMessage` |
 | `r.commands` | `execute`, `gatePrompt` |
 | `r.projectBrain` | `tasks`, `decisions`, `milestones`, `completeTask`, `usage` |
@@ -84,7 +84,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 ### Identity & Auth
 | Resource | Key methods |
 |----------|------------|
-| `r.auth` | `signUp`, `signIn`, `signInWithUsername`, `getSession`, `signOut`, `createApiKey`, `forgetPassword`, `resetPassword`; two-factor: `enableTwoFactor`, `verifyTwoFactor`, `disableTwoFactor`, `regenerateTwoFactorBackupCodes`, `requestTwoFactorEmailCode`, `completeTwoFactorSignIn`; OAuth consent: `exchangeSessionForCookie`, `getOAuthClientInfo` (session calls use explicit Bearer auth with a native/server Cookie fallback) |
+| `r.auth` | `signUp`, `signIn`, `signInWithUsername`, `getSession`, `signOut`, `createApiKey`, `forgetPassword`, `resetPassword`; two-factor: `enableTwoFactor`, `verifyTwoFactor`, `disableTwoFactor`, `regenerateTwoFactorBackupCodes`, `requestTwoFactorEmailCode`, `completeTwoFactorSignIn`; OAuth consent: `exchangeSessionForCookie`, `getOAuthClientInfo`; cutover: `legacyHandoff` (a legacy Minds session for a session here; throws `LegacyHandoffError`) (session calls use explicit Bearer auth with a native/server Cookie fallback) |
 | `@recursiv/sdk/next` | `createRecursivAuth` — cookie-session server auth for Next.js App Router (see below) |
 | `r.users` | `me`, `get` |
 | `r.organizations` | `create`, `members`, `addMember`, `invite` |
@@ -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 })`; 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), 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/`.
 
@@ -689,20 +689,29 @@ category, refreshed after 30 s, kept up to 300 s and warmed as the warmer reache
 viewer's `people` and `groups`; a section that timed out, failed or is off is empty with a
 `reason` for that request only (a failure is never cached, so asking again retries it), and one this
 key may not read is empty with `refused` (`stories` and `network` need the member's own app
-key with `users:read`; `people` and `groups` need `users:read`). In a category, a Bluesky
-topic the provider no longer lists, or whose feed holds nothing in the category, is served
-the network's indexed posts in it (`sourceIndex.reason` of `gone` or `empty`). While the
-provider has more of the topic the page's cursor is the provider's own, so the topic's
-deeper pages are still read; once it has none, or the topic is gone, the cursor is an
-`idx:tf:` one that continues in the index. When the index cannot answer (busy, or its safety
-cache unreadable), the page is what the provider answered: the empty page with its own
-cursor, or the gone topic's 404; only an `idx:tf:` page answers 503 `unavailable`, and that
-ends the index continuation, not the network. The app contract: a `trend_unavailable` 404,
-an empty topic page or a failed `idx:tf:` page never disables a network for the session;
-move to the next topic, keep every provider continuation, start the `idx:tf:` stream once
-per network and session (every such topic answers the same index stream; after a failed
-page it may start again), and pass cursors back unchanged. `DiscoveryFeedSession` does
-this for you.
+key with `users:read`; `people` and `groups` need `users:read`). A plain category page
+(`posts.list({ category })` with no other filter) reads on past a slice the safety floors
+thinned, up to six reads, until it holds `limit` posts or its candidates end: `meta.scanned`
+is how many it examined (the next offset is `offset + scanned`), and the stage ends on the
+page that reaches its end, with `next` and `fallover`, rather than after a trail of empty
+pages. In a category, Discover's read of Bluesky (`getPublicTrends` with `category` and
+`discovery: true`) is the network's posts judged into the category from the source index,
+as a page of posts with an `idx:tf:` cursor (pass it back to `getPublicTrends`), not the
+topic catalog, which ignores the category; with the index off the catalog is answered as
+before. A Bluesky topic feed in a category whose topic is gone, or whose page holds nothing
+in the category, is served the network's indexed posts in it (`sourceIndex.reason` of `gone`
+or `empty`) with an `idx:tf:` cursor that continues in the index; the provider's deeper pages
+of such a topic are not read. In a category, a network's feed ends when its source does (a null
+cursor) or on the third page in a row that shows no posts: an `idx:` cursor carries that count,
+so pass it back unchanged; a provider's own cursor continues until the provider ends it. While a
+category is read from the index, the server reads one Bluesky catalog topic a minute into it in
+the background. When the index cannot answer (busy, or its safety cache unreadable), the page
+is what the provider answered: the empty page, or the gone topic's 404; only an `idx:tf:` page
+answers 503 `unavailable`, and that ends the index continuation, not the network. The app
+contract: a `trend_unavailable` 404, an empty topic page or a failed `idx:tf:` page never
+disables a network for the session; move to the next topic, start the `idx:tf:` stream once per network and session
+(every such topic answers the same index stream; after a failed page it may start again),
+and pass cursors back unchanged. `DiscoveryFeedSession` does this for you.
 
 `sdk.posts.categories()` answers the app's categories in the order this member
 should see them. `meta.order` is `personal`, `popular` or `static`; `meta.reason`

package/dist/client.d.ts

@@ -35,6 +35,7 @@ export declare class HttpClient {
     }): Promise<T>;
     post<T>(path: string, body?: unknown, options?: {
         retry?: boolean;
+        idempotencyKey?: string;
     }): Promise<T>;
     put<T>(path: string, body?: unknown, options?: {
         retry?: boolean;

package/dist/client.js

@@ -182,6 +182,7 @@ export class HttpClient {
             headers: {
                 ...this.getAuthHeaders(),
                 'Content-Type': 'application/json',
+                ...(options?.idempotencyKey ? { 'Idempotency-Key': options.idempotencyKey } : {}),
             },
             body: body ? JSON.stringify(body) : undefined,
         };

package/dist/errors.d.ts

@@ -24,6 +24,19 @@ export declare class RecursivError extends Error {
 export declare class AuthenticationError extends RecursivError {
     constructor(body: ApiErrorBody['error']);
 }
+/**
+ * A failed legacy session handoff (`auth.legacyHandoff`). It keeps what a
+ * caller needs to tell a refusal from an outage: the HTTP status (0 when no
+ * response arrived), the server's code (`timeout` or `network_error` when no
+ * response arrived), and the seconds the server's Retry-After asked for.
+ * Only `legacy_token_used` and `legacy_token_invalid` are final; every other
+ * failure leaves the legacy session worth trying again.
+ */
+export declare class LegacyHandoffError extends RecursivError {
+    /** Seconds from the server's Retry-After header, when it sent one. */
+    readonly retryAfterSeconds: number | null;
+    constructor(status: number, body: ApiErrorBody['error']);
+}
 export declare class AuthorizationError extends RecursivError {
     constructor(body: ApiErrorBody['error']);
 }

package/dist/errors.js

@@ -66,6 +66,23 @@ export class AuthenticationError extends RecursivError {
         this.name = 'AuthenticationError';
     }
 }
+/**
+ * A failed legacy session handoff (`auth.legacyHandoff`). It keeps what a
+ * caller needs to tell a refusal from an outage: the HTTP status (0 when no
+ * response arrived), the server's code (`timeout` or `network_error` when no
+ * response arrived), and the seconds the server's Retry-After asked for.
+ * Only `legacy_token_used` and `legacy_token_invalid` are final; every other
+ * failure leaves the legacy session worth trying again.
+ */
+export class LegacyHandoffError extends RecursivError {
+    /** Seconds from the server's Retry-After header, when it sent one. */
+    retryAfterSeconds;
+    constructor(status, body) {
+        super(status, body);
+        this.name = 'LegacyHandoffError';
+        this.retryAfterSeconds = typeof body.retry_after === 'number' ? body.retry_after : null;
+    }
+}
 export class AuthorizationError extends RecursivError {
     constructor(body) {
         super(403, body);

package/dist/index.d.ts

@@ -147,14 +147,14 @@ export { HttpClient } from './client.js';
 export { RealtimeClient } from './realtime.js';
 export type { RealtimeConnectOptions } from './realtime.js';
 export { AuthResource } from './resources/auth.js';
-export type { AuthSession, CurrentSession, SignUpInput, SignInInput, UsernameSignInInput, AppContext, ResetPasswordInput, TwoFactorConfirmation, TwoFactorEnrollment, TwoFactorChallenge, CompleteTwoFactorSignInInput, OAuthClientInfo, SendOtpInput, VerifyOtpInput, CreateApiKeyInput, ApiKeyResult, } from './resources/auth.js';
+export type { AuthSession, CurrentSession, SignUpInput, SignInInput, UsernameSignInInput, AppContext, ResetPasswordInput, TwoFactorConfirmation, TwoFactorEnrollment, TwoFactorChallenge, CompleteTwoFactorSignInInput, OAuthClientInfo, SendOtpInput, VerifyOtpInput, CreateApiKeyInput, ApiKeyResult, LegacyHandoffOptions, LegacyHandoffSession, } from './resources/auth.js';
 export { PostsResource } from './resources/posts.js';
 export type { CategoryOrder, CategoryOrderMeta, CategoryOrderReason } from './resources/posts.js';
 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 } from './resources/e2ee.js';
+export type { E2eeDevice, E2eeEnvelope, E2eeEvent, E2eeKeyPackageStatus, E2eeObjectDownload, E2eeObjectUpload, 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';
@@ -165,7 +165,7 @@ export { SandboxResource } from './resources/sandbox.js';
 export { ProfilesResource } from './resources/profiles.js';
 export { OrganizationsResource } from './resources/organizations.js';
 export { NotificationsResource } from './resources/notifications.js';
-export type { Notification, NotificationActor, NotificationCategory, NotificationPostPreview, NotificationScopeParams, NotificationUnreadCount, ListNotificationsParams, NotificationListResponse, } from './resources/notifications.js';
+export type { Notification, NotificationActor, NotificationCategory, NotificationPostPreview, NotificationPostTag, NotificationScopeParams, NotificationUnreadCount, ListNotificationsParams, NotificationListResponse, } from './resources/notifications.js';
 export { SettingsResource } from './resources/settings.js';
 export { BillingResource } from './resources/billing.js';
 export { FreeTierResource } from './resources/free-tier.js';
@@ -240,7 +240,7 @@ 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, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, } from './errors.js';
+export { RecursivError, AuthenticationError, AuthorizationError, LegacyHandoffError, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, } 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, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, } from './errors.js';
+export { RecursivError, AuthenticationError, AuthorizationError, LegacyHandoffError, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, } from './errors.js';
 export { parseSSE } from './lib/sse.js';
 export * from './lib/webhooks.js';

package/dist/resources/auth.d.ts

@@ -1,4 +1,26 @@
 import type { HttpClient } from '../client.js';
+/** Options for `auth.legacyHandoff`. */
+export interface LegacyHandoffOptions {
+    projectId?: string;
+    organizationId?: string;
+    /** Random, 22 to 128 URL-safe characters, kept with the legacy session and sent with every exchange of it. */
+    attemptId?: string;
+    /** The legacy OAuth refresh token, when the legacy session has one. */
+    refreshToken?: string | null;
+    /** Bound for this call, body included. Defaults to the client's timeout. */
+    timeoutMs?: number;
+}
+/** What `auth.legacyHandoff` answers. */
+export interface LegacyHandoffSession extends AuthSession {
+    /**
+     * Present when an `attemptId` was sent. Give the API key made with this
+     * session this description (`createApiKey({ ..., description })`): the
+     * server counts only keys that carry it when it decides whether a replay of
+     * the attempt is still allowed, so the member signing in elsewhere never
+     * refuses this device, and the key revoking itself is never counted as use.
+     */
+    apiKeyDescription?: string;
+}
 export interface AuthSession {
     token: string;
     user: {
@@ -356,18 +378,32 @@ export declare 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.
      */
-    legacyHandoff(legacyToken: string, appContext?: {
-        projectId?: string;
-        organizationId?: string;
-    }): Promise<AuthSession>;
-    /** legacyHandoff, then the app API key, exactly like verifyOtpAndCreateKey. */
-    legacyHandoffAndCreateKey(legacyToken: string, keyInput: CreateApiKeyInput): Promise<{
+    legacyHandoff(legacyToken: string, options?: LegacyHandoffOptions): Promise<LegacyHandoffSession>;
+    /**
+     * 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.
+     */
+    legacyHandoffAndCreateKey(legacyToken: string, keyInput: CreateApiKeyInput, options?: Pick<LegacyHandoffOptions, 'attemptId' | 'refreshToken' | 'timeoutMs'>): Promise<{
         apiKey: string;
         apiKeyId: string;
         user: AuthSession['user'];

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

@@ -37,12 +37,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 +50,45 @@ 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;
+}
+/**
+ * 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 +126,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;

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 });

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) {

package/dist/resources/moderation.d.ts

@@ -81,7 +81,11 @@ export declare class ModerationResource {
      * reachable through a valid key while the account is suspended or banned.
      */
     mine(): Promise<SingleResponse<OwnModerationLog>>;
-    /** Appeal a decision affecting the caller or content they own. */
+    /**
+     * Appeal a decision affecting the caller or content they own. Sent once,
+     * never retried automatically: a 429 past the member's appeal budget
+     * (`RateLimitError`, `retryAfter`) is for the member to see.
+     */
     appeal(actionId: string, statement: string): Promise<SingleResponse<{
         success: true;
         id: string;

package/dist/resources/moderation.js

@@ -22,9 +22,13 @@ export class ModerationResource {
     mine() {
         return this.client.get('/appeals/moderation-actions');
     }
-    /** Appeal a decision affecting the caller or content they own. */
+    /**
+     * Appeal a decision affecting the caller or content they own. Sent once,
+     * never retried automatically: a 429 past the member's appeal budget
+     * (`RateLimitError`, `retryAfter`) is for the member to see.
+     */
     appeal(actionId, statement) {
-        return this.client.post(`/appeals/${encodeURIComponent(actionId)}`, { statement });
+        return this.client.post(`/appeals/${encodeURIComponent(actionId)}`, { statement }, { retry: false });
     }
     /** Admin review: uphold or overturn an appeal. */
     resolveAppeal(appealId, input) {

package/dist/resources/notifications.d.ts

@@ -19,6 +19,11 @@ export interface NotificationActor {
  * state so inline Upvote and Repost can start in the right position. `null`
  * when the post is gone or no longer visible to the viewer.
  */
+/** A post's tag as a notification's post preview carries it. */
+export interface NotificationPostTag {
+    name: string;
+    slug: string;
+}
 export interface NotificationPostPreview {
     id: string;
     /**
@@ -35,6 +40,20 @@ export interface NotificationPostPreview {
     excerpt_truncated?: boolean;
     media_url: string | null;
     media_type: string | null;
+    /**
+     * The post's own NSFW flag. With `tags`, it says whether the post is
+     * sensitive: a client that masks a sensitive post's card masks its excerpt
+     * and picture here too, and holds the picture back while this is absent
+     * (servers older than this field).
+     */
+    is_nsfw?: boolean;
+    /**
+     * The post's tags, each with its name as written and the slug the tag API
+     * derived from it ("nsfw", "nude", "porn" and the like mark it sensitive).
+     * Match both: a tag created as "NSFW!" is slugged "nsfw". Absent from
+     * servers older than this field.
+     */
+    tags?: NotificationPostTag[];
     reactions_count?: number;
     score?: number;
     upvote_count?: number;

package/dist/resources/protocols.d.ts

@@ -1119,6 +1119,15 @@ export interface SocialRadarMember {
         height?: number;
     };
     providerRank?: number;
+    /**
+     * Present on a post member whose image or video a signed-out visitor may see (an open-network post with a cached
+     * safe verdict, or a Minds post that passes the visitor's floor); absent on every other post member, and on members
+     * of a radar built before the server recorded it. An outlet's media needs no mark. The keyless routes
+     * (`getSharedRadar`, `getSharedRadarPosts`, `getSharedRadarStory`) serve media only from marked members and outlets.
+     * A signed-in read (`getPublicRadar` and friends) keeps every member's media, so use only an outlet's or a marked
+     * member's media on a signed-out page or a share card.
+     */
+    visitorMedia?: true;
 }
 /** One story on the radar. `breaking` is outlet corroboration inside a short window; `viral` is social velocity above its network's norm. */
 export interface SocialRadarCluster {
@@ -1143,6 +1152,7 @@ export interface SocialRadarCluster {
         normalized: number;
         samples: number;
     };
+    /** On a signed-in read the lead may belong to a member without `visitorMedia`; find it by `memberKey` before a share card uses it. */
     media: {
         images: number;
         videos: number;
@@ -1333,7 +1343,10 @@ export declare class ProtocolsResource {
         category?: string;
         discovery?: boolean;
     }): Promise<SingleResponse<SocialTrendFeed>>;
-    /** Breaking and viral stories clustered across outlets, open networks and Minds, through the same public-only app boundary. */
+    /**
+     * Breaking and viral stories clustered across outlets, open networks and Minds, through the same public-only app boundary.
+     * Images and videos come only from outlets and from members marked `visitorMedia`; every other member is text.
+     */
     getSharedRadar(projectId: string, params?: SocialRadarParams): Promise<SingleResponse<SocialRadar>>;
     /** One radar story's social member posts without a key, so a signed-out story card can show the posts it counts. */
     getSharedRadarPosts(projectId: string, params: {
@@ -1395,7 +1408,10 @@ export declare class ProtocolsResource {
         category?: string;
         discovery?: boolean;
     }, options?: SocialReadOptions): Promise<SingleResponse<SocialTrendFeed>>;
-    /** The app's topic radar under its own key: the same snapshot the keyless route serves. Never triggers a build. */
+    /**
+     * The app's topic radar under its own key: the same snapshot the keyless route serves, for a signed-in reader, so
+     * every member keeps its media (the keyless route serves only outlets' and `visitorMedia` members'). Never triggers a build.
+     */
     getPublicRadar(params?: SocialRadarParams, options?: SocialReadOptions): Promise<SingleResponse<SocialRadar>>;
     /** One radar story's social member posts, so its card can show the posts it counts. Minds members are read with `posts.get`. */
     getPublicRadarPosts(params: {

package/dist/resources/protocols.js

@@ -102,7 +102,10 @@ export class ProtocolsResource {
         return this.client.get(`/protocols/public/${encodeURIComponent(projectId)}/trend-feed`, { protocol: params.protocol, topic: params.topic,
             limit: params.limit, cursor: params.cursor, category: params.category, discovery: params.discovery });
     }
-    /** Breaking and viral stories clustered across outlets, open networks and Minds, through the same public-only app boundary. */
+    /**
+     * Breaking and viral stories clustered across outlets, open networks and Minds, through the same public-only app boundary.
+     * Images and videos come only from outlets and from members marked `visitorMedia`; every other member is text.
+     */
     getSharedRadar(projectId, params = {}) {
         return this.client.get(`/protocols/public/${encodeURIComponent(projectId)}/radar`, radarQuery(params));
     }
@@ -167,7 +170,10 @@ export class ProtocolsResource {
             ...(params.category !== undefined ? { category: params.category } : {}),
             ...(params.discovery !== undefined ? { discovery: params.discovery } : {}) }, ...readOptions(options));
     }
-    /** The app's topic radar under its own key: the same snapshot the keyless route serves. Never triggers a build. */
+    /**
+     * The app's topic radar under its own key: the same snapshot the keyless route serves, for a signed-in reader, so
+     * every member keeps its media (the keyless route serves only outlets' and `visitorMedia` members'). Never triggers a build.
+     */
     getPublicRadar(params = {}, options) {
         return this.client.get('/protocols/social/radar', radarQuery(params), ...readOptions(options));
     }

package/dist/resources/reports.d.ts

@@ -35,6 +35,10 @@ export declare class ReportsResource {
      * Submit a content report. Targets a post, user, community, or message
      * by ID, with a short reason and optional free-text details. Reporter
      * is the authenticated user.
+     *
+     * Sent once, never retried automatically: past the member's report budget
+     * the server answers 429 (`RateLimitError`, `retryAfter` = seconds until
+     * the window opens), and that refusal is for the member to see.
      */
     create(input: CreateReportInput): Promise<SingleResponse<{
         success: true;

package/dist/resources/reports.js

@@ -7,9 +7,13 @@ export class ReportsResource {
      * Submit a content report. Targets a post, user, community, or message
      * by ID, with a short reason and optional free-text details. Reporter
      * is the authenticated user.
+     *
+     * Sent once, never retried automatically: past the member's report budget
+     * the server answers 429 (`RateLimitError`, `retryAfter` = seconds until
+     * the window opens), and that refusal is for the member to see.
      */
     create(input) {
-        return this.client.post('/reports', input);
+        return this.client.post('/reports', input, { retry: false });
     }
     /** List recent reports in the caller's project/network (admin only). */
     list() {

package/dist/types.d.ts

@@ -229,6 +229,12 @@ export interface RepostedPost {
     /** The group the original is in (null when it is in none): it decides what the repost card offers. */
     community?: PostCommunity | null;
     organization_id: string | null;
+    /**
+     * The original's own NSFW flag. A repost or quote card shows the original's
+     * words and media: mask them when this is set or `tags` marks it sensitive.
+     * Absent from servers older than this field.
+     */
+    is_nsfw?: boolean;
     tags: Tag[];
     reactions_count: number;
     score: number;

package/llm.md

@@ -190,7 +190,7 @@ const { data } = await r.commands.execute({
 // data: { text, actions }
 ```
 
-Methods: `gatePrompt({ messages, model? })`, `execute({ prompt, current_screen?, org_slug?, model?, locale?, attachments? })`
+Methods: `execute({ prompt, current_screen?, org_slug?, model?, locale?, attachments? })`, `gatePrompt({ messages })`. `gatePrompt` is Recursiv's own signup gate, not a moderation API: it answers only for keys on the platform's networks (404 anywhere else, including an app's own network), ignores `model`, and shares one daily LLM budget with Recursiv's signup page.
 
 ### r.projectBrain — Per-project knowledge base & task management
 
@@ -389,7 +389,7 @@ await r.auth.requestTwoFactorEmailCode(live, { projectId }) // app context brand
 await r.auth.disableTwoFactor({ emailCode: '482913' }, live)
 ```
 
-Two-factor methods: `enableTwoFactor`, `verifyTwoFactor`, `disableTwoFactor`, `regenerateTwoFactorBackupCodes`, `requestTwoFactorEmailCode`, `completeTwoFactorSignIn`, `completeTwoFactorSignInAndCreateKey`. OAuth consent screens: `exchangeSessionForCookie(token)` (browser, sets the API-origin cookie so `/api/auth/mcp/authorize` continues without a second sign-in), `getOAuthClientInfo({ clientId, redirectUri?, scope? })` (public client name, redirect hosts, `redirect_uri_registered`, granted scopes).
+Two-factor methods: `enableTwoFactor`, `verifyTwoFactor`, `disableTwoFactor`, `regenerateTwoFactorBackupCodes`, `requestTwoFactorEmailCode`, `completeTwoFactorSignIn`, `completeTwoFactorSignInAndCreateKey`. Minds cutover: `legacyHandoff(legacyToken, { attemptId, refreshToken, projectId, timeoutMs })` exchanges the legacy app's session once; it throws `LegacyHandoffError` (`status` 0 when no response came, `code`, `retryAfterSeconds`), and only `legacy_token_used` / `legacy_token_invalid` mean forget the legacy session. With an `attemptId` a success carries `apiKeyDescription`; give the API key made with that session that `description`, so replays of the attempt count only that key. `legacyHandoffAndCreateKey(token, keyInput, { attemptId, refreshToken })` does both; pass the same `attemptId` on every retry. OAuth consent screens: `exchangeSessionForCookie(token)` (browser, sets the API-origin cookie so `/api/auth/mcp/authorize` continues without a second sign-in), `getOAuthClientInfo({ clientId, redirectUri?, scope? })` (public client name, redirect hosts, `redirect_uri_registered`, granted scopes).
 
 **Mobile/React Native auth** (recommended — one call instead of three):
 ```typescript
@@ -502,14 +502,18 @@ Scroll back with `messages(id, { cursor: page.meta.next_cursor })`, not a growin
 
 ### r.e2ee — End-to-end encryption transport (flag-gated)
 
-Relays opaque MLS envelopes, public device credentials and one-time key packages for the shared E2EE core; the server never sees keys or plaintext. Requires the `e2eeV2` network feature flag (otherwise `feature_disabled`) and a key acting as the account owner (agent-scoped keys get `agent_key_not_allowed`). The realm is the network id. Only a direct conversation between two people with an accepted request can start encryption (`conversation_not_eligible` otherwise); blocks apply (`blocked`); commits must send `expected_commit_seq`.
+Relays opaque MLS envelopes, public device credentials and one-time key packages for the shared E2EE core; the server never sees keys or plaintext. Requires the `e2eeV2` network feature flag (otherwise `feature_disabled`) and a key acting as the account owner (agent-scoped keys get `agent_key_not_allowed`). The realm is the network id. Only a direct conversation between two people with an accepted request can start encryption (`conversation_not_eligible` otherwise), and every later append to it is checked the same way again (both people still accepted, still in the pilot, still only the two of them), so a client need not read the policy before each send; a resend of an event already stored still returns `duplicate: true`, even once a Welcome's target device is gone; blocks apply (`blocked`), to resends too; commits must send `expected_commit_seq`.
+
+Ask first instead of trying a call: `r.e2ee.status()` returns `{ enabled: true }` or `{ enabled: false, reason: 'network_off' | 'not_allowlisted' }` for the calling account only. `enabled: false` means frozen: already-encrypted conversations stay readable, nothing new can be sent or enrolled.
 
 ```ts
+const { data: access } = await r.e2ee.status(); // offer encryption only when access.enabled
 const { data: device } = await r.e2ee.registerDevice({ device_name: 'phone-1', realm: networkId, signing_key, credential });
 await r.e2ee.publishKeyPackages({ device_id: device.id, packages: [keyPackageBase64] }); // → { published, available }
 const { data: stock } = await r.e2ee.keyPackageStatus({ device_id: device.id }); // { available, expiringSoon }; refill when low
 const { data: claimed } = await r.e2ee.claimKeyPackage({ device_id: device.id, target_device_id: peerDeviceId });
 await r.e2ee.appendEvent(conversationId, { device_id: device.id, envelope }); // idempotent per event_id
+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 });
 ```
@@ -808,7 +812,7 @@ Pagination: pass `limit` and `offset`. Check `meta.has_more`.
 | `RateLimitError` | 429 | Rate limit hit (`error.retryAfter` seconds) |
 | `ConflictError` | 409 | Resource already exists |
 
-Auto-retry on 429/5xx built in (exponential backoff, default `maxRetries: 2`).
+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).
 
 ### Idempotency
 

package/package.json

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