@recursiv/sdk 0.7.53 → 0.7.55

package/dist/resources/discovery.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../client.js';
-import type { DiscoveryLayout, Post } from '../types.js';
+import type { DiscoveryLayout, FalloverStep, Post } from '../types.js';
 import type { CuratorResource } from './curator.js';
 import type { DiscoveryLearning } from './discovery-learning.js';
 import type { PostsResource } from './posts.js';
@@ -66,6 +66,61 @@ export interface EntityImpressionsInput {
     /** 'shown' when a suggestion was on screen; 'engaged' on a tap, follow or join. Three showings without a tap rest a suggestion for fourteen days; engaging clears it. */
     event: 'shown' | 'engaged';
 }
+/** One section of a category surface: bounded, read under its own deadline; empty with a `reason` when it timed out, failed, is off, or the recommender said why. */
+export interface CategorySurfaceSection<T> {
+    items: T[];
+    ms: number;
+    reason?: string;
+}
+/** A radar cluster themed into the category, with up to six members (headline or excerpt and link only). */
+export type CategoryStory = Pick<SocialRadar['clusters'][number], 'id' | 'label' | 'kind' | 'theme' | 'sources' | 'corroboration' | 'laneMix' | 'velocity' | 'media' | 'freshness' | 'score' | 'members'>;
+export interface CategoryClip {
+    id: string;
+    title: string | null;
+    excerpt: string;
+    created_at: string;
+    author: {
+        id: string;
+        username: string | null;
+        name: string;
+        image: string | null;
+    };
+    media: Array<{
+        id: string;
+        url: string;
+        type: string;
+        thumbnail_url: string | null;
+        unplayable?: boolean;
+    }>;
+    engagement: {
+        score: number;
+        like_count: number;
+        reply_count: number;
+        repost_count: number;
+    };
+}
+export interface CategorySurface {
+    category: string;
+    /** When the oldest cached section served (stories, network, clips) was built. */
+    as_of: string;
+    stories: CategorySurfaceSection<CategoryStory>;
+    network: CategorySurfaceSection<SocialPost> & {
+        by_protocol: Record<string, number>;
+    };
+    clips: CategorySurfaceSection<CategoryClip>;
+    people: CategorySurfaceSection<EntityRecommendation>;
+    groups: CategorySurfaceSection<EntityRecommendation>;
+}
+export interface CategorySurfaceResponse {
+    /** Null when the key has no app (meta.reason `no_app`). */
+    data: CategorySurface | null;
+    meta: {
+        category: string;
+        as_of?: string;
+        reason?: 'no_app';
+        personalized: boolean;
+    };
+}
 export interface DiscoveryGroupCandidate {
     id: string;
     name: string;
@@ -219,6 +274,12 @@ export interface DiscoveryFeedPage {
     hasMore: boolean;
     failedSources: string[];
     partialCategories: boolean;
+    /**
+     * The Minds feed's fall-through, once its category feed has ended a stage (the server's
+     * `meta.fallover`): where to read next when this session has no more. Absent until then, and
+     * on servers that predate it.
+     */
+    fallover?: FalloverStep[];
 }
 /** A gallery strip holds up to twelve image posts gathered from the whole page. */
 export declare const GALLERY_MAX_ITEMS = 12;
@@ -292,6 +353,22 @@ export declare class DiscoveryResource {
             reason?: 'disabled' | 'other_app' | 'unavailable' | 'no_app';
         };
     }>;
+    /**
+     * A category's surface in one call: the modules All has, scoped to the category. `stories` (radar
+     * clusters themed into it), `network` (open-network posts judged into it, newest first) and `clips`
+     * (public video posts among its hot window) are shared per app and category (refreshed after 30 s, kept up to 300 s, so a copy
+     * may be that old) and filtered for the viewer on every call: the cached safety verdicts and the promotion term list again, the
+     * viewer's blocks and mutes, and for stories and network the member's own hidden sources. `people` and `groups` are the
+     * viewer's suggestions in it. A section that timed out, failed or is off is empty
+     * with a `reason` and never delays the others. The posts feed itself is `posts.list({ category })`,
+     * whose pages carry `meta.next` and `meta.fallover`.
+     */
+    category(params: {
+        category: string;
+        session?: string;
+    }, options?: {
+        retry?: boolean;
+    }): Promise<CategorySurfaceResponse>;
     /**
      * A For you Discover feed: the member's For You ranking (asked for Discover's surface, with layouts and a
      * snapshot cursor) in a session's Minds slot. With a category, the session also reads open-network posts

package/dist/resources/discovery.js

@@ -22,6 +22,16 @@ const isGone = (error) => typeof error === 'object' && error !== null && error.c
 const TOPIC_WALK = 5;
 /** The walk starts no topic read after this long: well inside the page deadline, so it commits its progress rather than timing the network out. */
 const TOPIC_WALK_MS = 8000;
