@recursiv/sdk 0.7.53 → 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/`.
 
@@ -675,6 +675,44 @@ what the viewer follows, joined, blocked or muted, and says why a list is empty
 showings without a tap rest a suggestion for fourteen days, and engaging clears it.
 Keep one `session` token per app session so a rail does not reshuffle on every render.
 
+A category feed never ends at an empty page. `sdk.posts.list({ category, sort: 'hot' })`
+(or `score`, or the default chronological order) pages the window of the category's
+newest judged posts, then continues by keyset through the whole indexed
+history: every page's `meta.next` is `{ offset }`, `{ cursor }` or `null`, and when a
+stage ends `meta.fallover` lists where to go, in order: `category_older` (the keyset
+cursor `next` also carries), `category_network` (the same category on the open
+networks), the member's next categories (`via` names the order they came from), `for_you`
+and `all`. A `DiscoveryFeedSession` follows the cursor itself and reports the Minds
+feed's `fallover` on its pages. `sdk.discovery.category({ category, session? })` answers a
+category's surface in one call: `stories`, `network` and `clips` (each shared per app and
+category, refreshed after 30 s, kept up to 300 s and warmed as the warmer reaches the category, then filtered for the viewer on every call: the cached safety verdicts of story members, network posts and clips again, the term list, the viewer's blocks and mutes over clips, and the member's own hidden sources over network posts and story members) and the
+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`). 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`
 says why an answer is not personal (`low_signal`, `deadline`, `requested`,

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, 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: {
@@ -8,6 +30,20 @@ export interface AuthSession {
         image: string | null;
     };
 }
+/**
+ * What `getSession` answers: the account, and which of its sessions the token
+ * is. `session.id` is the id `settings.listSessions()` lists that session
+ * under. A client that authenticates with an API key gets `is_current: false`
+ * on every listed row (a key belongs to no session), so it matches this id to
+ * mark its own device.
+ */
+export interface CurrentSession extends AuthSession {
+    /** Null only when the server's answer names no session row. */
+    session: {
+        id: string;
+        expiresAt: string | null;
+    } | null;
+}
 export interface SignUpInput {
     email: string;
     password: string;
@@ -275,10 +311,10 @@ export declare class AuthResource {
         success: true;
     }>;
     /**
-     * Get current session info using a session token.
-     * Returns null if the session is invalid or expired.
+     * Get current session info using a session token: the account, and the
+     * session's id and expiry. Returns null if the session is invalid or expired.
      */
-    getSession(sessionToken: string): Promise<AuthSession | null>;
+    getSession(sessionToken: string): Promise<CurrentSession | null>;
     /**
      * Sign out (invalidate session).
      */
@@ -342,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 ?? {});
@@ -596,8 +604,8 @@ export class AuthResource {
         return { success: true };
     }
     /**
-     * Get current session info using a session token.
-     * Returns null if the session is invalid or expired.
+     * Get current session info using a session token: the account, and the
+     * session's id and expiry. Returns null if the session is invalid or expired.
      */
     async getSession(sessionToken) {
         const res = await this.fetchWithTimeout(`${this.baseOrigin}/api/auth/get-session`, {
@@ -612,6 +620,8 @@ export class AuthResource {
         const data = await res.json();
         if (!data?.user)
             return null;
+        const sessionId = data.session?.id;
+        const expiresAt = data.session?.expiresAt;
         return {
             token: sessionToken,
             user: {
@@ -620,6 +630,9 @@ export class AuthResource {
                 email: data.user.email,
                 image: data.user.image ?? null,
             },
+            session: typeof sessionId === 'string' && sessionId
+                ? { id: sessionId, expiresAt: typeof expiresAt === 'string' ? expiresAt : null }
+                : null,
         };
     }
     /**
@@ -629,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 = {};
@@ -757,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 };
     }
     /**
@@ -839,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/curator.d.ts

@@ -7,7 +7,7 @@ export type ForYouParams = {
     offset?: number;
     /** The previous page's `meta.next_cursor`: pages a stored ranking, so posts read meanwhile never shift the next page. */
     cursor?: string;
-    /** Adds `meta.discovery` (layouts) and the public safety floor; limit <= 25. */
+    /** Adds `meta.discovery` (layouts); limit <= 25. Every page carries the promotion safety floor, with or without it. */
     discovery?: boolean;
     /** `discover` ranks for Discover: fresher, beyond the member's follows, with their category order. */
     surface?: ForYouSurface;