@recursiv/sdk 0.7.63 → 0.7.66

package/README.md

@@ -95,6 +95,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 |----------|------------|
 | `r.posts` | `create`, `update`, `list`, `liked`, `bookmarked`, `bookmark`, `unbookmark`, `search`, `replies`, `react` |
 | `r.bookmarks` | `save`, `unsave`, `posts`, `list`, `keys`, `merge` — the member's saved posts, open-network posts and articles, synced across devices |
+| `r.feeds` | `top` (what the member is most likely to engage with, rotated by what they saw, with open-network lanes and the lead story), `stories` (the story tail), `publicTop` (a visitor's top, keyless and edge-cacheable) |
 | `r.communities` | `create`, `join`, `search`, `members` |
 | `r.chat` | `send`, `dm`, `createGroup` (`encrypted: true` for an end-to-end encrypted group, 0.7.59), `messages` (cursor paging), `acceptRequest`, `declineRequest`, `leave`, `deleteConversation`; a private group's admin: `addMembers`, `removeMember`, `updateGroup` (0.7.59) |
 | `r.tags` | `create`, `list` |
@@ -669,6 +670,58 @@ and says whether the member is personalized yet (`meta.personalized`). With a
 `category` (the member's first), the session also reads open-network posts from it;
 without, it is Minds only. It never carries the radar.
 
+### For You: the world by the member's interests
+
+`sdk.curator.forYouWorld({ part?, session?, snapshot?, compass? })` reads the For You overview
+for the signed-in member, with their own key of the app. `stories` are world stories (Today,
+the radar and the viral read) matched to the member's interests with breadth: at least four
+themes and two breaking or general stories in the first eight, at most two per theme, and a
+story shown three times without an open rests for a week. `items` are the member's For You
+picks interleaved with the most engaging posts of their top interests (half or more on their
+interests, no interest over 40%, videos weighted up), and `blocks` lay the page out like All:
+`stories`, `lead_video`, `clips`, `posts`, `people`, `groups`, `topics`, `viral` and
+`categories`, never the same type twice in a row, each naming the refs its views should send.
+Every story and item carries `reasons` (`interest:<category>`, `followed:@<handle>`, `breaking`,
+`general`, `for_you`, `engaging`, `breadth`). `part: 'stories'` and `part: 'items'` read the
+two halves on their own, so an app can draw each as it lands; a part=items answer keeps the
+stories rail as a `deferred` block. `meta.interests` are category ids for chips (never put them
+in a URL), `meta.partial` names a source that missed its deadline, and `meta.foryou_cursor`
+continues the same ranking with `curator.forYou({ cursor })`. 404 while the app's operator has
+it off; a 503 `for_you_world_unavailable` carries Retry-After.
+
+### The top of a feed
+
+`sdk.feeds.top({ ref, limit?, session?, compass? })` answers the top of a feed for the
+signed-in member, read with their own key of the app (`ref`: `builtin:all`,
+`category:<id>`, `following`, `watch` or `story:<cluster id>`): `items` (the posts most
+likely to be engaged with, often video, rotated by what the member has seen), `networks`
+(Bluesky, Fediverse and Nostr lanes of up to six posts, each with a `card` to draw and no
+URL on its network), `lead` (the story the feed should open with) and `meta` (`short`,
+`safety`, whether the order used impressions). Every item's `target` is in the app: a
+post id, `/social/post/<protocol>/<id>`, or a story id. `sdk.feeds.stories({ after?, limit? })`
+is the story tail from the same ranker. `sdk.feeds.publicTop({ projectId, ref?, limit?, compass? })`
+is a visitor's top (safe items only, the same for every visitor in one 15-minute bucket),
+read with no credential so the edge can hold it. Each answers 404 while the app's operator
+has it off. Send `block: 'top'` and the item's position with a visible view of a top item.
+
+A feed session opens with it when asked: `createFeed({ networks, top: { ref, session? }, seen,
+seenClusters?, bucket? })` (or `new DiscoveryFeedSession(..., { top: { ref, read, post? }, seen })`
+with your own readers). The top's read starts with the first page's reads, and the top holds
+the page at most 1.5 s from its start, the reads of its items' posts included; a top that is
+off, fails or is late leaves the session exactly as it is without one. The radar's story reads
+its posts as soon as the radar answers, whatever the top does. When it answers, page 0 opens with the story it leads with, then its items (each item
+carries `top: { ref, position, block }`, a lane entry also `lane`), and its lanes stand in
+for the networks' first reads. Minds items the first hot page does not carry are read by id
+once, within the same 1.5 s (`top.post`, or `GET /posts/:id` without retries). `seen` (Minds post ids and
+`<protocol>/<nativeId>` refs the member already saw) leaves those posts out of the hot pages,
+and no hot page repeats a top item; a hot page left under five posts walks on, up to three
+more pages, and the feed's `fallover` still reports when the ranking ends. Without impressions
+in the top's order, the member's seen top items follow the unseen ones. With no server lead,
+`seenClusters` (`Map<id, { n, clicked }>`) skips a story shown three times without an open,
+and a visitor's `bucket` rotates page 0's story among the breaking ones
+(`pickRadarCluster` is the same rule on its own). With none of these options a session is
+unchanged.
+
 Both take a Politics choice, `compass` (`all`, `mix`, `hide`, or cells in the order
 `lo,co,ro,lm,cm,rm,ll,cl,rl`, optionally `np`), and send it with every Minds read
 (`posts.list` and `curator.forYou` take it too). Each such page says what it did in

package/dist/feed-definition.d.ts

@@ -17,7 +17,11 @@ export declare const FEED_SOURCES_MAX = 50;
 export declare const FEED_DEFINITION_MAX_BYTES: number;
 export declare const FEED_SOURCE_KINDS: readonly ["category", "tag", "account", "community", "collection", "list", "story", "bsky_feed", "bsky_list", "bsky_starterpack", "nostr_set"];
 export type FeedSourceKind = typeof FEED_SOURCE_KINDS[number];
-export declare const FEED_RANKING_MODES: readonly ["hot", "new", "top", "for_you", "viral"];
+/**
+ * 'engagement' ranks by predicted engagement for the reader: the top of a feed (`feeds.top`). Like For you
+ * and viral it reaches past the sources on the reader's behalf.
+ */
+export declare const FEED_RANKING_MODES: readonly ["hot", "new", "top", "for_you", "viral", "engagement"];
 export type FeedRankingMode = typeof FEED_RANKING_MODES[number];
 export declare const FEED_RANKING_RANGES: readonly ["24h", "7d", "30d", "1y"];
 export type FeedRankingRange = typeof FEED_RANKING_RANGES[number];

package/dist/feed-definition.js

@@ -19,7 +19,11 @@ export const FEED_SOURCE_KINDS = [
     'category', 'tag', 'account', 'community', 'collection', 'list', 'story',
     'bsky_feed', 'bsky_list', 'bsky_starterpack', 'nostr_set',
 ];
-export const FEED_RANKING_MODES = ['hot', 'new', 'top', 'for_you', 'viral'];
+/**
+ * 'engagement' ranks by predicted engagement for the reader: the top of a feed (`feeds.top`). Like For you
+ * and viral it reaches past the sources on the reader's behalf.
+ */
+export const FEED_RANKING_MODES = ['hot', 'new', 'top', 'for_you', 'viral', 'engagement'];
 export const FEED_RANKING_RANGES = ['24h', '7d', '30d', '1y'];
 export const FEED_MEDIA = ['any', 'images', 'video', 'longread'];
 export const FEED_NETWORKS = ['minds', 'bluesky', 'activitypub', 'nostr'];

package/dist/index.d.ts

@@ -62,6 +62,7 @@ import { ModerationResource } from './resources/moderation.js';
 import { LinkPreviewResource } from './resources/link-preview.js';
 import { SearchResource } from './resources/search.js';
 import { BookmarksResource } from './resources/bookmarks.js';
+import { FeedsResource } from './resources/feeds.js';
 import { AccountsResource } from './resources/accounts.js';
 import { RealtimeClient } from './realtime.js';
 import type { RecursivConfig } from './types.js';
@@ -121,6 +122,8 @@ export declare class Recursiv {
     readonly jobs: JobsResource;
     readonly curator: CuratorResource;
     readonly discovery: DiscoveryResource;
+    /** The top of a feed: what the member (or a visitor) is most likely to engage with, rotated by what they have seen. */
+    readonly feeds: FeedsResource;
     readonly video: VideoResource;
     readonly appSubscriptions: AppSubscriptionsResource;
     readonly boosts: BoostsResource;
@@ -192,7 +195,7 @@ export { VideoResource } from './resources/video.js';
 export type { VideoUploadCreds, CreateVideoUploadResult, VideoStatusInfo, VideoPlaybackToken, VideoEntitlement, } from './resources/video.js';
 export { AppSubscriptionsResource } from './resources/app-subscriptions.js';
 export type { AppSubscriptionBoostCredit, AppSubscriptionCheckoutResult, AppSubscriptionPortalResult, AppSubscriptionStatusResult, AppSubscriptionTierChangePreview, AppSubscriptionTierChangeResult, } from './resources/app-subscriptions.js';
-export type { CuratorSource, CuratorPrompt, CuratorRunInput, CuratorRunResult, CuratorTodayEdition, CuratorTodayExcerpt, CuratorTodayLeadImage, CuratorTodayRadar, CuratorTodayReaction, CuratorTodayResponse, CuratorTodaySource, CuratorTodayStory, ForYouMeta, ForYouParams, ForYouSurface, } from './resources/curator.js';
+export type { CuratorSource, CuratorPrompt, CuratorRunInput, CuratorRunResult, CuratorTodayEdition, CuratorTodayExcerpt, CuratorTodayLeadImage, CuratorTodayRadar, CuratorTodayReaction, CuratorTodayResponse, CuratorTodaySource, CuratorTodayStory, ForYouMeta, ForYouParams, ForYouSurface, ForYouWorldBlock, ForYouWorldBlockType, ForYouWorldCategoryShortcut, ForYouWorldItem, ForYouWorldMeta, ForYouWorldParams, ForYouWorldPart, ForYouWorldResponse, ForYouWorldStory, ForYouWorldStoryTarget, ForYouWorldViral, } from './resources/curator.js';
 export { ReportsResource } from './resources/reports.js';
 export type { ReportTargetType, ReportStatus, CreateReportInput, ReportRecord, ResolveReportInput, } from './resources/reports.js';
 export { ModerationResource } from './resources/moderation.js';
@@ -201,6 +204,8 @@ export { LinkPreviewResource } from './resources/link-preview.js';
 export { SEARCH_SECTIONS, SearchResource } from './resources/search.js';
 export type { SearchAnswer, SearchGroup, SearchOmitReason, SearchParams, SearchPerson, SearchRelated, SearchResponse, SearchSection, SearchStory, SearchTopic } from './resources/search.js';
 export { BOOKMARK_MERGE_MAX_ITEMS, BookmarksResource } from './resources/bookmarks.js';
+export { FEED_TOP_NETWORKS, FeedsResource } from './resources/feeds.js';
+export type { FeedStoriesParams, FeedStoriesResponse, FeedStory, FeedTopExplain, FeedTopItem, FeedTopMeta, FeedTopNetwork, FeedTopNetworkCard, FeedTopNetworkEntry, FeedTopParams, FeedTopResponse, FeedTopTarget, PublicFeedTopMeta, PublicFeedTopParams, PublicFeedTopResponse, } from './resources/feeds.js';
 export type { BookmarkedPost, BookmarkInput, BookmarkItem, BookmarkKey, BookmarkKeyRow, BookmarkKind, BookmarkMergeItem, BookmarkMergeResult, BookmarkProtocol, BookmarkRequestOptions, BookmarksPage, SavedBookmark, UnsavedBookmark, } from './resources/bookmarks.js';
 export { AccountsResource } from './resources/accounts.js';
 export type { SiblingAccount, SiblingAccountsResponse, SwitchAccountResult, } from './resources/accounts.js';

package/dist/index.js

@@ -63,6 +63,7 @@ import { ModerationResource } from './resources/moderation.js';
 import { LinkPreviewResource } from './resources/link-preview.js';
 import { SearchResource } from './resources/search.js';
 import { BookmarksResource } from './resources/bookmarks.js';
+import { FeedsResource } from './resources/feeds.js';
 import { AccountsResource } from './resources/accounts.js';
 import { RealtimeClient } from './realtime.js';
 export class Recursiv {
@@ -122,6 +123,8 @@ export class Recursiv {
     jobs;
     curator;
     discovery;
+    /** The top of a feed: what the member (or a visitor) is most likely to engage with, rotated by what they have seen. */
+    feeds;
     video;
     appSubscriptions;
     boosts;
@@ -188,7 +191,8 @@ export class Recursiv {
         this.webhooks = new WebhooksResource(client);
         this.jobs = new JobsResource(client);
         this.curator = new CuratorResource(client);
-        this.discovery = new DiscoveryResource(this.posts, this.protocols, this.curator, client);
+        this.feeds = new FeedsResource(client);
+        this.discovery = new DiscoveryResource(this.posts, this.protocols, this.curator, client, this.feeds);
         this.video = new VideoResource(client);
         this.appSubscriptions = new AppSubscriptionsResource(client);
         this.boosts = new BoostsResource(client);
@@ -254,6 +258,7 @@ export { ModerationResource } from './resources/moderation.js';
 export { LinkPreviewResource } from './resources/link-preview.js';
 export { SEARCH_SECTIONS, SearchResource } from './resources/search.js';
 export { BOOKMARK_MERGE_MAX_ITEMS, BookmarksResource } from './resources/bookmarks.js';
+export { FEED_TOP_NETWORKS, FeedsResource } from './resources/feeds.js';
 export { AccountsResource } from './resources/accounts.js';
 export { OrganizationSettingsResource } from './resources/organization-settings.js';
 export { ProjectSettingsResource } from './resources/project-settings.js';

package/dist/resources/curator.d.ts

@@ -1,5 +1,6 @@
 import type { HttpClient } from '../client.js';
-import type { DiscoveryLayout, PaginatedResponse, PaginationMeta, Post, SingleResponse } from '../types.js';
+import type { CompassFilterMeta, DiscoveryLayout, PaginatedResponse, PaginationMeta, Post, SingleResponse } from '../types.js';
+import type { FeedTopNetworkCard, FeedTopTarget } from './feeds.js';
 /** Which surface is asking: Home's For You (default) or Discover's For you. */
 export type ForYouSurface = 'home' | 'discover';
 export type ForYouParams = {
@@ -22,6 +23,158 @@ export interface ForYouMeta extends PaginationMeta {
     /** Whether the ranker can personalize for this member yet (3 follows or 3 upvoted authors). */
     personalized?: boolean;
 }
+/** Which half to read: the stories rail, the items, or both (the default). The app can read the two at once and draw each as it lands. */
+export type ForYouWorldPart = 'stories' | 'items' | 'all';
+export interface ForYouWorldParams {
+    part?: ForYouWorldPart;
+    /** Opaque per app session ([A-Za-z0-9_-], up to 64): the same token keeps one session's order stable across reads. */
+    session?: string;
+    /** A For You snapshot nonce the app holds (`meta.snapshot` of a previous answer): reused while the server holds it. */
+    snapshot?: string;
+    /** A Politics choice, as `posts.list` takes it. */
+    compass?: string;
+}
+/** Where a story opens in the app: a radar story by its cluster id, or a World Today story the radar has none for by its Today id. */
+export type ForYouWorldStoryTarget = {
+    kind: 'story';
+    id: string;
+} | {
+    kind: 'today_story';
+    id: string;
+};
+/** One world story: a radar story (with Today's headline when Today seeded it), a Today story, or a viral post. */
+export interface ForYouWorldStory {
+    /** What an impression of it names: 'cluster:<id>', 'today:<id>' or the post's ref. Send it with `block: 'top'` on a visible view. */
+    ref: string;
+    id: string;
+    source: 'today' | 'radar' | 'viral';
+    target: FeedTopTarget | ForYouWorldStoryTarget;
+    label: string;
+    kind: 'breaking' | 'viral' | 'story';
+    breaking: boolean;
+    /** A front-page or general-news story: one of those shown whatever the member's interests. */
+    general: boolean;
+    theme: string | null;
+    categories: string[];
+    /** How widely it is told: posts per source kind, and the outlets that ran it (Today), when known. */
+    counts: {
+        sources: Record<string, number>;
+        outlets: number | null;
+    };
+    media: {
+        images: number;
+        videos: number;
+    };
+    freshness: {
+        newestAt: string | null;
+    };
+    position: number;
+    /** Why it is here: `interest:<category>`, `breaking`, `general`, `viral`, `breadth` or `trending`. */
+    reasons: string[];
+    explain: {
+        score: number;
+        interest: number;
+        rank: number;
+        impression: 'fresh' | 'demoted';
+    };
+}
+/** One item: a Minds post (`ref` is its id) or an open-network post (`ref` is '<protocol>/<nativeId>'). */
+export interface ForYouWorldItem {
+    ref: string;
+    kind: 'post' | 'network_post';
+    authorId: string;
+    target: FeedTopTarget;
+    /** Reading order through the blocks. */
+    position: number;
+    /** 'top' for the first 10: send `block: 'top'` and the position with a visible view of one. */
+    block: 'top' | 'below';
+    media: 'video' | 'image' | 'none';
+    topic: string | null;
+    /** Why it is here: `interest:<category>`, `followed:@<handle>`, `for_you`, `engaging` or `breadth`. */
+    reasons: string[];
+    explain: {
+        score: number;
+        source: 'foryou' | 'category' | 'all';
+        label: 'safe' | 'open';
+        impression: 'fresh' | 'demoted';
+        engagement: {
+            source: string;
+            rate: number;
+        };
+    };
+}
+/** A viral post in the viral block. `card` is an open-network post's card (no URL on its network); null for a Minds post, read by id. */
+export interface ForYouWorldViral {
+    ref: string;
+    kind: 'post' | 'network_post';
+    protocol: string;
+    target: FeedTopTarget;
+    label: string;
+    category: string | null;
+    media: 'video' | 'image' | null;
+    rank: number;
+    velocity: {
+        perHour1h: number;
+        z: number;
+    };
+    card: FeedTopNetworkCard | null;
+}
+export interface ForYouWorldCategoryShortcut {
+    id: string;
+    name: string;
+    reason: 'interest' | 'breadth';
+    target: {
+        kind: 'category';
+        id: string;
+    };
+}
+/** The page's components, laid out like All: no type follows itself. */
+export type ForYouWorldBlockType = 'stories' | 'lead_video' | 'clips' | 'posts' | 'people' | 'groups' | 'topics' | 'categories' | 'viral';
+export interface ForYouWorldBlock {
+    id: string;
+    type: ForYouWorldBlockType;
+    /** What it shows, in order: item refs (lead_video, clips, posts), story refs, entity keys, category ids or viral refs. */
+    refs: string[];
+    /** The stories rail of a part=items answer: fill it from your own part=stories read. */
+    deferred?: true;
+    /** people, groups and topics: the recommender's suggestions (three showings without a tap rest one). */
+    entities?: Array<Record<string, unknown> & {
+        kind: string;
+        key: string;
+    }>;
+    categories?: ForYouWorldCategoryShortcut[];
+    viral?: ForYouWorldViral[];
+}
+export interface ForYouWorldMeta {
+    part: ForYouWorldPart;
+    flag: {
+        world: 'on';
+        impressions: 'on' | 'off' | 'unavailable';
+    };
+    /** Fewer than 3 follows and no signals yet: a breadth-only overview. */
+    cold_start: boolean;
+    personalized: boolean | null;
+    /** The member's top interests as browse category ids, for chips. Never put them in a URL. */
+    interests: string[];
+    /**
+     * Sources left out because they missed their deadline or failed. `consent` is the Bluesky consent read: when it is
+     * named, Bluesky posts from the category pools and the viral read were left out of this answer.
+     */
+    partial: string[];
+    safety: 'safe' | 'open' | null;
+    /** The For You snapshot the items came from; `foryou_cursor` continues it on `curator.forYou({ cursor })`. */
+    snapshot: string | null;
+    foryou_cursor: string | null;
+    short: boolean;
+    compass_filter?: CompassFilterMeta;
+}
+/** GET /curator/foryou/world: `stories` unless part=items, `items` and `blocks` unless part=stories. */
+export interface ForYouWorldResponse {
+    stories?: ForYouWorldStory[];
+    items?: ForYouWorldItem[];
+    blocks?: ForYouWorldBlock[];
+    meta: ForYouWorldMeta;
+}
 /** RSS / Atom source. Default — `type` may be omitted for back-compat. */
 export interface CuratorRssSource {
     type?: 'rss';
@@ -278,4 +431,13 @@ export declare class CuratorResource {
     forYou(params?: ForYouParams): Promise<PaginatedResponse<Post> & {
         meta: ForYouMeta;
     }>;
+    /**
+     * For You as an overview of the world by the member's interests, read with their own key of the app: world stories
+     * (interest-matched, with breadth), then a page of typed blocks laid out like All (a lead video, clip strips, posts,
+     * people and groups to follow, trending topics, viral posts, category shortcuts). `part` reads one half on its own.
+     * 404 until the app's operator turns it on; a 503 `for_you_world_unavailable` carries Retry-After. Always private.
+     */
+    forYouWorld(params?: ForYouWorldParams, options?: {
+        retry?: boolean;
+    }): Promise<ForYouWorldResponse>;
 }

package/dist/resources/curator.js

@@ -57,4 +57,13 @@ export class CuratorResource {
         const { retry, ...query } = params;
         return retry === false ? this.client.get('/curator/foryou', query, { retry: false }) : this.client.get('/curator/foryou', query);
     }
+    /**
+     * For You as an overview of the world by the member's interests, read with their own key of the app: world stories
+     * (interest-matched, with breadth), then a page of typed blocks laid out like All (a lead video, clip strips, posts,
+     * people and groups to follow, trending topics, viral posts, category shortcuts). `part` reads one half on its own.
+     * 404 until the app's operator turns it on; a 503 `for_you_world_unavailable` carries Retry-After. Always private.
+     */
+    forYouWorld(params = {}, options) {
+        return this.client.get('/curator/foryou/world', { part: params.part, session: params.session, snapshot: params.snapshot, compass: params.compass }, options);
+    }
 }

package/dist/resources/discovery.d.ts

@@ -2,6 +2,7 @@ import type { HttpClient } from '../client.js';
 import type { CompassFilterMeta, DiscoveryLayout, FalloverStep, MediaItem, Post } from '../types.js';
 import type { CuratorResource } from './curator.js';
 import type { DiscoveryLearning } from './discovery-learning.js';
+import type { FeedStory, FeedTopItem, FeedTopNetwork, FeedTopNetworkEntry, FeedsResource } from './feeds.js';
 import type { PostsResource } from './posts.js';
 import type { ProtocolsResource, SocialNetwork, SocialPost, SocialRadar, SocialRadarPosts } from './protocols.js';
 export type DiscoveryRecommendationKind = 'groups' | 'people' | 'tags';
@@ -284,15 +285,97 @@ export interface DiscoveryRadarMemberSources {
     }>;
 }
 export type DiscoveryRadarPresentation = 'breaking' | 'story';
+/** Where an item sits in the top of the feed: set only on the items a session's top placed on its first page. */
+export interface DiscoveryTopPlacement {
+    /** The item's ref in the top (a Minds post id, or '<protocol>/<nativeId>'): what a visible view of it names. */
+    ref: string;
+    /** Its position in the top, or in its network's lane. */
+    position: number;
+    /** 'top' for the first 10: send `block: 'top'` and the position with a visible view of one (an impression). */
+    block: 'top' | 'below';
+    /** Set on an open-network lane's entry: its network. */
+    lane?: FeedTopNetwork;
+}
 export type DiscoveryPostItem = {
     key: string;
     kind: 'minds';
     post: Post;
+    top?: DiscoveryTopPlacement;
 } | {
     key: string;
     kind: 'social';
     post: SocialPost;
+    top?: DiscoveryTopPlacement;
 };
+/** What a session reads of a top answer: the member route's (`feeds.top`) and the visitor read's (`feeds.publicTop`) common shape. */
+export interface DiscoveryTopAnswer {
+    items: FeedTopItem[];
+    networks: Partial<Record<FeedTopNetwork, FeedTopNetworkEntry[]>> | null;
+    lead: FeedStory | null;
+    meta?: {
+        flag?: {
+            impressions?: string;
+        };
+    };
+}
+/** Reads the top of the session's feed. */
+export type DiscoveryTopSource = (params: {
+    ref: string;
+    limit: number;
+    session?: string;
+}) => Promise<DiscoveryTopAnswer>;
+/** The top of the feed a session opens with (`discovery.createFeed({ top })`, or DiscoveryFeedSession's options). */
+export interface DiscoveryTopOptions {
+    /**
+     * The feed's ref as the reader takes it: `builtin:all`, `category:<id>`, `following`, `watch` or `story:<id>` for
+     * `feeds.top`; `all`, `watch` or `category:<id>` for `feeds.publicTop`.
+     */
+    ref: string;
+    /** Items asked for, 1..25 (default DISCOVERY_TOP_LIMIT). */
+    limit?: number;
+    /** The app's session token (`feeds.top` keeps one session's order stable with it). */
+    session?: string;
+    /** The reader. createFeed reads `feeds.top` (with its `compass`); a session built directly has no top without one. */
+    read?: DiscoveryTopSource;
+    /**
+     * Reads one Minds post by id, for a top item the first hot page does not carry, within the top's one deadline
+     * (DISCOVERY_TOP_TIMEOUT_MS from the page's start). Defaults to the session's radar Minds reader; createFeed passes
+     * `GET /posts/:id` without retries. Without either, a Minds top item shows only when the first hot page carries it.
+     */
+    post?: (id: string) => Promise<{
+        data: Post;
+    }>;
+}
+/** What a member saw of a radar story: how often its lead was on screen, and whether they ever opened it. */
+export interface DiscoverySeenCluster {
+    n: number;
+    clicked: boolean;
+}
+/** The options a session takes besides its readers. With none set, a session answers exactly what 0.7.63's did. */
+export interface DiscoveryFeedSessionOptions {
+    /**
+     * The top of the feed. Its read starts with the first page's reads, and it holds the page at most
+     * DISCOVERY_TOP_TIMEOUT_MS from the page's start, the reads of its items' posts included: a top that fails (404 while
+     * it is off, a network error, a timeout) leaves the session exactly as it is without one. The radar's own story reads
+     * its member posts as soon as the radar answers, whatever the top does; a different story the top leads with reads its
+     * own from the moment the top answers.
+     * When it answers, the first page opens with its items (each carrying `top`), its open-network lanes stand in for the
+     * networks' first reads (a topics network's previews), its lead is the page's story, and no later hot page repeats an
+     * item it placed.
+     */
+    top?: DiscoveryTopOptions;
+    /**
+     * What the member already saw (Minds post ids and '<protocol>/<nativeId>' refs, as the app records visible views): left
+     * out of the Minds hot pages. A page the filter leaves under DISCOVERY_SEEN_MIN_ITEMS walks on, up to
+     * DISCOVERY_SEEN_WALK more hot pages, and the stream's fall-through (`fallover`) still reports when it ends. When the
+     * top's order did not use impressions (`meta.flag.impressions` not 'on'), the top's seen items follow its unseen ones.
+     */
+    seen?: Iterable<string>;
+    /** The client's own story rotation, for a session with no server lead: a story shown RADAR_REST_AFTER times with no open is skipped. */
+    seenClusters?: ReadonlyMap<string, DiscoverySeenCluster>;
+    /** A visitor's rotation bucket (e.g. floor(now / 15 min)): page 0's story rotates among the breaking stories by it. */
+    bucket?: number;
+}
 export type DiscoveryItem = DiscoveryPostItem | {
     key: string;
     kind: 'group';
@@ -325,6 +408,22 @@ export declare const DISCOVERY_SOURCE_TIMEOUT_MS = 15000;
  * "Minds posts didn't load" with Try again and which its Politics fallback (minds#1212) waits for.
  */
 export declare const DISCOVERY_SOURCE_RETRIES = 2;
+/**
+ * The longest the top of the feed holds the first page, counted from the page's start. The top's read and the reads of
+ * the posts its items need (Minds posts by id, a story's network posts) share this one deadline: a top that has not
+ * answered by then is left out, and an item whose post was not read by then shows only if the first hot page carries it.
+ */
+export declare const DISCOVERY_TOP_TIMEOUT_MS = 1500;
+/** Top items a session asks for unless its options say otherwise: the top block. */
+export declare const DISCOVERY_TOP_LIMIT = 10;
+/** A hot page the seen set (or the top) leaves under this many posts walks on to the next hot page... */
+export declare const DISCOVERY_SEEN_MIN_ITEMS = 5;
+/** ...up to this many more pages in one read; then the page is what it is and the next read goes on from there. */
+export declare const DISCOVERY_SEEN_WALK = 3;
+/** A story whose lead was on screen this many times with no open is skipped (DiscoveryFeedSessionOptions.seenClusters). */
+export declare const RADAR_REST_AFTER = 3;
+/** A visitor's page-0 story rotates by bucket among this many best breaking stories (or best stories when none is breaking). */
+export declare const RADAR_BUCKET_ROTATION = 5;
 /**
  * Whether a source's read failed for a reason that passes: it ran past its deadline, its call never got an answer (a
  * failed connection or an abort, as the session's read reports it), or the server answered 408, 425, 429 or 5xx (or no
@@ -332,6 +431,17 @@ export declare const DISCOVERY_SOURCE_RETRIES = 2;
  * checking it) and any other 4xx are the source's own failure and are not asked again.
  */
 export declare function transientSourceFailure(error: unknown): boolean;
+/** Page 0's story, else a later page's: the client's own pick, for a session with no lead from the top of the feed. */
+export interface RadarPickOptions {
+    /** Stories this session already showed. */
+    used?: ReadonlySet<string>;
+    /** What the member saw of each story: one shown RADAR_REST_AFTER times with no open is skipped. */
+    seenClusters?: ReadonlyMap<string, DiscoverySeenCluster>;
+    /** A visitor's bucket: page 0's story rotates by it among the RADAR_BUCKET_ROTATION best breaking stories (best stories when none is breaking). */
+    bucket?: number;
+}
+/** Page 0: the top breaking story, else the top story. Later pages: the next unused story that is not breaking. */
+export declare function pickRadarCluster(clusters: readonly DiscoveryCluster[], page: number, options?: RadarPickOptions): DiscoveryCluster | undefined;
 /** json-render Spec: values are references to authenticated SDK results, never
  * arbitrary executable components, links, generated text or provider markup. */
 export interface DiscoveryModule {
@@ -407,7 +517,21 @@ export declare class DiscoveryFeedSession {
     private radarLoading;
     /** Member reads per story, started as soon as the story is known and shared by whichever page shows it. */
     private memberReads;
-    constructor(posts: Pick<PostsResource, 'list'>, protocols: Pick<ProtocolsResource, 'getPublicTrends' | 'getPublicTrendFeed'>, networks: SocialNetwork[], category?: string | undefined, source?: string, learning?: DiscoveryLearning | undefined, recommend?: DiscoveryRecommendationSources | undefined, radar?: DiscoveryRadarSource, members?: DiscoveryRadarMemberSources | undefined);
+    /** The top of the feed (options.top with a reader), its read started with page 0's reads, and the keys it placed. */
+    private top?;
+    private topLoading;
+    /** The story the top leads with, once its answer is in (null: it names none); undefined until then. */
+    private topLead;
+    private topKeys;
+    /** What the member already saw (options.seen): left out of the Minds hot pages. */
+    private appSeen;
+    private seenClusters?;
+    private bucket?;
+    constructor(posts: Pick<PostsResource, 'list'>, protocols: Pick<ProtocolsResource, 'getPublicTrends' | 'getPublicTrendFeed'>, networks: SocialNetwork[], category?: string | undefined, source?: string, learning?: DiscoveryLearning | undefined, recommend?: DiscoveryRecommendationSources | undefined, radar?: DiscoveryRadarSource, members?: DiscoveryRadarMemberSources | undefined, options?: DiscoveryFeedSessionOptions);
+    /** The Minds hot pages leave out what the member saw or the top placed, and walk on past a page that leaves too little. */
+    private get filtering();
+    /** A Minds hot item the page leaves out: shown on an earlier page, placed by the top, or in the member's seen set. */
+    private hiddenFromHot;
     retryFailed(): void;
     next(): Promise<DiscoveryFeedPage>;
     private read;
@@ -421,10 +545,35 @@ export declare class DiscoveryFeedSession {
      */
     private walkTopics;
     private readPage;
-    /** Page 0: the top breaking cluster, else the top cluster. Every second later page: the next unused story or viral cluster. */
+    /**
+     * Page 0: the top's lead when it names one, else the top breaking cluster, else the top cluster. Every second later
+     * page: the next unused story or viral cluster.
+     */
     private radarCluster;
-    /** Page 0: the top breaking cluster, else the top cluster. Later pages: the next unused story or viral cluster. */
+    /** Page 0: the top breaking cluster, else the top cluster. Later pages: the next unused story or viral cluster (pickRadarCluster). */
     private pickCluster;
+    /** Page 0's story: the top's lead (from the radar snapshot when it holds it, so its links and members come along), else the client's pick. */
+    private leadOf;
+    /** One top item as its own module, in the top's order: a video plays as a video module (unless the member's layouts say posts). */
+    private topModule;
+    /**
+     * The top's read, then the posts its items need, all under one deadline of DISCOVERY_TOP_TIMEOUT_MS from the page's
+     * start: the reads of its posts get what is left of it, never a deadline of their own. Null when it failed, timed out
+     * or answered nothing usable: the page is then as without a top.
+     */
+    private loadTop;
+    /**
+     * Checks a top answer and reads what its items need before `deadline`: Minds posts by id, a story's network posts
+     * (lanes come with their cards). A lead it names starts reading its member posts at once.
+     */
+    private readyTop;
+    /**
+     * Places the top on page 0: each lane stands in for its network's first read (a topics network's catalog previews; a
+     * posts network's read follows its lane), and the top's items, read by id or carried by this page, become the page's
+     * first items, marked seen so no hot page repeats them. Without impressions in the top's order, the member's seen
+     * items follow the unseen ones.
+     */
+    private placeTop;
     /** The story's members as feed items, read once per story and bounded to three seconds; a failed read is simply none. */
     private memberPosts;
     private readMembers;
@@ -437,7 +586,8 @@ export declare class DiscoveryResource {
     private protocols;
     private curator?;
     private http?;
-    constructor(posts: PostsResource, protocols: ProtocolsResource, curator?: Pick<CuratorResource, "forYou"> | undefined, http?: Pick<HttpClient, "get" | "post"> | undefined);
+    private feeds?;
+    constructor(posts: PostsResource, protocols: ProtocolsResource, curator?: Pick<CuratorResource, "forYou"> | undefined, http?: Pick<HttpClient, "get" | "post"> | undefined, feeds?: Pick<FeedsResource, "top"> | undefined);
     /**
      * 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
@@ -497,6 +647,10 @@ export declare class DiscoveryResource {
      * Discover's feed session. `compass` (a Politics choice, as `posts.list` takes it) goes on every Minds read, whose
      * pages then carry `meta.compass_filter`; the open networks' reads and the radar are not filtered by it, so a view
      * that leaves posts out (Hide politics, Choose sides) is best read with `source: 'minds'`.
+     *
+     * `top` opens the first page with the top of the feed (`feeds.top`, with the same `compass`, unless `top.read` is
+     * given); `seen` leaves what the member saw out of the hot pages; `seenClusters` and `bucket` rotate the story when
+     * the top names none (DiscoveryFeedSessionOptions). With none of them the session is what it was before they existed.
      */
     createFeed(options: {
         networks: SocialNetwork[];
@@ -505,5 +659,5 @@ export declare class DiscoveryResource {
         learning?: DiscoveryLearning;
         recommend?: DiscoveryRecommendationSources;
         compass?: string;
-    }): DiscoveryFeedSession;
+    } & DiscoveryFeedSessionOptions): DiscoveryFeedSession;
 }