@recursiv/sdk 0.7.54 → 0.7.57

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

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

package/dist/resources/protocols.js

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

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

package/package.json

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