@recursiv/sdk 0.7.52 → 0.7.53

package/dist/resources/discovery.js

@@ -8,6 +8,20 @@ const RADAR_MAX_MEMBERS = 12;
 const RADAR_MAX_MINDS_READS = 4;
 /** A discovery page holds its own deadline: a retried 5xx from one provider only makes the whole page wait. */
 const NO_RETRY = { retry: false };
+/**
+ * The provider no longer lists the topic (`trend_unavailable`): that topic's end, never a network
+ * failure. Matched on the server's code, which every SDK error carries: any other 404 on the route
+ * (`unsupported_protocol`, a missing route) is the network failing, and still fails the source.
+ */
+const isGone = (error) => typeof error === 'object' && error !== null && error.code === 'trend_unavailable';
+/**
+ * Topic pages one read of a topics network walks past when each is gone or carries nothing in the
+ * category, so a page reaches a topic that carries posts. Live (2026-09-26, Bluesky, news) 21 of 25
+ * topics answered no posts in the category; one topic a read left the network out of most pages.
+ */
+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;
 const RECOMMENDATION_KINDS = ['groups', 'people', 'tags'];
 const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0 && value.length <= 512;
 function recommendationItem(kind, candidate) {
@@ -116,7 +130,7 @@ function windowLayout(layout, index) {
 }
 /** Per-viewer feed session. Create a new session when user, app, category or
  * source changes. All reads retain existing server authorization/moderation.
- * At most four requests per page; providers fail independently. */
+ * At most four sources per page (a topics network's read walks up to TOPIC_WALK topic pages); providers fail independently. */
 export class DiscoveryFeedSession {
     posts;
     protocols;
@@ -181,23 +195,9 @@ export class DiscoveryFeedSession {
             if (data.coverage !== 'provider_ranked_window' || data.items.length > 25 || data.items.some(post => post.protocol !== stream.protocol || post.author.protocol !== stream.protocol))
                 throw new Error('Invalid discovery source response');
         };
-        if (stream.topics) {
-            const topic = stream.topics[0];
-            if (!topic) {
-                stream.done = true;
-                return { items: [], layout: ordinary, partial: false };
-            }
-            const { data } = await this.protocols.getPublicTrendFeed({ ...params, protocol: stream.protocol, topic: topic.topic, cursor: topic.cursor }, NO_RETRY);
-            validatePosts(data);
-            if (data.trend.protocol !== stream.protocol || data.trend.nativeId !== topic.topic)
-                throw new Error('Invalid discovery topic');
-            const next = data.cursor;
-            stream.topics.shift();
-            if (next && next !== topic.cursor && !topic.used.includes(next))
-                stream.topics.push({ topic: topic.topic, cursor: next, used: [...topic.used, ...(topic.cursor ? [topic.cursor] : [])].slice(-32) });
-            stream.done = !stream.topics.length;
-            return { items: data.items.map(post => ({ key: key(post.protocol, post.nativeId), kind: 'social', post })), layout: data.discovery ?? ordinary, partial: data.categoryFilter?.status === 'partial' };
-        }
+        const started = Date.now();
+        if (stream.topics)
+            return this.walkTopics(stream, params, validatePosts, false, started);
         const { data } = await this.protocols.getPublicTrends({ ...params, protocol: stream.protocol, cursor: stream.cursor, includePreviews: true }, NO_RETRY);
         if (data.coverage !== 'provider_ranked_window' || data.items.length > 25 || data.items.some(item => item.protocol !== stream.protocol))
             throw new Error('Invalid discovery source response');
@@ -206,7 +206,14 @@ export class DiscoveryFeedSession {
                 throw new Error('Invalid discovery preview');
             stream.topics = [...new Set(data.items.map(topic => topic.nativeId))].map(topic => ({ topic, used: [] }));
             stream.done = !stream.topics.length;
-            return { items: data.items.flatMap(topic => !this.category && topic.preview ? [{ key: key(topic.preview.protocol, topic.preview.nativeId), kind: 'social', post: topic.preview }] : []), layout: ordinary, partial: data.categoryFilter?.status === 'partial' };
+            const partial = data.categoryFilter?.status === 'partial';
+            // Outside a category the catalog's previews are this page. In a category a preview is not
+            // judged to be in it, so the catalog carries no card: the read walks into its topics now,
+            // not a round later, so the network's first page in a category is not empty by design.
+            const previews = data.items.flatMap(topic => !this.category && topic.preview ? [{ key: key(topic.preview.protocol, topic.preview.nativeId), kind: 'social', post: topic.preview }] : []);
+            if (previews.length || stream.done)
+                return { items: previews, layout: ordinary, partial };
+            return this.walkTopics(stream, params, validatePosts, partial, started);
         }
         validatePosts(data);
         const next = data.cursor ?? undefined;
@@ -216,6 +223,42 @@ export class DiscoveryFeedSession {
         stream.cursor = next;
         return { items: data.items.map(post => ({ key: key(post.protocol, post.nativeId), kind: 'social', post })), layout: data.discovery ?? ordinary, partial: data.categoryFilter?.status === 'partial' };
     }
+    /**
+     * One read of a topics network: the next topic page that carries posts. A topic the provider no
+     * longer lists (Bluesky rotates its trends between the catalog read and the walk through it) is
+     * that topic's end, not the network's failure; a topic page with nothing in the category is
+     * walked past too, and its continuation kept, so the page reaches a topic that carries posts
+     * instead of spending a round on each empty one. Bounded by TOPIC_WALK reads and TOPIC_WALK_MS;
+     * a walk that stops short has moved the stream on, and the next read continues from there.
+     */
+    async walkTopics(stream, params, validatePosts, partial, started) {
+        const topics = stream.topics;
+        for (let reads = 0; reads < TOPIC_WALK && Date.now() - started < TOPIC_WALK_MS; reads++) {
+            const topic = topics[0];
+            if (!topic)
+                break;
+            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; });
+            topics.shift();
+            if (!response)
+                continue;
+            const { data } = response;
+            validatePosts(data);
+            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))
+                topics.push({ topic: topic.topic, cursor: next, used: [...topic.used, ...(topic.cursor ? [topic.cursor] : [])].slice(-32) });
+            partial ||= data.categoryFilter?.status === 'partial';
+            if (data.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 };
+            }
+        }
+        stream.done = !topics.length;
+        return { items: [], layout: ordinary, partial };
+    }
     async readPage() {
         // The radar is one small snapshot read: start it with the page, not after the slowest provider,
         // and start the lead story's member reads the moment the snapshot names it.
@@ -466,10 +509,30 @@ export class DiscoveryResource {
     posts;
     protocols;
     curator;
-    constructor(posts, protocols, curator) {
+    http;
+    constructor(posts, protocols, curator, http) {
         this.posts = posts;
         this.protocols = protocols;
         this.curator = curator;
+        this.http = http;
+    }
+    /**
+     * Suggestions for the signed-in viewer from the app's one recommender: active or warm members, groups
+     * with several posters, tags used by several people, open-network accounts or stories, overall or in one
+     * browse category. What the viewer follows, joined, blocked or muted is left out, and so is anything
+     * resting for them. Call `recordImpressions` when suggestions are actually on screen and when one is tapped.
+     */
+    recommendations(params, options) {
+        if (!this.http)
+            throw new Error('recommendations needs the HTTP client');
+        const { exclude, ...rest } = params;
+        return this.http.get('/discover/recommendations', { ...rest, exclude: exclude?.length ? exclude.join(',') : undefined }, options);
+    }
+    /** Records that suggestions were shown (at most once per half hour counts) or engaged with. */
+    recordImpressions(input) {
+        if (!this.http)
+            throw new Error('recordImpressions needs the HTTP client');
+        return this.http.post('/discover/impressions', input);
     }
     /**
      * A For you Discover feed: the member's For You ranking (asked for Discover's surface, with layouts and a

package/dist/resources/link-preview.d.ts

@@ -9,7 +9,13 @@ export interface LinkPreview {
     siteName: string | null;
 }
 export interface LinkPreviewResponse {
-    data: LinkPreview;
+    /**
+     * The preview, or null when the link cannot be previewed: the page refused a
+     * server (a private repository, a paywall or bot wall), is not HTML, or could
+     * not be reached. Show the plain link. Servers before this change answered
+     * 422 for these links instead, so treat that rejection the same way.
+     */
+    data: LinkPreview | null;
     cached?: boolean;
 }
 export declare class LinkPreviewResource {
@@ -17,9 +23,10 @@ export declare class LinkPreviewResource {
     constructor(client: HttpClient);
     /**
      * Fetch Open Graph / Twitter card metadata for a public URL. Cached
-     * server-side so repeated lookups are cheap. No auth required — the
-     * endpoint is intentionally public so unauthenticated UIs can render
-     * link previews.
+     * server-side so repeated lookups are cheap, including links that have no
+     * preview (`data: null`). No auth required — the endpoint is intentionally
+     * public so unauthenticated UIs can render link previews. A URL that is not
+     * http(s), or points at a private or internal address, still rejects (422).
      */
     get(url: string): Promise<LinkPreviewResponse>;
 }

package/dist/resources/link-preview.js

@@ -5,9 +5,10 @@ export class LinkPreviewResource {
     }
     /**
      * Fetch Open Graph / Twitter card metadata for a public URL. Cached
-     * server-side so repeated lookups are cheap. No auth required — the
-     * endpoint is intentionally public so unauthenticated UIs can render
-     * link previews.
+     * server-side so repeated lookups are cheap, including links that have no
+     * preview (`data: null`). No auth required — the endpoint is intentionally
+     * public so unauthenticated UIs can render link previews. A URL that is not
+     * http(s), or points at a private or internal address, still rejects (422).
      */
     get(url) {
         return this.client.get('/link-preview', { url });

package/dist/resources/notifications.d.ts

@@ -7,6 +7,12 @@ export interface NotificationActor {
     username: string | null;
     image: string | null;
     is_ai: boolean | null;
+    /**
+     * Follow rows only: whether the viewer already follows this person, so
+     * Follow back can render without reading the follow set. Absent on other
+     * rows and from servers older than this field.
+     */
+    viewer_follows?: boolean;
 }
 /**
  * The post a notification references, as it reads NOW, with the viewer's own
@@ -15,7 +21,18 @@ export interface NotificationActor {
  */
 export interface NotificationPostPreview {
     id: string;
+    /**
+     * The post's words as plain text (no Markdown or HTML marks; a link reads as
+     * its label and a bare URL as its site), up to 140 characters. A longer post
+     * is cut at the last whole word and ends in "…". Show it as it is.
+     */
     excerpt: string | null;
+    /**
+     * True when `excerpt` is a cut of a longer post. Use this rather than the
+     * excerpt's length to decide whether there is more to read. Absent from
+     * servers older than this field.
+     */
+    excerpt_truncated?: boolean;
     media_url: string | null;
     media_type: string | null;
     reactions_count?: number;
@@ -24,7 +41,10 @@ export interface NotificationPostPreview {
     downvote_count?: number;
     /** The viewer's own reaction on this post ('upvote', 'downvote', ...), if any. */
     user_reaction?: string | null;
+    /** Stored replies a reader can open. */
     reply_count?: number;
+    /** A legacy import's comment count; none of those comments are stored as replies. */
+    reply_count_external?: number;
     unique_commenters?: number;
     reposts_count?: number;
     /** Id of the viewer's own repost of this post; delete it to undo the repost. */
@@ -43,6 +63,12 @@ export interface Notification {
     read_at: string | null;
     /** For `post_reaction` rows: which reaction ('upvote', 'downvote', ...). Null otherwise or on older rows. */
     reaction_type?: string | null;
+    /**
+     * For `agent_needs_input` rows: whether you have written in the agent's
+     * thread since it asked, which is what answers an ask. The title then reads
+     * "You answered <agent>". Null on other rows; absent from older servers.
+     */
+    answered?: boolean | null;
     actor?: NotificationActor | null;
     post_preview?: NotificationPostPreview | null;
 }

package/dist/resources/posts.d.ts

@@ -1,5 +1,6 @@
 import type { HttpClient } from '../client.js';
-import type { PaginatedResponse, SingleResponse, DeleteResponse, Post, PostDetail, CreatePostInput, CreatedPost, UpdatePostInput, ListPostsParams, ListPostRepliesParams, PostRepliesPage, SearchPostsParams, ReactionType } from '../types.js';
+import type { PaginatedResponse, SingleResponse, DeleteResponse, Post, PostDetail, CreatePostInput, CreatedPost, UpdatePostInput, ListPostsParams, ListPostRepliesParams, PostRepliesPage, SearchPostsParams, SearchPostsResponse, ReactionType } from '../types.js';
+import type { BookmarkedPost, BookmarksPage, SavedBookmark, UnsavedBookmark } from './bookmarks.js';
 /** How GET /posts/categories ordered its answer: the member's own order, the app's popularity order, or the fixed order. */
 export type CategoryOrder = 'personal' | 'popular' | 'static';
 /** Why an answer is not `personal`. */
@@ -33,6 +34,19 @@ export declare class PostsResource {
     }>;
     /** List posts the authenticated caller has upvoted. */
     liked(params?: Pick<ListPostsParams, 'limit' | 'offset' | 'cursor'>): Promise<PaginatedResponse<Post>>;
+    /**
+     * The caller's saved posts in this app, newest saved first, each with `bookmarked_at`. Page on
+     * `meta.next_cursor` (a page can be short while it skips posts the member can no longer read).
+     * Same as `bookmarks.posts`; 503 `bookmarks_unavailable` where synced bookmarks are not available.
+     */
+    bookmarked(params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<BookmarksPage<BookmarkedPost>>;
+    /** Save a post to the caller's synced bookmarks (idempotent). A bare repost is saved as its original: see `post_id`. */
+    bookmark(postId: string): Promise<SingleResponse<SavedBookmark>>;
+    /** Remove a post from the caller's synced bookmarks (idempotent). Pass the `post_id` its save returned. */
+    unbookmark(postId: string): Promise<SingleResponse<UnsavedBookmark>>;
     /** Posts similar to this one (embedding neighbours), in the app's scope. */
     similar(id: string, params?: {
         limit?: number;
@@ -48,8 +62,12 @@ export declare class PostsResource {
     update(id: string, input: UpdatePostInput): Promise<SingleResponse<CreatedPost>>;
     /** Delete a post */
     delete(id: string): Promise<DeleteResponse>;
-    /** Search posts by text query */
-    search(params: SearchPostsParams): Promise<PaginatedResponse<Post>>;
+    /**
+     * Search posts by text query. Relevance (the default) ranks relevance x recency x engagement through
+     * the promotion safety floor; `sort: 'new'` lists newest first. Page with `meta.next_cursor` as
+     * `cursor`; the first relevance page carries `latest`, the last page `fall_over` (SearchPostsResponse).
+     */
+    search(params: SearchPostsParams): Promise<SearchPostsResponse>;
     /** Add or update a reaction on a post */
     react(postId: string, type: ReactionType): Promise<SingleResponse<{
         success: true;

package/dist/resources/posts.js

@@ -20,6 +20,22 @@ export class PostsResource {
     liked(params) {
         return this.list({ ...params, liked: true });
     }
+    /**
+     * The caller's saved posts in this app, newest saved first, each with `bookmarked_at`. Page on
+     * `meta.next_cursor` (a page can be short while it skips posts the member can no longer read).
+     * Same as `bookmarks.posts`; 503 `bookmarks_unavailable` where synced bookmarks are not available.
+     */
+    bookmarked(params) {
+        return this.client.get('/posts', { bookmarked: true, ...params });
+    }
+    /** Save a post to the caller's synced bookmarks (idempotent). A bare repost is saved as its original: see `post_id`. */
+    bookmark(postId) {
+        return this.client.put('/bookmarks', { kind: 'post', post_id: postId });
+    }
+    /** Remove a post from the caller's synced bookmarks (idempotent). Pass the `post_id` its save returned. */
+    unbookmark(postId) {
+        return this.client.delete(`/bookmarks/${encodeURIComponent(`post:${postId}`)}`);
+    }
     /** Posts similar to this one (embedding neighbours), in the app's scope. */
     similar(id, params) {
         return this.client.get(`/posts/${encodeURIComponent(id)}/similar`, params);
@@ -44,7 +60,11 @@ export class PostsResource {
     delete(id) {
         return this.client.delete(`/posts/${id}`);
     }
-    /** Search posts by text query */
+    /**
+     * Search posts by text query. Relevance (the default) ranks relevance x recency x engagement through
+     * the promotion safety floor; `sort: 'new'` lists newest first. Page with `meta.next_cursor` as
+     * `cursor`; the first relevance page carries `latest`, the last page `fall_over` (SearchPostsResponse).
+     */
     search(params) {
         return this.client.get('/posts/search', params);
     }

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, SearchMentionsParams, MentionCandidate, 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, ViewerRelationship } from '../types.js';
 export declare class ProfilesResource {
     private client;
     constructor(client: HttpClient);
@@ -15,14 +15,25 @@ export declare class ProfilesResource {
     /** Get a user by username */
     getByUsername(username: string): Promise<SingleResponse<ProfileDetail>>;
     /** Search users by name or username */
-    search(params: SearchProfilesParams): Promise<PaginatedResponse<Profile>>;
+    /**
+     * Search accounts by name or handle, ranked by match x ln(1 + followers + min(posts, 100)) (doubled for an
+     * official account): empties last and marked `empty`, the official ones `verified`. Every page is
+     * a slice of one ranked pool of 200; past it `has_more` is false.
+     */
+    search(params: SearchProfilesParams): Promise<PaginatedResponse<ProfileSearchResult>>;
     /**
      * Accounts to @mention: people and agents on the caller's network, the
      * caller's follows first. Unlike `search`, this includes agents the app may
      * discover (an agent answers when mentioned); another member's personal AI
      * is never offered.
+     *
+     * A search that runs over its 2 s budget answers 503 with Retry-After. A
+     * type-ahead has its own deadline, so pass `{ retry: false }` to get that
+     * answer at once instead of waiting through retries.
      */
-    mentions(params: SearchMentionsParams): Promise<PaginatedResponse<MentionCandidate>>;
+    mentions(params: SearchMentionsParams, options?: {
+        retry?: boolean;
+    }): Promise<PaginatedResponse<MentionCandidate>>;
     /** Update own profile */
     update(input: UpdateProfileInput): Promise<SingleResponse<Profile>>;
     /** Follow a user */
@@ -30,18 +41,16 @@ export declare class ProfilesResource {
     /** Unfollow a user */
     unfollow(userId: string): Promise<SuccessResponse>;
     /**
-     * List a user's followers. Each row carries the caller's relationship with
-     * it (`is_following`, `follows_you`), so a Follow button needs no second read.
+     * List a user's followers, newest follow first once the server's database
+     * has the follow-list order indexes (until then, in the order it reads
+     * them). Each row carries the caller's relationship with it (`is_following`,
+     * `follows_you`), so a Follow button needs no second read. `search` narrows
+     * the whole list to accounts whose name or handle contains it (at most 200
+     * characters); page the matches with `limit` and `offset`.
      */
-    followers(userId: string, params?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<PaginatedResponse<FollowListProfile>>;
-    /** List who a user follows, each row with the caller's relationship with it. */
-    following(userId: string, params?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<PaginatedResponse<FollowListProfile>>;
+    followers(userId: string, params?: FollowListParams): Promise<PaginatedResponse<FollowListProfile>>;
+    /** List who a user follows, in the order `followers` uses, each row with the caller's relationship with it; `search` as on `followers`. */
+    following(userId: string, params?: FollowListParams): Promise<PaginatedResponse<FollowListProfile>>;
     /**
      * The caller's whole follow set as ids, up to 5000 per page (default 1000).
      * Answers what `isFollowing` answers, for every account at once. Pass

package/dist/resources/profiles.js

@@ -20,6 +20,11 @@ export class ProfilesResource {
         return this.client.get(`/profiles/by-username/${username}`);
     }
     /** Search users by name or username */
+    /**
+     * Search accounts by name or handle, ranked by match x ln(1 + followers + min(posts, 100)) (doubled for an
+     * official account): empties last and marked `empty`, the official ones `verified`. Every page is
+     * a slice of one ranked pool of 200; past it `has_more` is false.
+     */
     search(params) {
         return this.client.get('/profiles/search', params);
     }
@@ -28,9 +33,13 @@ export class ProfilesResource {
      * caller's follows first. Unlike `search`, this includes agents the app may
      * discover (an agent answers when mentioned); another member's personal AI
      * is never offered.
+     *
+     * A search that runs over its 2 s budget answers 503 with Retry-After. A
+     * type-ahead has its own deadline, so pass `{ retry: false }` to get that
+     * answer at once instead of waiting through retries.
      */
-    mentions(params) {
-        return this.client.get('/profiles/mentions', params);
+    mentions(params, options) {
+        return this.client.get('/profiles/mentions', params, options);
     }
     /** Update own profile */
     update(input) {
@@ -45,13 +54,17 @@ export class ProfilesResource {
         return this.client.delete(`/profiles/${userId}/follow`);
     }
     /**
-     * List a user's followers. Each row carries the caller's relationship with
-     * it (`is_following`, `follows_you`), so a Follow button needs no second read.
+     * List a user's followers, newest follow first once the server's database
+     * has the follow-list order indexes (until then, in the order it reads
+     * them). Each row carries the caller's relationship with it (`is_following`,
+     * `follows_you`), so a Follow button needs no second read. `search` narrows
+     * the whole list to accounts whose name or handle contains it (at most 200
+     * characters); page the matches with `limit` and `offset`.
      */
     followers(userId, params) {
         return this.client.get(`/profiles/${userId}/followers`, params);
     }
-    /** List who a user follows, each row with the caller's relationship with it. */
+    /** List who a user follows, in the order `followers` uses, each row with the caller's relationship with it; `search` as on `followers`. */
     following(userId, params) {
         return this.client.get(`/profiles/${userId}/following`, params);
     }

package/dist/resources/protocols.d.ts

@@ -305,6 +305,8 @@ export interface SocialSourceControlDisplay {
     avatarUrl: string | null;
     /** A hidden post's text, at most 140 characters; null for accounts, deleted posts, and moderated posts or authors. */
     excerpt: string | null;
+    /** A hidden ActivityPub post's public reader id, for the conversation read; absent for accounts, other networks and posts observed without one. */
+    readRef?: string;
     observedAt: string;
 }
 export interface SocialSourceControl {
@@ -641,6 +643,8 @@ export interface NativeReplyBatch {
             authorHandle: string;
             text: string;
             textTruncated?: boolean;
+            /** An ActivityPub parent's public reader id, when the reply was prepared with one: pass it to the conversation read. */
+            readRef?: string;
         };
         text: string;
         wireText: string;
@@ -742,7 +746,7 @@ export interface NativeDelegatedReplyHistoryItem {
     createdAt: string;
     text: string;
     textTruncated: boolean;
-    source: Pick<NativeReplyBatch['deliveries'][number]['parent'], 'protocol' | 'nativeId' | 'sourceUrl'>;
+    source: Pick<NativeReplyBatch['deliveries'][number]['parent'], 'protocol' | 'nativeId' | 'sourceUrl' | 'readRef'>;
     deliveries: Array<Pick<NativeReplyBatch['deliveries'][number], 'id' | 'protocol' | 'kind' | 'state' | 'attemptedAt' | 'account' | 'recoverable' | 'replacedBy'> & {
         removalReceipt: NativeReplyRemovalReceipt | null;
     }>;
@@ -751,10 +755,12 @@ export interface NativeNostrReplyResult {
     id: string;
     createdAt: string;
     text: string;
+    /** `readRef`: a linked ActivityPub source's public reader id, for the conversation read (replies saved before it existed have none). */
     source: {
         protocol: SocialSourceRef['protocol'];
         nativeId: string;
         sourceUrl: string;
+        readRef?: string;
     };
     identityId: string;
     pubkey: string;
@@ -962,6 +968,12 @@ export interface SocialPost {
     replyCount: number | null;
     likeCount: number | null;
     repostCount: number | null;
+    /**
+     * When the counts were read from the source network. 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.
+     */
+    countsObservedAt?: string;
     /** Pixel dimensions when the source declares them (Bluesky aspect ratio, Mastodon attachment meta), so a card can take the clip's shape before it loads. */
     media: Array<{
         type: 'image' | 'video';
@@ -1165,17 +1177,46 @@ export interface SocialRadarPosts {
     builtAt: string | null;
     items: SocialPost[];
 }
+/** A story that has left the radar, as the radar's story archive keeps it (up to 30 days after it was last on the radar). */
+export interface SocialRadarStoryArchive {
+    /** The story as the radar last published it. Articles keep their headline and link; a post is a member by reference only (no `title`). */
+    cluster: Pick<SocialRadarCluster, 'id' | 'label' | 'kind' | 'seed' | 'theme' | 'sources' | 'laneMix'> & {
+        members: Array<Pick<SocialRadarMember, 'kind' | 'key' | 'url' | 'publishedAt' | 'outlet'> & {
+            title?: string;
+        }>;
+    };
+    /** Its open-network posts the app's source index still holds and its source controls and safety floor admit today, in member order. */
+    items: SocialPost[];
+    /** A World Today story's dek: an outlet's own sentence, or the editor model's. */
+    summary: {
+        text: string;
+        origin: 'outlet' | 'editor';
+    } | null;
+    /** The first and the last radar build that published it. */
+    firstSeenAt: string;
+    lastSeenAt: string;
+    /** The index holds none of its open-network posts any more (retention or deletion), so none are listed. */
+    postsExpired: boolean;
+}
 /**
  * One radar story by id, with its social member posts.
- * `live`: on the current radar (`cluster` and `items` present). `aged_out`: on one of the last six
- * radars but not this one. `unknown`: not seen in that window (never existed, or aged out long ago).
+ * `live`: on the current radar (`cluster` and `items` present). `aged_out`: not on this radar, but
+ * held by the story archive (`archive`, and the live story it continues as in `successor`) or seen on
+ * one of the last six radars (`archive` null). `unknown`: in neither (never existed, or left longer ago
+ * than the archive keeps stories). A server without the story archive leaves `archive` and `successor` out.
  */
 export interface SocialRadarStory {
     id: string;
     builtAt: string | null;
     status: 'live' | 'aged_out' | 'unknown';
     cluster: SocialRadarCluster | null;
+    /** The live story's posts; empty otherwise (an archived story's are in `archive.items`). */
     items: SocialPost[];
+    archive?: SocialRadarStoryArchive | null;
+    successor?: {
+        id: string;
+        label: string;
+    } | null;
 }
 /** Read options for callers that hold their own deadline, such as a discovery page. */
 export interface SocialReadOptions {