@recursiv/sdk 0.7.54 → 0.7.57

package/README.md

@@ -75,7 +75,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | Resource | Key methods |
 |----------|------------|
 | `r.agents` | `create`, `update`, `chat`, `chatStream`, `retryChatStream`, `grantProjectAccess`, `conversations` |
-| `r.e2ee` | `registerDevice`, `devices`, `revokeDevice`, `publishKeyPackages`, `keyPackageStatus`, `claimKeyPackage`, `appendEvent`, `events`, `acknowledge` (flag-gated E2EE v2 transport) |
+| `r.e2ee` | `status`, `registerDevice`, `devices`, `revokeDevice`, `publishKeyPackages`, `keyPackageStatus`, `claimKeyPackage`, `appendEvent`, `events`, `acknowledge`, `conversations`; device linking by scan: `createLink`, `link`, `scannedLink`, `approveLink`, `completeLink`, `linkProgress`, `cancelLink` (flag-gated E2EE v2 transport; its doorbell is `r.realtime.onE2eeEvent`, which carries a small message's stored ciphertext to the owner's own sockets; link and device changes arrive on `r.realtime.onE2eeLink` and `onE2eeDevices`) |
 | `r.brain` | `sendMessage` |
 | `r.commands` | `execute`, `gatePrompt` |
 | `r.projectBrain` | `tasks`, `decisions`, `milestones`, `completeTask`, `usage` |
@@ -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; the id may be a World Today edition story's, and the answer then names it in `editionStory` under the story's radar id), keyless `getSharedRadarStory(projectId, { cluster })` and `getSharedRadarPosts(projectId, { cluster })` (keyless reads carry images and videos only from outlets and members marked `visitorMedia`; signed-in reads keep all media, so a share card uses only those); private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. `list` returns bounded adapter `maturity`, `limitations`, and exhaustive `supported`/`planned`/`unsupported` implementation capabilities (not provider health or enablement); settings, candidate refresh/status, search, and read-only quarantined candidate review via `listCandidates` / `getCandidate` |
 
 Full reference: see [llm.md](./llm.md) (ships with this package) or the type definitions in `dist/`.
 
@@ -351,7 +351,7 @@ import {
   AuthorizationError,   // 403 — API key lacks required scope
   NotFoundError,        // 404
   ValidationError,      // 400 — check error.details
-  RateLimitError,       // 429 — includes retryAfter, upgradeUrl
+  RateLimitError,       // 429 — includes retryAfter, resetAt, scope, upgradeUrl
   ConflictError,        // 409
 } from '@recursiv/sdk'
 
@@ -364,7 +364,7 @@ try {
 }
 ```
 
-Auto-retry is built in. 429 and 5xx responses retry with exponential backoff (configurable via `maxRetries`, default 2).
+Auto-retry is built in. 429 and 5xx responses retry with exponential backoff (configurable via `maxRetries`, default 2). A 429 with `X-RateLimit-Scope: action` refuses one member action past its budget and is never retried: its `RateLimitError` has `scope: 'action'` and `resetAt` (a `Date`, when that action's budget reopens).
 
 ## Pagination
 
@@ -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

@@ -1,4 +1,4 @@
-import { RecursivError, AuthenticationError, AuthorizationError, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, errorBodyFromResponse, httpStatusMessage, } from './errors.js';
+import { RecursivError, AuthenticationError, AuthorizationError, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, errorBodyFromResponse, httpStatusMessage, isActionRateLimitScope, rateLimitDetailsFromResponse, } from './errors.js';
 const DEFAULT_BASE_URL = 'https://api.recursiv.io/api/v1';
 export class HttpClient {
     #apiKey;
@@ -59,6 +59,13 @@ export class HttpClient {
             if (response.status === 429 || response.status >= 500) {
                 if (attempt === this.maxRetries)
                     return response;
+                // X-RateLimit-Scope: action refuses this one action (a post, a follow,
+                // a report) past the member's budget. The API is not busy: the same
+                // request is refused again until the budget reopens, or, sent late,
+                // becomes a write the member saw refused. The caller gets the 429 now,
+                // with RateLimitError.scope and resetAt.
+                if (response.status === 429 && isActionRateLimitScope(response.headers))
+                    return response;
                 const retryAfter = response.headers.get('retry-after');
                 const delay = retryAfter
                     ? parseInt(retryAfter, 10) * 1000
@@ -163,7 +170,7 @@ export class HttpClient {
             case 409:
                 throw new ConflictError(err);
             case 429:
-                throw new RateLimitError(err);
+                throw new RateLimitError(err, rateLimitDetailsFromResponse(response.headers, err));
             default:
                 throw new RecursivError(response.status, err);
         }
@@ -182,6 +189,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']);
 }
@@ -37,9 +50,36 @@ export declare class InsufficientCreditsError extends RecursivError {
     readonly upgradeUrl: string;
     constructor(body: ApiErrorBody['error']);
 }
+/** What a 429 says beyond its body: which budget refused it, and when that budget reopens. */
+export interface RateLimitDetails {
+    /**
+     * `'action'` when the server refused one member action past its budget
+     * (a post, a follow, a report: `X-RateLimit-Scope: action`). Only that
+     * action is refused, the rest of the API is not busy, and sending it again
+     * before `resetAt` is refused again. `undefined` for any other 429.
+     */
+    scope?: 'action';
+    /**
+     * When the refused budget reopens, for showing in the member's local time.
+     * From `X-RateLimit-Reset`, else `Retry-After`, else the body's
+     * `retry_after`; `undefined` when none of them says.
+     */
+    resetAt?: Date;
+}
+/** Whether a response's headers mark its 429 as refusing one action (`X-RateLimit-Scope: action`). */
+export declare function isActionRateLimitScope(headers: Pick<Headers, 'get'> | null | undefined): boolean;
+/**
+ * The scope and reset of a 429, read from its headers, and from the body's
+ * `retry_after` (seconds) when neither reset header was sent.
+ */
+export declare function rateLimitDetailsFromResponse(headers: Pick<Headers, 'get'> | null | undefined, body?: Pick<ApiErrorBody['error'], 'retry_after'>, now?: number): RateLimitDetails;
 export declare class RateLimitError extends RecursivError {
     readonly upgradeUrl: string;
-    constructor(body: ApiErrorBody['error']);
+    /** `'action'` when only this one action was refused (see RateLimitDetails.scope); otherwise undefined. */
+    readonly scope?: 'action';
+    /** When the refused budget reopens (see RateLimitDetails.resetAt); undefined when the server did not say. */
+    readonly resetAt?: Date;
+    constructor(body: ApiErrorBody['error'], details?: RateLimitDetails);
 }
 export declare class ConflictError extends RecursivError {
     constructor(body: ApiErrorBody['error']);

package/dist/errors.js

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/realtime.d.ts

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

package/dist/realtime.js

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

package/dist/resources/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'];