+/**
+ * A topic page the server answered from its open-network source index (`sourceIndex`): in a category, a
+ * topic that is gone or holds nothing in it is served the network's indexed posts in the category, which
+ * are the same for every such topic. While the provider has more of the topic the page carries the
+ * provider's own cursor, which the walk keeps like any other; a topic that is gone or ended carries an
+ * `idx:tf:` cursor, the one index stream of the network. So a walk starts that stream at most once per
+ * session (a second start would re-read what it already showed), and an index page that shows nothing
+ * new counts as an empty topic.
+ */
+const INDEX_CURSOR = 'idx:tf:';
 const RECOMMENDATION_KINDS = ['groups', 'people', 'tags'];
 const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0 && value.length <= 512;
 function recommendationItem(kind, candidate) {
@@ -188,6 +198,9 @@ export class DiscoveryFeedSession {
             if (stream.cursor)
                 stream.used = [...stream.used, stream.cursor].slice(-32);
             stream.cursor = next;
+            // A category feed that ended a stage says where to go next; kept on the stream and reported on every page from here.
+            if (Array.isArray(response.meta.fallover))
+                stream.fallover = response.meta.fallover;
             return { items: response.data.map(post => ({ key: key('minds', post.id), kind: 'minds', post })),
                 layout: response.meta.discovery ?? ordinary, partial: response.meta.category_filter?.status === 'partial' };
         }
@@ -237,9 +250,20 @@ export class DiscoveryFeedSession {
             const topic = topics[0];
             if (!topic)
                 break;
+            // A failed read of the network's index stream (the server's index busy, or its safety cache down) ends that
+            // continuation, not the network: the stream may start again from a later topic's page. A provider topic
+            // read that fails any other way than gone is still the network's failure.
+            const indexContinuation = !!topic.cursor?.startsWith(INDEX_CURSOR);
             const response = await this.protocols.getPublicTrendFeed({ ...params, protocol: stream.protocol, topic: topic.topic, cursor: topic.cursor }, NO_RETRY)
-                .catch((error) => { if (isGone(error))
-                return null; throw error; });
+                .catch((error) => {
+                if (isGone(error))
+                    return null;
+                if (indexContinuation) {
+                    stream.indexStarted = false;
+                    return null;
+                }
+                throw error;
+            });
             topics.shift();
             if (!response)
                 continue;
@@ -248,12 +272,20 @@ export class DiscoveryFeedSession {
             if (data.trend.protocol !== stream.protocol || data.trend.nativeId !== topic.topic)
                 throw new Error('Invalid discovery topic');
             const next = data.cursor;
-            if (next && next !== topic.cursor && !topic.used.includes(next))
+            // A provider cursor is always kept. An index cursor from a provider page starts the network's one index
+            // stream: queued the first time only, since every later start would re-read the same stream from its top.
+            const indexed = !!data.sourceIndex;
+            const startsIndex = !!next?.startsWith(INDEX_CURSOR) && !topic.cursor?.startsWith(INDEX_CURSOR);
+            if (next && next !== topic.cursor && !topic.used.includes(next) && !(startsIndex && stream.indexStarted)) {
                 topics.push({ topic: topic.topic, cursor: next, used: [...topic.used, ...(topic.cursor ? [topic.cursor] : [])].slice(-32) });
+                if (startsIndex)
+                    stream.indexStarted = true;
+            }
             partial ||= data.categoryFilter?.status === 'partial';
-            if (data.items.length) {
+            const items = indexed ? data.items.filter(post => !this.seen.has(key(post.protocol, post.nativeId))) : data.items;
+            if (items.length) {
                 stream.done = !topics.length;
-                return { items: data.items.map(post => ({ key: key(post.protocol, post.nativeId), kind: 'social', post })), layout: data.discovery ?? ordinary, partial };
+                return { items: items.map(post => ({ key: key(post.protocol, post.nativeId), kind: 'social', post })), layout: data.discovery ?? ordinary, partial };
             }
         }
         stream.done = !topics.length;
@@ -369,8 +401,10 @@ export class DiscoveryFeedSession {
             modules.splice(Math.min(2, modules.length), 0, recommendation);
         if (cluster)
             modules.splice(page === 0 ? 0 : Math.min(2, modules.length), 0, this.radarModule(page, cluster, clusterItems));
+        const fallover = this.streams.find(stream => stream.protocol === 'minds')?.fallover;
         return { modules, hasMore: this.streams.some(stream => !stream.done && !stream.failed),
-            failedSources: this.streams.filter(stream => stream.failed).map(stream => stream.protocol), partialCategories: reads.some(read => read.partial) };
+            failedSources: this.streams.filter(stream => stream.failed).map(stream => stream.protocol), partialCategories: reads.some(read => read.partial),
+            ...(fallover ? { fallover } : {}) };
     }
     /** Page 0: the top breaking cluster, else the top cluster. Every second later page: the next unused story or viral cluster. */
     async radarCluster(page) {
@@ -534,6 +568,21 @@ export class DiscoveryResource {
             throw new Error('recordImpressions needs the HTTP client');
         return this.http.post('/discover/impressions', input);
     }
+    /**
+     * A category's surface in one call: the modules All has, scoped to the category. `stories` (radar
+     * clusters themed into it), `network` (open-network posts judged into it, newest first) and `clips`
+     * (public video posts among its hot window) are shared per app and category (refreshed after 30 s, kept up to 300 s, so a copy
+     * may be that old) and filtered for the viewer on every call: the cached safety verdicts and the promotion term list again, the
+     * viewer's blocks and mutes, and for stories and network the member's own hidden sources. `people` and `groups` are the
+     * viewer's suggestions in it. A section that timed out, failed or is off is empty
+     * with a `reason` and never delays the others. The posts feed itself is `posts.list({ category })`,
+     * whose pages carry `meta.next` and `meta.fallover`.
+     */
+    category(params, options) {
+        if (!this.http)
+            throw new Error('category needs the HTTP client');
+        return this.http.get('/discover/category', params, options);
+    }
     /**
      * A For you Discover feed: the member's For You ranking (asked for Discover's surface, with layouts and a
      * snapshot cursor) in a session's Minds slot. With a category, the session also reads open-network posts

package/dist/resources/e2ee.d.ts

@@ -37,12 +37,6 @@ export interface E2eeKeyPackageStatus {
     /** Of `available`, how many expire within 7 days. */
     expiringSoon: number;
 }
-/**
- * E2EE v2 ciphertext transport. The server relays envelopes and public
- * credentials only; encryption happens in the shared core on each device.
- * Requires the `e2eeV2` network feature flag and a key acting as the account
- * owner (agent-scoped keys are refused). The realm is the network id.
- */
 /** A reserved encrypted attachment object: PUT exactly `length` bytes of ciphertext to `uploadUrl`, then complete it. */
 export interface E2eeObjectUpload {
     reference: string;
@@ -56,9 +50,45 @@ export interface E2eeObjectDownload {
     downloadUrl: string;
     length: number;
 }
+/**
+ * Why this account cannot use the E2EE relay on its network:
+ * - `network_off`: the network has not turned E2EE v2 on.
+ * - `not_allowlisted`: it is on, but only for pilot accounts, and this is not one.
+ */
+export type E2eeStatusReason = 'network_off' | 'not_allowlisted';
+/** Whether the calling account is admitted to the E2EE relay on its network. */
+export interface E2eeStatus {
+    /**
+     * True: this account may enroll devices, publish key packages, send, and
+     * start encryption in an eligible direct conversation. False: the relay is
+     * frozen for it. Conversations that already carry encryption stay readable
+     * (fetch, acknowledge, object downloads), its own devices can be listed and
+     * revoked, and nothing new can be sent or enrolled. It never falls back to
+     * plaintext.
+     */
+    enabled: boolean;
+    /** Present only when `enabled` is false. Treat any unrecognised reason as off. */
+    reason?: E2eeStatusReason;
+}
+/**
+ * E2EE v2 ciphertext transport. The server relays envelopes and public
+ * credentials only; encryption happens in the shared core on each device.
+ * Requires the `e2eeV2` network feature flag and a key acting as the account
+ * owner (agent-scoped keys are refused). The realm is the network id.
+ */
 export declare class E2eeResource {
     private client;
     constructor(client: HttpClient);
+    /**
+     * Whether this account is admitted to encrypted chat on its network, without
+     * attempting a relay call. `{ enabled: true }`, or `{ enabled: false, reason }`
+     * with `reason` `'network_off'` or `'not_allowlisted'`. Only the caller's own
+     * account is described; the network comes from the key or session. Enrolling
+     * a device still needs an accepted two-person DM (or an already-encrypted
+     * conversation) in this key's scope. Agent-scoped keys get
+     * `agent_key_not_allowed`.
+     */
+    status(): Promise<SingleResponse<E2eeStatus>>;
     /** Register this device's public identity and its signed approval chain. */
     registerDevice(input: {
         device_name: string;
@@ -96,12 +126,28 @@ export declare class E2eeResource {
         bytes: string;
         device: E2eeDevice;
     }>>;
+    /**
+     * Append one MLS envelope to an encrypted conversation.
+     *
+     * `silent: true` marks a message that changes an earlier one (a reaction,
+     * an edit, a delete for everyone): the relay sends no push (so no unread
+     * badge either) and does not move the conversation up the chat list. The
+     * `e2ee:event` doorbell still rings exactly as for any message: on the
+     * sockets of every member, the sender's own account included, except
+     * across a block. So every listener hears a quiet event, not only an open
+     * thread: a chat list that pulls on the doorbell pulls it too, and should
+     * leave the row where it is once it has decrypted a reaction, an edit or a
+     * delete. A commit ignores the flag. The relay learns only that the event
+     * is quiet; the flag is not stored. A relay that predates it drops the
+     * key, so the event is simply not quiet there.
+     */
     appendEvent(conversationId: string, input: {
         device_id: string;
         envelope: E2eeEnvelope;
         welcome?: string;
         welcome_for_device_id?: string;
         expected_commit_seq?: number;
+        silent?: boolean;
     }): Promise<SingleResponse<{
         seq: number;
         duplicate: boolean;

package/dist/resources/e2ee.js

@@ -1,8 +1,26 @@
+/**
+ * E2EE v2 ciphertext transport. The server relays envelopes and public
+ * credentials only; encryption happens in the shared core on each device.
+ * Requires the `e2eeV2` network feature flag and a key acting as the account
+ * owner (agent-scoped keys are refused). The realm is the network id.
+ */
 export class E2eeResource {
     client;
     constructor(client) {
         this.client = client;
     }
+    /**
+     * Whether this account is admitted to encrypted chat on its network, without
+     * attempting a relay call. `{ enabled: true }`, or `{ enabled: false, reason }`
+     * with `reason` `'network_off'` or `'not_allowlisted'`. Only the caller's own
+     * account is described; the network comes from the key or session. Enrolling
+     * a device still needs an accepted two-person DM (or an already-encrypted
+     * conversation) in this key's scope. Agent-scoped keys get
+     * `agent_key_not_allowed`.
+     */
+    status() {
+        return this.client.get('/e2ee/status');
+    }
     /** Register this device's public identity and its signed approval chain. */
     registerDevice(input) {
         return this.client.post('/e2ee/devices', input);
@@ -28,6 +46,21 @@ export class E2eeResource {
     claimKeyPackage(input) {
         return this.client.post('/e2ee/key-packages/claim', input);
     }
+    /**
+     * Append one MLS envelope to an encrypted conversation.
+     *
+     * `silent: true` marks a message that changes an earlier one (a reaction,
+     * an edit, a delete for everyone): the relay sends no push (so no unread
+     * badge either) and does not move the conversation up the chat list. The
+     * `e2ee:event` doorbell still rings exactly as for any message: on the
+     * sockets of every member, the sender's own account included, except
+     * across a block. So every listener hears a quiet event, not only an open
+     * thread: a chat list that pulls on the doorbell pulls it too, and should
+     * leave the row where it is once it has decrypted a reaction, an edit or a
+     * delete. A commit ignores the flag. The relay learns only that the event
+     * is quiet; the flag is not stored. A relay that predates it drops the
+     * key, so the event is simply not quiet there.
+     */
     appendEvent(conversationId, input) {
         // Retries are safe: the server is idempotent on (conversation, device, event id).
         return this.client.post(`/e2ee/conversations/${encodeURIComponent(conversationId)}/events`, input, { retry: true });

package/dist/resources/human-input.d.ts

@@ -15,6 +15,7 @@ export interface RequestHumanInputInput {
 export interface HumanInputRequest {
     conversation_id: string;
     message_id: string;
+    human_ask_id: string | null;
     /** Where to read the answer. MCP is stateless, so the agent polls. */
     poll: string;
     poll_after_seconds: number;
@@ -45,7 +46,9 @@ export declare class HumanInputResource {
     private client;
     constructor(client: HttpClient);
     /** Raise a blocking question and notify the human wherever they are. */
-    request(input: RequestHumanInputInput): Promise<SingleResponse<HumanInputRequest>>;
+    request(input: RequestHumanInputInput, options?: {
+        requestId?: string;
+    }): Promise<SingleResponse<HumanInputRequest>>;
     /** Has the human answered yet? */
     answers(conversationId: string): Promise<SingleResponse<HumanInputAnswers>>;
 }

package/dist/resources/human-input.js

@@ -17,8 +17,13 @@ export class HumanInputResource {
         this.client = client;
     }
     /** Raise a blocking question and notify the human wherever they are. */
-    request(input) {
-        return this.client.post('/human-input', input);
+    request(input, options) {
+        // Never automatically replay: chat delivery may have committed before a
+        // response was lost, even when a keyed workspace ask was recorded once.
+        // Callers can reuse a requestId with the exact same input after an
+        // uncertain response. The server claims it against the durable
+        // organization-owned ask row; changed fields need a new requestId.
+        return this.client.post('/human-input', input, { retry: false, idempotencyKey: options?.requestId });
     }
     /** Has the human answered yet? */
     answers(conversationId) {

package/dist/resources/moderation.d.ts

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

package/dist/resources/moderation.js

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

package/dist/resources/notifications.d.ts

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

package/dist/resources/profiles.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../client.js';
-import type { PaginatedResponse, SingleResponse, SuccessResponse, Profile, ProfileDetail, ProfileMe, LeaderboardEntry, UpdateProfileInput, SearchProfilesParams, ProfileSearchResult, SearchMentionsParams, MentionCandidate, FollowListParams, FollowListProfile, BlockedProfile, MutedProfile, ModerationListParams, ViewerRelationship } from '../types.js';
+import type { PaginatedResponse, SingleResponse, SuccessResponse, Profile, ProfileDetail, ProfileMe, LeaderboardEntry, UpdateProfileInput, SearchProfilesParams, ProfileSearchResult, SearchMentionsParams, MentionCandidate, FollowListParams, FollowListProfile, BlockedProfile, MutedProfile, ModerationListParams, ProfileRelationship } from '../types.js';
 export declare class ProfilesResource {
     private client;
     constructor(client: HttpClient);
@@ -60,8 +60,12 @@ export declare class ProfilesResource {
         cursor?: string;
         limit?: number;
     }): Promise<PaginatedResponse<string>>;
-    /** The follow relationship with another user in both directions (mutual when both are true). */
-    isFollowing(userId: string): Promise<SingleResponse<ViewerRelationship>>;
+    /**
+     * The caller's relationship with another user: follows in both directions
+     * (mutual when both are true), and whether the caller blocks (`is_blocking`)
+     * or mutes (`is_muting`) them, left out when the server cannot say.
+     */
+    isFollowing(userId: string): Promise<SingleResponse<ProfileRelationship>>;
     /**
      * Block a user. A block is a two-way wall: it severs follows in both
      * directions and hides each side's posts from the other.

package/dist/resources/profiles.js

@@ -76,7 +76,11 @@ export class ProfilesResource {
     followingIds(params) {
         return this.client.get('/profiles/me/following/ids', params);
     }
-    /** The follow relationship with another user in both directions (mutual when both are true). */
+    /**
+     * The caller's relationship with another user: follows in both directions
+     * (mutual when both are true), and whether the caller blocks (`is_blocking`)
+     * or mutes (`is_muting`) them, left out when the server cannot say.
+     */
     isFollowing(userId) {
         return this.client.get(`/profiles/${userId}/is-following`);
     }

package/dist/resources/protocols.d.ts

@@ -928,6 +928,8 @@ export interface SocialProfile {
     followersCount: number | null;
     followingCount: number | null;
     postsCount: number | null;
+    /** Nostr only: the NIP-05 name its domain has confirmed for this key ("lyn@primal.net"); `handle` stays the key. */
+    nip05?: string;
     subscription: SocialSubscription | null;
 }
 export interface SocialSubscription {
@@ -1073,6 +1075,20 @@ export interface SocialTrendFeed extends SocialTrendProvenance {
     trend: SocialTrend;
     items: SocialPost[];
     cursor: string | null;
+    /**
+     * Present when the page came from the app's open-network source index instead of the provider:
+     * with a category, a topic the provider no longer lists (`gone`) or whose feed held nothing in the
+     * category (`empty`) is served the network's indexed posts in the category. While the provider has
+     * more of the topic, `cursor` is the provider's own continuation (the topic's deeper pages may hold
+     * the category); once it has none, or the topic is gone, it is an `idx:tf:` cursor that continues in
+     * the index (`cursor`), the same stream for every topic of the network. The `trend` of a gone topic
+     * carries its id as its title. Pass the cursor back unchanged like any other. When the index cannot
+     * answer, the page is what the provider answered (the empty page with its cursor, or the gone topic's
+     * 404); only an `idx:tf:` page is 503 `unavailable`, which ends that continuation, not the network.
+     */
+    sourceIndex?: SocialTrendSourceIndex & {
+        reason: 'gone' | 'empty' | 'cursor';
+    };
 }
 /** A member of a radar cluster: a headline or excerpt and a link only, never a body. */
 export type SocialRadarSourceKind = 'outlet' | 'hackernews' | 'bluesky' | 'activitypub' | 'nostr' | 'minds';
@@ -1103,6 +1119,15 @@ export interface SocialRadarMember {
         height?: number;
     };
     providerRank?: number;
+    /**
+     * Present on a post member whose image or video a signed-out visitor may see (an open-network post with a cached
+     * safe verdict, or a Minds post that passes the visitor's floor); absent on every other post member, and on members
+     * of a radar built before the server recorded it. An outlet's media needs no mark. The keyless routes
+     * (`getSharedRadar`, `getSharedRadarPosts`, `getSharedRadarStory`) serve media only from marked members and outlets.
+     * A signed-in read (`getPublicRadar` and friends) keeps every member's media, so use only an outlet's or a marked
+     * member's media on a signed-out page or a share card.
+     */
+    visitorMedia?: true;
 }
 /** One story on the radar. `breaking` is outlet corroboration inside a short window; `viral` is social velocity above its network's norm. */
 export interface SocialRadarCluster {
@@ -1127,6 +1152,7 @@ export interface SocialRadarCluster {
         normalized: number;
         samples: number;
     };
+    /** On a signed-in read the lead may belong to a member without `visitorMedia`; find it by `memberKey` before a share card uses it. */
     media: {
         images: number;
         videos: number;
@@ -1317,7 +1343,10 @@ export declare class ProtocolsResource {
         category?: string;
         discovery?: boolean;
     }): Promise<SingleResponse<SocialTrendFeed>>;
-    /** Breaking and viral stories clustered across outlets, open networks and Minds, through the same public-only app boundary. */
+    /**
+     * Breaking and viral stories clustered across outlets, open networks and Minds, through the same public-only app boundary.
+     * Images and videos come only from outlets and from members marked `visitorMedia`; every other member is text.
+     */
     getSharedRadar(projectId: string, params?: SocialRadarParams): Promise<SingleResponse<SocialRadar>>;
     /** One radar story's social member posts without a key, so a signed-out story card can show the posts it counts. */
     getSharedRadarPosts(projectId: string, params: {
@@ -1379,7 +1408,10 @@ export declare class ProtocolsResource {
         category?: string;
         discovery?: boolean;
     }, options?: SocialReadOptions): Promise<SingleResponse<SocialTrendFeed>>;
-    /** The app's topic radar under its own key: the same snapshot the keyless route serves. Never triggers a build. */
+    /**
+     * The app's topic radar under its own key: the same snapshot the keyless route serves, for a signed-in reader, so
+     * every member keeps its media (the keyless route serves only outlets' and `visitorMedia` members'). Never triggers a build.
+     */
     getPublicRadar(params?: SocialRadarParams, options?: SocialReadOptions): Promise<SingleResponse<SocialRadar>>;
     /** One radar story's social member posts, so its card can show the posts it counts. Minds members are read with `posts.get`. */
     getPublicRadarPosts(params: {

package/dist/resources/protocols.js

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

package/dist/resources/reports.d.ts

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

package/dist/resources/reports.js

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