@recursiv/sdk 0.7.68 → 0.7.70

package/README.md

@@ -75,7 +75,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | Resource | Key methods |
 |----------|------------|
 | `r.agents` | `create`, `update`, `chat`, `chatStream`, `retryChatStream`, `grantProjectAccess`, `conversations` |
-| `r.e2ee` | `status`, `registerDevice`, `devices`, `revokeDevice` (`{ cascade }` to also revoke devices approved through it; 409 `has_dependents` otherwise), `requestResetCode` and `resetAccount` (reset encrypted chat with an emailed code where `status().accountReset`), `publishKeyPackages`, `keyPackageStatus`, `claimKeyPackage`, `appendEvent`, `events`, `acknowledge`, `conversations`; device linking by scan: `createLink`, `link`, `scannedLink`, `approveLink`, `completeLink`, `linkProgress`, `cancelLink` (flag-gated E2EE v2 transport; its doorbell is `r.realtime.onE2eeEvent`, which carries a small message's stored ciphertext to the owner's own sockets; link and device changes arrive on `r.realtime.onE2eeLink` and `onE2eeDevices`) |
+| `r.e2ee` | `status`, `registerDevice`, `devices`, `revokeDevice` (`{ cascade }` to also revoke devices approved through it; 409 `has_dependents` otherwise), `requestResetCode` and `resetAccount` (reset encrypted chat with an emailed code where `status().accountReset`), `publishKeyPackages`, `keyPackageStatus`, `claimKeyPackage`, `appendEvent`, `events`, `acknowledge`, `conversations`, `requestStart` and `cancelStartRequest` (ask the other person to encrypt a chat when they have no device yet: a message with `metadata.kind` `e2ee_start_request`; the live ones are `ConversationDetail.encryption_requests`); device linking by scan: `createLink`, `link`, `scannedLink`, `approveLink`, `completeLink`, `linkProgress`, `cancelLink` (flag-gated E2EE v2 transport; its doorbell is `r.realtime.onE2eeEvent`, which carries a small message's stored ciphertext to the owner's own sockets; link and device changes arrive on `r.realtime.onE2eeLink` and `onE2eeDevices`) |
 | `r.brain` | `sendMessage` |
 | `r.commands` | `execute`, `gatePrompt` |
 | `r.projectBrain` | `tasks`, `decisions`, `milestones`, `completeTask`, `usage` |
@@ -99,6 +99,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | `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` |
+| `r.curator` | `today` (World Today; a world story can carry `story_key` and `discussion`, its count across networks), `storyPosts` / `memberStoryPosts` (one page of a story's posts, keyless or under the member's key), `storyPostPages` (walk every page), `forYou`, `run`, `refreshIfStale`, `seedDeck` |
 | `r.uploads` | `uploadMedia` — upload post/chat bytes end to end |
 | `r.video` | `entitlement` (may the caller publish video, and how much is left), `createUpload`, `renewUpload` (the creator's fresh TUS credentials for the same video, with `createUpload`'s `resumeGrant`, so a resume past the hour continues it; 0.7.63), `getStatus`, `getPlaybackToken` |
 
@@ -682,7 +683,9 @@ interests, no interest over 40%, videos weighted up), and `blocks` lay the page
 `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
+`general`, `for_you`, `engaging`, `breadth`). An open-network item carries its `card` (text,
+author, media and counts, no URL on its network) to draw it from; a Minds item's is null (read
+the post by id). `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`
@@ -740,6 +743,20 @@ a legislature, or a party or politician. Hide politics leaves those out whatever
 `feeds.top()` carry `political` too (0.7.67), and those reads and `curator.forYouWorld()` leave political stories out
 under Hide politics.
 
+A World Today story's discussion across networks (0.7.69; servers with World Story Volume on): `sdk.curator.today()`
+gives each world story the server indexed a `story_key` and, when the reader's pool holds a post, a `discussion`:
+`total`, `people`, `by_network` (`minds`, `bluesky`, `activitypub`, `nostr`), `capped` (the pool reached 1,000: show
+"1,000+") and up to two open-network `previews`; `meta.story_volume` says how the pools stand. Without them (an older
+server, or the feature off) show the story as before. The posts behind the count:
+`sdk.curator.storyPosts({ storyKey, network?, sort?: 'top' | 'latest', cursor?, limit? })` keyless (a visitor's view)
+or `sdk.curator.memberStoryPosts(...)` under the member's key (their own blocks, mutes and hidden posts leave each
+page), and `for await (const page of sdk.curator.storyPostPages({ storyKey }, { reader: 'member' }))` walks every
+page. Each item is `{ kind: 'minds', post: Post }` or `{ kind: 'social', post: SocialPost }` (narrow on `kind`; open
+a social post inside the app, never link out); `text_only` means show its words only. A post removed since the build is
+counted in the page's `withheld`, never replaced, so the pages' items plus `withheld` add up to the page's `matched`:
+`discussion.total` for `network: 'all'`, that network's `discussion.by_network` count for one network (`discussion`
+always counts the whole pool). A cursor whose build is gone answers `status: 'expired'`: start again from the first page.
+
 `sdk.discovery.recommendations({ kind, category?, limit?, session?, exclude? })` is
 the app's one recommender for suggestion rails: `kind` is `member`, `group`, `tag`,
 `network_account` or `story`, and `category` is `all` or a browse category id. It

package/dist/index.d.ts

@@ -158,7 +158,7 @@ export { UsersResource } from './resources/users.js';
 export { CommunitiesResource } from './resources/communities.js';
 export { ChatResource } from './resources/chat.js';
 export { E2eeResource } from './resources/e2ee.js';
-export type { E2eeAccountReset, E2eeDevice, E2eeDevicesRealtimeEvent, E2eeEnvelope, E2eeEvent, E2eeHasDependentsDetails, E2eeKeyPackageStatus, E2eeLink, E2eeLinkCancelledBy, E2eeLinkProgress, E2eeLinkRealtimeEvent, E2eeLinkState, E2eeObjectDownload, E2eeObjectUpload, E2eeRealtimeEvent, E2eeResetCodeSent, E2eeResetErrorCode, E2eeRevokeResponse, E2eeStatus, E2eeStatusReason, } from './resources/e2ee.js';
+export type { E2eeAccountReset, E2eeDevice, E2eeDevicesRealtimeEvent, E2eeEnvelope, E2eeEvent, E2eeHasDependentsDetails, E2eeKeyPackageStatus, E2eeLink, E2eeLinkCancelledBy, E2eeLinkProgress, E2eeLinkRealtimeEvent, E2eeLinkState, E2eeObjectDownload, E2eeObjectUpload, E2eeRealtimeEvent, E2eeResetCodeSent, E2eeResetErrorCode, E2eeRevokeResponse, E2eeStartRequest, E2eeStatus, E2eeStatusReason, } from './resources/e2ee.js';
 export { ProjectsResource } from './resources/projects.js';
 export { AgentsResource, SUPPORTED_MODELS } from './resources/agents.js';
 export { EvidenceResource } from './resources/evidence.js';
@@ -195,7 +195,8 @@ 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, CuratorTodayParams, CuratorTodayRadar, CuratorTodayReaction, CuratorTodayResponse, CuratorTodaySource, CuratorTodayStory, ForYouMeta, ForYouParams, ForYouSurface, ForYouWorldBlock, ForYouWorldBlockType, ForYouWorldCategoryShortcut, ForYouWorldItem, ForYouWorldMeta, ForYouWorldParams, ForYouWorldPart, ForYouWorldResponse, ForYouWorldStory, ForYouWorldStoryTarget, ForYouWorldViral, } from './resources/curator.js';
+export type { CuratorSource, CuratorPrompt, CuratorRunInput, CuratorRunResult, CuratorTodayEdition, CuratorTodayExcerpt, CuratorTodayLeadImage, CuratorTodayParams, CuratorTodayRadar, CuratorTodayReaction, CuratorTodayResponse, CuratorTodaySource, CuratorTodayStory, CuratorTodayDiscussion, CuratorStoryDiscussion, CuratorStoryLaneOutcome, CuratorStoryMindsPost, CuratorStoryPostItem, CuratorStoryPostPagesOptions, CuratorStoryPostsPage, CuratorStoryPostsParams, CuratorStoryReader, CuratorStorySocialPost, CuratorStoryVolumeLanes, CuratorStoryVolumeMeta, StoryPostNetwork, StoryPostPool, StoryPostSort, ForYouMeta, ForYouParams, ForYouSurface, ForYouWorldBlock, ForYouWorldBlockType, ForYouWorldCategoryShortcut, ForYouWorldItem, ForYouWorldMeta, ForYouWorldParams, ForYouWorldPart, ForYouWorldResponse, ForYouWorldStory, ForYouWorldStoryTarget, ForYouWorldViral, } from './resources/curator.js';
+export { STORY_POOL_MAX_POSTS, STORY_POST_NETWORKS, STORY_POSTS_PAGE_MAX } 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';

package/dist/index.js

@@ -253,6 +253,7 @@ export { JobsResource } from './resources/jobs.js';
 export { CuratorResource } from './resources/curator.js';
 export { VideoResource } from './resources/video.js';
 export { AppSubscriptionsResource } from './resources/app-subscriptions.js';
+export { STORY_POOL_MAX_POSTS, STORY_POST_NETWORKS, STORY_POSTS_PAGE_MAX } from './resources/curator.js';
 export { ReportsResource } from './resources/reports.js';
 export { ModerationResource } from './resources/moderation.js';
 export { LinkPreviewResource } from './resources/link-preview.js';

package/dist/realtime.d.ts

@@ -14,6 +14,8 @@ export interface ChatMessageEvent {
         isAi?: boolean;
     };
     createdAt: string;
+    /** The message's metadata as stored; `kind: 'e2ee_start_request'` is an encryption request (MessageMetadata). */
+    metadata?: Record<string, unknown>;
 }
 export interface ChatMessageEditEvent {
     id: string;
@@ -163,11 +165,18 @@ export declare class RealtimeClient {
     onAgentThinking(callback: (event: AgentThinkingEvent) => void): (() => void) | undefined;
     /**
      * A private group's people changed (0.7.59): `{ conversationId, change, userIds, actorId }`,
-     * change `added`, `removed`, `left` or `invites_cancelled`. Sent to everyone in the group
-     * and to the people it is about. Read the conversation again; in an encrypted group, check its keys.
+     * change `added`, `accepted`, `removed`, `left` or `invites_cancelled`, sent to everyone in the group
+     * and to the people it is about; or `device` (a member's device can be added to the encrypted group
+     * now), sent to the group's admin only, on a connection that may read encrypted chat for the group.
+     * Read the conversation again; in an encrypted group, check its keys.
      */
     onChatMembers(callback: (event: ChatMembersEvent) => void): () => void;
-    /** A private group was renamed (0.7.59): `{ conversationId, change: 'renamed', name, actorId }`. */
+    /**
+     * A conversation changed: a private group was renamed (0.7.59,
+     * `{ conversationId, change: 'renamed', name, actorId }`), or someone
+     * withdrew their request to encrypt a one-on-one chat
+     * (`encryption_request_withdrawn`, with `actorId`). Read it again.
+     */
     onChatConversation(callback: (event: ChatConversationEvent) => void): () => void;
     /**
      * The E2EE doorbell after each append to an encrypted conversation this

package/dist/realtime.js

@@ -429,13 +429,20 @@ export class RealtimeClient {
     }
     /**
      * A private group's people changed (0.7.59): `{ conversationId, change, userIds, actorId }`,
-     * change `added`, `removed`, `left` or `invites_cancelled`. Sent to everyone in the group
-     * and to the people it is about. Read the conversation again; in an encrypted group, check its keys.
+     * change `added`, `accepted`, `removed`, `left` or `invites_cancelled`, sent to everyone in the group
+     * and to the people it is about; or `device` (a member's device can be added to the encrypted group
+     * now), sent to the group's admin only, on a connection that may read encrypted chat for the group.
+     * Read the conversation again; in an encrypted group, check its keys.
      */
     onChatMembers(callback) {
         return this.on('chat:members', callback);
     }
-    /** A private group was renamed (0.7.59): `{ conversationId, change: 'renamed', name, actorId }`. */
+    /**
+     * A conversation changed: a private group was renamed (0.7.59,
+     * `{ conversationId, change: 'renamed', name, actorId }`), or someone
+     * withdrew their request to encrypt a one-on-one chat
+     * (`encryption_request_withdrawn`, with `actorId`). Read it again.
+     */
     onChatConversation(callback) {
         return this.on('chat:conversation', callback);
     }

package/dist/resources/chat.d.ts

@@ -93,7 +93,10 @@ export declare class ChatResource {
      * only stops listening for live events.
      */
     leave(conversationId: string): Promise<SingleResponse<LeaveConversationResult>>;
-    /** Accept a message request (`request_status: 'pending'`). Idempotent; also reverses a decline. */
+    /**
+     * Accept a message request (`request_status: 'pending'`). Idempotent; also reverses a decline. In a
+     * private group, everyone in it gets the realtime `chat:members` event (`accepted`); a repeat sends none.
+     */
     acceptRequest(conversationId: string): Promise<SingleResponse<ConversationRequestResult>>;
     /**
      * Decline a message request. The conversation leaves the caller's lists and

package/dist/resources/chat.js

@@ -108,7 +108,10 @@ export class ChatResource {
     leave(conversationId) {
         return this.client.post(`/chat/conversations/${conversationId}/leave`);
     }
-    /** Accept a message request (`request_status: 'pending'`). Idempotent; also reverses a decline. */
+    /**
+     * Accept a message request (`request_status: 'pending'`). Idempotent; also reverses a decline. In a
+     * private group, everyone in it gets the realtime `chat:members` event (`accepted`); a repeat sends none.
+     */
     acceptRequest(conversationId) {
         return this.client.post(`/chat/conversations/${conversationId}/accept`);
     }

package/dist/resources/curator.d.ts

@@ -1,6 +1,7 @@
 import type { HttpClient } from '../client.js';
 import type { CompassFilterMeta, DiscoveryLayout, PaginatedResponse, PaginationMeta, Post, SingleResponse } from '../types.js';
 import type { FeedTopNetworkCard, FeedTopTarget } from './feeds.js';
+import type { SocialPost } from './protocols.js';
 /** Which surface is asking: Home's For You (default) or Discover's For you. */
 export type ForYouSurface = 'home' | 'discover';
 export type ForYouParams = {
@@ -102,6 +103,8 @@ export interface ForYouWorldItem {
             rate: number;
         };
     };
+    /** An open-network post's card (no URL on its network): draw the post from it. Null for a Minds post, read by id. Every open-network item carries one. */
+    card: FeedTopNetworkCard | null;
 }
 /** 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 {
@@ -375,6 +378,18 @@ export interface CuratorTodayStory {
     lead_image?: CuratorTodayLeadImage | null;
     /** World stories only: the radar cluster the story seeded, or null. */
     radar?: CuratorTodayRadar | null;
+    /**
+     * World Story Volume (servers with it on): the story's stable key, which survives the edition's regenerations. Its
+     * posts page is `curator.storyPosts({ storyKey })`. Absent on a Minds story, on a world story the builder has not
+     * indexed, and on every story of a server without it.
+     */
+    story_key?: string;
+    /**
+     * World Story Volume: how many posts discuss the story across Minds, Bluesky, the Fediverse and Nostr, and up to two
+     * of its open-network posts. Present only when the reader's pool holds a post (never `{ total: 0 }`). `posts` stays
+     * the Minds previews it was. Absent: show the story as before.
+     */
+    discussion?: CuratorTodayDiscussion;
 }
 export interface CuratorTodayEdition {
     id: string;
@@ -393,6 +408,8 @@ export interface CuratorTodayResponse {
     meta: {
         generating: boolean;
         compass_filter?: CompassFilterMeta;
+        /** World Story Volume: how the story pools stand for this app. Absent on a server without it, or with it off. */
+        story_volume?: CuratorStoryVolumeMeta;
     };
 }
 export interface CuratorTodayParams {
@@ -402,6 +419,124 @@ export interface CuratorTodayParams {
      */
     compass?: string;
 }
+/** The networks a story's discussion counts posts on. A mirrored `name@host` Minds account counts as `activitypub`. */
+export declare const STORY_POST_NETWORKS: readonly ["minds", "bluesky", "activitypub", "nostr"];
+export type StoryPostNetwork = (typeof STORY_POST_NETWORKS)[number];
+/** `safe`: posts a cached verdict clears (visitors, and members until their content-filter tiers ship); `open`: words of the rest too. */
+export type StoryPostPool = 'safe' | 'open';
+export type StoryPostSort = 'top' | 'latest';
+/** Posts a story page holds at most (`limit`, the default too). */
+export declare const STORY_POSTS_PAGE_MAX = 25;
+/** Posts a story's pool holds at most; a pool that reaches it is `capped` (shown as "1,000+"). */
+export declare const STORY_POOL_MAX_POSTS = 1000;
+/** A story's pool counts: what a card shows ("312 posts · Bluesky 248 · Nostr 31 · Minds 24 · Fediverse 9"). */
+export interface CuratorStoryDiscussion {
+    /** Posts in the reader's pool. */
+    total: number;
+    /** Distinct authors among them. */
+    people: number;
+    by_network: Record<StoryPostNetwork, number>;
+    pool: StoryPostPool;
+    /** The pool reached STORY_POOL_MAX_POSTS: show "1,000+". */
+    capped: boolean;
+    /** ISO time the pool was built (every ten minutes). */
+    built_at: string;
+}
+/** The discussion a world story carries on `curator.today()`. */
+export interface CuratorTodayDiscussion extends CuratorStoryDiscussion {
+    /** Up to two of the pool's open-network posts, as the reader may see them (none when they could not be read in time). */
+    previews: CuratorStoryPostItem[];
+}
+/** A Minds post discussing the story, in the shape `curator.today()` serves its `posts`. */
+export interface CuratorStoryMindsPost {
+    /** JSON `["minds", id]`. */
+    key: string;
+    kind: 'minds';
+    /** Where the author is from: a mirrored `name@host` Minds account counts as `activitypub`. */
+    network: StoryPostNetwork;
+    post: Post;
+    /** No verdict clears the post (the `open` pool only): its words are served, never its media. */
+    text_only?: true;
+}
+/** An open-network post discussing the story. Open it inside the app; never link out to its network. */
+export interface CuratorStorySocialPost {
+    /** JSON `[protocol, nativeId]`. */
+    key: string;
+    kind: 'social';
+    network: StoryPostNetwork;
+    post: SocialPost;
+    /** No verdict clears the post (the `open` pool only): its words are served, never its media. */
+    text_only?: true;
+}
+/** One post on a story page, or a preview on a card: narrow on `kind`. */
+export type CuratorStoryPostItem = CuratorStoryMindsPost | CuratorStorySocialPost;
+/** `meta.story_volume` on `curator.today()`. */
+export interface CuratorStoryVolumeMeta {
+    /** `building`: no build yet (or the last expired); `unavailable`: the counts could not be read. */
+    status: 'ok' | 'building' | 'unavailable';
+    pool: StoryPostPool;
+    built_at: string | null;
+    /** False for the minutes after a regeneration, while stories the builder has not read yet carry no key. */
+    edition_current: boolean;
+    /** World stories indexed, those whose reader's pool holds a post, and those whose build lost an input. */
+    stories: number;
+    pooled: number;
+    degraded: number;
+}
+/** What one lane of a story's build did: counts only. */
+export interface CuratorStoryLaneOutcome {
+    state: 'ok' | 'empty' | 'failed' | 'off';
+    items: number;
+}
+export interface CuratorStoryVolumeLanes {
+    minds: CuratorStoryLaneOutcome;
+    source_index: CuratorStoryLaneOutcome;
+    attach: CuratorStoryLaneOutcome;
+}
+export interface CuratorStoryPostsParams {
+    /** The story's `story_key` from `curator.today()` (a UUID). */
+    storyKey: string;
+    /** One network's posts, or `all` (default). */
+    network?: 'all' | StoryPostNetwork;
+    /** `top` (default): the pool's rank; `latest`: newest first. */
+    sort?: StoryPostSort;
+    /** The previous page's `cursor`, unchanged. It is bound to its network and sort (and build), not to `limit`. */
+    cursor?: string;
+    /** 1 to STORY_POSTS_PAGE_MAX (default 25). */
+    limit?: number;
+}
+/** One page of a story's posts. */
+export interface CuratorStoryPostsPage {
+    /** `expired`: the build the cursor walks is gone (kept 30 minutes); the list ends here: start again from the first page. */
+    status: 'ok' | 'expired';
+    story_key: string;
+    pool: StoryPostPool;
+    network: 'all' | StoryPostNetwork;
+    sort: StoryPostSort;
+    items: CuratorStoryPostItem[];
+    /** The next page's cursor; null on the last page. */
+    cursor: string | null;
+    exhausted: boolean;
+    /** Places on this page whose post was not listed (removed or edited out since the build, or hidden by the member's own filters): never replaced. */
+    withheld: number;
+    /** The pool's posts this network filter covers: what walking every page lists, less `withheld`. */
+    matched: number;
+    /** The reader's pool's counts, as `curator.today()` carries them (without previews); null when the pool is empty. */
+    discussion: CuratorStoryDiscussion | null;
+    built_at: string;
+    /** A lane failed or the cached verdicts could not be read during the build: the pool may be smaller than the story's discussion. */
+    degraded: boolean;
+    lanes: CuratorStoryVolumeLanes;
+}
+/** Who reads a story page: a visitor (`storyPosts`, the default) or the signed-in member (`memberStoryPosts`). */
+export type CuratorStoryReader = 'visitor' | 'member';
+export interface CuratorStoryPostPagesOptions {
+    reader?: CuratorStoryReader;
+    /** Stop after this many pages. Default: as many as a capped pool can fill at this `limit`. */
+    maxPages?: number;
+    /** `false` asks each page once (no retry on a 5xx or 429), as `posts.list` takes it. */
+    retry?: boolean;
+}
 export declare class CuratorResource {
     private client;
     constructor(client: HttpClient);
@@ -411,6 +546,39 @@ export declare class CuratorResource {
      * conversation stories follow. Requires `posts:read`.
      */
     today(params?: CuratorTodayParams): Promise<CuratorTodayResponse>;
+    /**
+     * One page of the posts discussing a World Today story across Minds, Bluesky, the Fediverse and Nostr, as a visitor
+     * reads them (the safe pool, floored again on every page). Works keyless: build the client with
+     * `new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false })`, since `anonymous` alone still sends
+     * `RECURSIV_API_KEY` when the process has one (a shared cache may hold the keyless answer for a minute). With a key it
+     * is that app's visitor answer, never cached. For a signed-in member use `memberStoryPosts`. Throws ValidationError
+     * (no request) for a key that is not a story key; the server answers 404 while it does not serve story volume and for
+     * a story with no pool, and 503 (retry shortly) when it cannot floor the page.
+     */
+    storyPosts(params: CuratorStoryPostsParams, options?: {
+        retry?: boolean;
+    }): Promise<SingleResponse<CuratorStoryPostsPage>>;
+    /**
+     * `storyPosts` for the signed-in member under the app's own key (`users:read` and `posts:read`): their own blocks,
+     * mutes and hidden posts leave each page (counted in `withheld`). Never cached.
+     */
+    memberStoryPosts(params: CuratorStoryPostsParams, options?: {
+        retry?: boolean;
+    }): Promise<SingleResponse<CuratorStoryPostsPage>>;
+    /**
+     * Walk a story's pages from `params.cursor` (or the first page), yielding each page: the walk keeps one network and
+     * sort, and ends on the last page, on an `expired` page (yielded, so the reader can start again) or at `maxPages`.
+     * Over a walk to the last page, `items.length + withheld` sums to the page's `matched`: `discussion.total` for
+     * network `all`, and that network's `discussion.by_network` count for one network (`discussion` is the whole pool's).
+     * Throws ValidationError (no request) for a bad story key, a `limit` outside 1 to STORY_POSTS_PAGE_MAX, or a
+     * `maxPages` that is not a whole number of at least 1 (`Infinity` walks to the last page).
+     *
+     * ```ts
+     * for await (const page of sdk.curator.storyPostPages({ storyKey, network: 'bluesky' })) render(page.items)
+     * ```
+     */
+    storyPostPages(params: CuratorStoryPostsParams, options?: CuratorStoryPostPagesOptions): AsyncGenerator<CuratorStoryPostsPage, void, undefined>;
+    private readStoryPosts;
     /**
      * Fetch the supplied sources in parallel, annotate each top item with
      * the supplied prompt template, and insert audience-scoped posts into

package/dist/resources/curator.js

@@ -1,3 +1,38 @@
+import { ValidationError } from '../errors.js';
+// ── World Story Volume: a World Today story's discussion across networks ──
+//
+// GET /curator/today gives each world story the builder indexed a `story_key` and, when the reader's pool holds a post,
+// a `discussion`. The posts behind the count are paged by `storyPosts` (keyless: a signed-out visitor, or a key's app
+// as a visitor reads it) and `memberStoryPosts` (the signed-in member's own blocks, mutes and hidden posts applied).
+// Walking every page lists exactly the page's `matched`, less each page's `withheld`: `discussion.total` for network
+// `all`, that network's `discussion.by_network` count for one network (`discussion` counts the whole pool on every page).
+/** The networks a story's discussion counts posts on. A mirrored `name@host` Minds account counts as `activitypub`. */
+export const STORY_POST_NETWORKS = Object.freeze(['minds', 'bluesky', 'activitypub', 'nostr']);
+/** Posts a story page holds at most (`limit`, the default too). */
+export const STORY_POSTS_PAGE_MAX = 25;
+/** Posts a story's pool holds at most; a pool that reaches it is `capped` (shown as "1,000+"). */
+export const STORY_POOL_MAX_POSTS = 1000;
+/** Story keys are UUIDs; anything else never reaches a path. */
+const STORY_KEY = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function storyPostsPath(reader, storyKey) {
+    if (typeof storyKey !== 'string' || !STORY_KEY.test(storyKey)) {
+        throw new ValidationError({ type: 'validation_error', code: 'invalid_story_key', message: "Pass a world story's story_key from curator.today()." });
+    }
+    return reader === 'member' ? `/protocols/social/stories/${storyKey}/posts` : `/curator/today/stories/${storyKey}/posts`;
+}
+/** Only the four fields the story page reads: the server's query is strict, and a caller's extras never reach it. */
+function storyPostsQuery(params) {
+    const query = {};
+    if (params.network !== undefined)
+        query.network = params.network;
+    if (params.sort !== undefined)
+        query.sort = params.sort;
+    if (params.cursor !== undefined)
+        query.cursor = params.cursor;
+    if (params.limit !== undefined)
+        query.limit = params.limit;
+    return query;
+}
 export class CuratorResource {
     client;
     constructor(client) {
@@ -11,6 +46,67 @@ export class CuratorResource {
     today(params = {}) {
         return params.compass ? this.client.get('/curator/today', { compass: params.compass }) : this.client.get('/curator/today');
     }
+    /**
+     * One page of the posts discussing a World Today story across Minds, Bluesky, the Fediverse and Nostr, as a visitor
+     * reads them (the safe pool, floored again on every page). Works keyless: build the client with
+     * `new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false })`, since `anonymous` alone still sends
+     * `RECURSIV_API_KEY` when the process has one (a shared cache may hold the keyless answer for a minute). With a key it
+     * is that app's visitor answer, never cached. For a signed-in member use `memberStoryPosts`. Throws ValidationError
+     * (no request) for a key that is not a story key; the server answers 404 while it does not serve story volume and for
+     * a story with no pool, and 503 (retry shortly) when it cannot floor the page.
+     */
+    storyPosts(params, options) {
+        return this.readStoryPosts('visitor', params, options);
+    }
+    /**
+     * `storyPosts` for the signed-in member under the app's own key (`users:read` and `posts:read`): their own blocks,
+     * mutes and hidden posts leave each page (counted in `withheld`). Never cached.
+     */
+    memberStoryPosts(params, options) {
+        return this.readStoryPosts('member', params, options);
+    }
+    /**
+     * Walk a story's pages from `params.cursor` (or the first page), yielding each page: the walk keeps one network and
+     * sort, and ends on the last page, on an `expired` page (yielded, so the reader can start again) or at `maxPages`.
+     * Over a walk to the last page, `items.length + withheld` sums to the page's `matched`: `discussion.total` for
+     * network `all`, and that network's `discussion.by_network` count for one network (`discussion` is the whole pool's).
+     * Throws ValidationError (no request) for a bad story key, a `limit` outside 1 to STORY_POSTS_PAGE_MAX, or a
+     * `maxPages` that is not a whole number of at least 1 (`Infinity` walks to the last page).
+     *
+     * ```ts
+     * for await (const page of sdk.curator.storyPostPages({ storyKey, network: 'bluesky' })) render(page.items)
+     * ```
+     */
+    async *storyPostPages(params, options = {}) {
+        const reader = options.reader ?? 'visitor';
+        storyPostsPath(reader, params.storyKey);
+        // A limit or maxPages the loop cannot count by (NaN, Infinity, 0) would end the walk before its first request and
+        // look like an empty story, so it throws here, before any request, as a bad story key does.
+        const limit = params.limit ?? STORY_POSTS_PAGE_MAX;
+        if (!Number.isInteger(limit) || limit < 1 || limit > STORY_POSTS_PAGE_MAX) {
+            throw new ValidationError({ type: 'validation_error', code: 'invalid_limit', message: `limit must be a whole number from 1 to ${STORY_POSTS_PAGE_MAX}.` });
+        }
+        const maxPages = options.maxPages ?? Math.ceil(STORY_POOL_MAX_POSTS / limit);
+        if (!(maxPages === Number.POSITIVE_INFINITY || (Number.isInteger(maxPages) && maxPages >= 1))) {
+            throw new ValidationError({ type: 'validation_error', code: 'invalid_max_pages', message: 'maxPages must be a whole number of pages, at least 1.' });
+        }
+        const readOptions = options.retry === undefined ? undefined : { retry: options.retry };
+        let cursor = params.cursor;
+        const seen = new Set(cursor ? [cursor] : []);
+        for (let pages = 0; pages < maxPages; pages += 1) {
+            const { data: page } = await this.readStoryPosts(reader, { ...params, cursor }, readOptions);
+            yield page;
+            if (page.status !== 'ok' || page.exhausted || !page.cursor || seen.has(page.cursor))
+                return;
+            seen.add(page.cursor);
+            cursor = page.cursor;
+        }
+    }
+    readStoryPosts(reader, params, options) {
+        const path = storyPostsPath(reader, params.storyKey);
+        const query = storyPostsQuery(params);
+        return options?.retry === undefined ? this.client.get(path, query) : this.client.get(path, query, { retry: options.retry });
+    }
     /**
      * Fetch the supplied sources in parallel, annotate each top item with
      * the supplied prompt template, and insert audience-scoped posts into

package/dist/resources/e2ee.d.ts

@@ -232,6 +232,16 @@ export interface E2eeHasDependentsDetails {
     dependents: string[];
     root: boolean;
 }
+/**
+ * A live "Encrypt this chat" request (`e2ee.requestStart`): the message that
+ * carries it in the chat, and when it was made, by the relay's clock.
+ */
+export interface E2eeStartRequest {
+    message_id: string;
+    requested_at: string;
+    /** False when this request was live already, so nothing was sent. Absent from older relays. */
+    created?: boolean;
+}
 /** `revokeDevice`'s answer: the device, and every device the call revoked (the target first). */
 export interface E2eeRevokeResponse extends SingleResponse<E2eeDevice> {
     /** Absent on relays before 0.7.58. Empty when the device was already revoked and nothing else was. */
@@ -467,6 +477,37 @@ export declare class E2eeResource {
         device_id?: string;
         reason?: 'cancelled' | 'declined';
     }): Promise<SingleResponse<E2eeLink>>;
+    /**
+     * "Encrypt this chat" when the other person has no encrypted-chat device
+     * yet. The relay writes the request into the chat as a message from this
+     * account, with `metadata: { kind: 'e2ee_start_request', v: 1 }` (see
+     * `Message.metadata`), so it reaches the other person as a message does:
+     * their open chat, chat list and unread count, and one push, "<name> wants
+     * to encrypt your chat" (at most one a day per chat). Their device then
+     * starts the encryption as usual, with this account's devices. So this
+     * account needs an active device first (`no_root`, 409, otherwise).
+     *
+     * Answers this account's live request, `{ message_id, requested_at,
+     * created }`; asking again changes nothing and sends nothing (`created`
+     * false). The other person's app finds live requests in
+     * `chat.conversation()`'s `encryption_requests`. Refused where encryption
+     * cannot start: `conversation_not_eligible` (409), `blocked` (403),
+     * `forbidden` (403: not a member this key reaches); `conflict` (409) when
+     * the chat is already encrypted; `request_limit` (409, with
+     * `details.retryAfterSeconds`) after three requests in a day in this chat.
+     * Relays without it answer 404.
+     */
+    requestStart(conversationId: string): Promise<SingleResponse<E2eeStartRequest>>;
+    /**
+     * Withdraw this account's request to encrypt the chat: `{ cancelled }`,
+     * false when none of its requests was live (answered by a start, or
+     * withdrawn already). The request leaves the chat's history; open chats get
+     * `chat_message_delete`, and both people's sockets `chat:conversation`
+     * `encryption_request_withdrawn`. Relays without it answer 404.
+     */
+    cancelStartRequest(conversationId: string): Promise<SingleResponse<{
+        cancelled: boolean;
+    }>>;
     /**
      * The ids of the encrypted conversations this account belongs to, in this
      * key's scope, ordered by id: pass `next` as `after` for the next page

package/dist/resources/e2ee.js

@@ -178,6 +178,39 @@ export class E2eeResource {
     cancelLink(id, input) {
         return this.client.post(`/e2ee/links/${encodeURIComponent(id)}/cancel`, input ?? {});
     }
+    /**
+     * "Encrypt this chat" when the other person has no encrypted-chat device
+     * yet. The relay writes the request into the chat as a message from this
+     * account, with `metadata: { kind: 'e2ee_start_request', v: 1 }` (see
+     * `Message.metadata`), so it reaches the other person as a message does:
+     * their open chat, chat list and unread count, and one push, "<name> wants
+     * to encrypt your chat" (at most one a day per chat). Their device then
+     * starts the encryption as usual, with this account's devices. So this
+     * account needs an active device first (`no_root`, 409, otherwise).
+     *
+     * Answers this account's live request, `{ message_id, requested_at,
+     * created }`; asking again changes nothing and sends nothing (`created`
+     * false). The other person's app finds live requests in
+     * `chat.conversation()`'s `encryption_requests`. Refused where encryption
+     * cannot start: `conversation_not_eligible` (409), `blocked` (403),
+     * `forbidden` (403: not a member this key reaches); `conflict` (409) when
+     * the chat is already encrypted; `request_limit` (409, with
+     * `details.retryAfterSeconds`) after three requests in a day in this chat.
+     * Relays without it answer 404.
+     */
+    requestStart(conversationId) {
+        return this.client.put(`/e2ee/conversations/${encodeURIComponent(conversationId)}/start-request`, {});
+    }
+    /**
+     * Withdraw this account's request to encrypt the chat: `{ cancelled }`,
+     * false when none of its requests was live (answered by a start, or
+     * withdrawn already). The request leaves the chat's history; open chats get
+     * `chat_message_delete`, and both people's sockets `chat:conversation`
+     * `encryption_request_withdrawn`. Relays without it answer 404.
+     */
+    cancelStartRequest(conversationId) {
+        return this.client.delete(`/e2ee/conversations/${encodeURIComponent(conversationId)}/start-request`);
+    }
     /**
      * The ids of the encrypted conversations this account belongs to, in this
      * key's scope, ordered by id: pass `next` as `after` for the next page

package/dist/resources/posts.d.ts

@@ -64,7 +64,8 @@ export declare class PostsResource {
     delete(id: string): Promise<DeleteResponse>;
     /**
      * 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
+     * the promotion safety floor; `sort: 'new'` lists newest first; `media: 'video'` keeps only posts with a
+     * video that plays (a Watch feed of the matches, relevance only). Page with `meta.next_cursor` as
      * `cursor`; the first relevance page carries `latest`, the last page `fall_over` (SearchPostsResponse).
      */
     search(params: SearchPostsParams): Promise<SearchPostsResponse>;

package/dist/resources/posts.js

@@ -66,7 +66,8 @@ export class PostsResource {
     }
     /**
      * 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
+     * the promotion safety floor; `sort: 'new'` lists newest first; `media: 'video'` keeps only posts with a
+     * video that plays (a Watch feed of the matches, relevance only). Page with `meta.next_cursor` as
      * `cursor`; the first relevance page carries `latest`, the last page `fall_over` (SearchPostsResponse).
      */
     search(params) {

package/dist/types.d.ts

@@ -425,6 +425,13 @@ export interface SearchPostsParams extends PaginationParams {
     tag_ids?: string;
     /** `relevance` (default) or `new` (newest first). */
     sort?: 'relevance' | 'new';
+    /**
+     * `video` (0.7.69): only posts with a video that plays, ranked as the relevance search ranks them, in the page shape Watch
+     * reads (`data`, `meta.next_cursor`, `meta.has_more`), so a player can play a query. A post whose every video cannot
+     * play (a legacy file that is gone, an upload still encoding) is left out; the cursor moves past it, so a page can
+     * be short and still have `next_cursor`. Relevance only: with `sort: 'new'` it answers 400 `invalid_input`.
+     */
+    media?: 'video';
     since?: string;
     until?: string;
     /**
@@ -753,6 +760,25 @@ export interface ConversationDetail {
      * older APIs.
      */
     last_activity_at?: string;
+    /**
+     * The live "Encrypt this chat" requests (`e2ee.requestStart`) that can
+     * still be answered, oldest first, at most one per person, however far
+     * back in the history their messages are. Served by `conversation()` on a
+     * plaintext one-on-one chat only: `[]` when there is none (or the chat is
+     * not accepted by both, or a block stands). A request is listed only while
+     * both people are inside the encryption pilot and its sender has an active
+     * device. Absent on other chats and from older APIs.
+     */
+    encryption_requests?: ConversationEncryptionRequest[];
+}
+/** One entry of `ConversationDetail.encryption_requests`. */
+export interface ConversationEncryptionRequest {
+    /** Who asked. The other person answers by starting encryption as usual, from their own device. */
+    sender_id: string;
+    /** The request's message (`metadata.kind` `e2ee_start_request`). */
+    message_id: string;
+    /** When it was asked, by the relay's clock. */
+    requested_at: string;
 }
 export type ChatMemberRole = 'admin' | 'member';
 /**
@@ -800,21 +826,39 @@ export interface UpdateGroupResult {
  * the conversation again (and, in an encrypted group, check its keys).
  * `actorId` is the admin for `added` and `removed`, and the leaver for `left`
  * and `invites_cancelled` (the invites an encrypted group's admin sent, which
- * went with them).
+ * went with them). `accepted`: the person in `userIds` (and `actorId`)
+ * accepted their invite; everyone in the group is told. `device`: one of that
+ * person's devices can be added to the encrypted group now (it has key
+ * packages after it had none); only the group's admin is told, since only the
+ * admin's device adds someone it invited, and only on a connection that may
+ * read encrypted chat for the group (a session, or a key for the group's app;
+ * never an agent's key). Read `change` defensively: an older API never sends
+ * the last two, and a newer one may add more.
  */
 export interface ChatMembersEvent {
     conversationId: string;
-    change: 'added' | 'removed' | 'left' | 'invites_cancelled';
+    change: 'added' | 'accepted' | 'removed' | 'left' | 'invites_cancelled' | 'device';
     userIds: string[];
     actorId: string;
 }
-/** Realtime `chat:conversation`: a private group was renamed by its admin. */
-export interface ChatConversationEvent {
+/**
+ * Realtime `chat:conversation`. Ids only, except a group's new name:
+ * - `renamed`: a private group was renamed by its admin (`name`).
+ * - `encryption_request_withdrawn`: `actorId` withdrew their request to
+ *   encrypt this one-on-one chat (`e2ee.cancelStartRequest`); it left the
+ *   history. Read the conversation and its messages again.
+ * Treat any other `change` as "read the conversation again".
+ */
+export type ChatConversationEvent = {
     conversationId: string;
     change: 'renamed';
     name: string;
     actorId: string;
-}
+} | {
+    conversationId: string;
+    change: 'encryption_request_withdrawn';
+    actorId: string;
+};
 export interface MessageReaction {
     type: string;
     user_id: string;
@@ -827,6 +871,20 @@ export interface MessageMedia {
     mime_type: string | null;
     file_name: string | null;
 }
+/**
+ * What a message the relay wrote on someone's behalf is, by `kind`. Only such
+ * messages carry it.
+ * - `e2ee_start_request` (`v` 1): the sender asked to turn on end-to-end
+ *   encryption for this one-on-one chat (`e2ee.requestStart`). Show it as
+ *   that request, not as its `content`, which is a fallback for apps that do
+ *   not know the kind. It is live while it is in the history and the chat is
+ *   not encrypted; a withdrawn one leaves the history. The person who did not
+ *   ask answers it by starting encryption as usual, from their own device.
+ */
+export interface MessageMetadata {
+    kind: 'e2ee_start_request';
+    v: number;
+}
 export interface Message {
     id: string;
     content: string;
@@ -835,6 +893,8 @@ export interface Message {
     media: MessageMedia[];
     reactions: MessageReaction[];
     created_at: string;
+    /** Absent on a person's own message, and from older APIs: see MessageMetadata. */
+    metadata?: MessageMetadata;
 }
 export interface SendMessageInput {
     conversation_id: string;
@@ -854,6 +914,8 @@ export interface ChatMessageEvent {
         isAi?: boolean;
     };
     createdAt: string;
+    /** The message's metadata as stored; `kind: 'e2ee_start_request'` is an encryption request (MessageMetadata). */
+    metadata?: Record<string, unknown>;
 }
 export interface ChatMessageEditEvent {
     id: string;

package/llm.md

@@ -522,6 +522,9 @@ await r.e2ee.appendEvent(conversationId, { device_id: device.id, envelope }); //
 await r.e2ee.appendEvent(conversationId, { device_id: device.id, envelope: reaction, silent: true }); // no push, no move up the chat list; every member's doorbell still rings
 const { data: page } = await r.e2ee.events(conversationId, { device_id: device.id, after_seq: 0 });
 await r.e2ee.acknowledge(conversationId, { device_id: device.id, seq: page.headSeq });
+// The other person has no device yet: ask them (0.7.70). The relay writes it into the chat as a message with metadata { kind: 'e2ee_start_request', v: 1 }; their start answers it.
+await r.e2ee.requestStart(conversationId); // → { message_id, requested_at, created }; cancelStartRequest(conversationId) withdraws it
+// The live requests, however far back: (await r.chat.conversation(conversationId)).data.encryption_requests → [{ sender_id, message_id, requested_at }]
 // Doorbell after every append: { conversationId, seq, event? }. `event` (a small application message, as events() returns it) comes only to a socket of the owner's session or an owner key, never an agent-scoped key.
 // The policy is required: policyForConversationType(conversation.type) from @recursiv/e2ee ('direct' or 'group').
 r.realtime.onE2eeEvent(({ conversationId, event }) => (event ? controller.applyPushed(conversationId, event, policy) : controller.sync(conversationId, undefined, policy)));
@@ -623,7 +626,7 @@ Methods: `list`, `get`, `create`, `update`, `delete`, `search`, `replies(id, { l
 
 Feed definitions (types only; no route serves one yet): `FeedDefinition` is `{ v: 1, sources, ranking: { mode, range? }, filters?, exclude? }`, with 1-`FEED_SOURCES_MAX` (50) sources read as one union (`FEED_SOURCE_KINDS`; `FEED_SOURCE_KEY[kind]` names each kind's one field, e.g. `{ kind: 'tag', slug: 'rust' }`, `{ kind: 'account', ref: 'did:plc:…' }`). `filters.politics` stores only `'hide'`; viewer settings, blocks, mutes and compass Mix/Sides never go in a definition. Built-in feeds: `builtinCategoryFeedRef('science')` → `'builtin:category:science'`, plus `'builtin:all'` and `'builtin:for_you'`.
 
-`search` ranks relevance x recency x engagement (recency falls as a power of age: this month outranks years ago) through the promotion safety floor; `sort: 'new'` lists newest first. Page with `meta.next_cursor` as `cursor`: later relevance pages are slices of the ranking the first page kept for ten minutes (nothing skipped or repeated while it lives; after that, the page continues past the last post's score boundary), newest-first pages continue by (created_at, id). A cursor is bound to its search and sort: another search's, or the other sort's, is 400 `invalid_cursor`. The first relevance page carries `latest` (up to three of the newest matches not on the page, one per author, for a Latest strip); the last page carries `fall_over.lanes` (`new`, `open_network`, `tag`): draw a way on, not a wall.
+`search` ranks relevance x recency x engagement (recency falls as a power of age: this month outranks years ago) through the promotion safety floor; `sort: 'new'` lists newest first; `media: 'video'` (0.7.69) keeps only posts with a video that plays (relevance only), in the page shape Watch reads, so a player can play a query. Page with `meta.next_cursor` as `cursor`: later relevance pages are slices of the ranking the first page kept for ten minutes (nothing skipped or repeated while it lives; after that, the page continues past the last post's score boundary), newest-first pages continue by (created_at, id). A cursor is bound to its search and sort: another search's, or the other sort's, is 400 `invalid_cursor`. The first relevance page carries `latest` (up to three of the newest matches not on the page, one per author, for a Latest strip); the last page carries `fall_over.lanes` (`new`, `open_network`, `tag`): draw a way on, not a wall.
 
 ### r.bookmarks — Synced saves (per member, per app)
 
@@ -664,7 +667,7 @@ await r.bookmarks.collections.remove(list.id)
 const head = r.curator.forYouWorld({ part: 'stories', session })                // member's own app key; read the two halves at once
 const page = await r.curator.forYouWorld({ part: 'items', session, snapshot })   // items + blocks; snapshot = a previous meta.snapshot
 // stories: { ref, id, source: today|radar|viral, target, label, kind, breaking, general, theme, counts, reasons, ... }
-// items: { ref, kind, target, position, block: 'top' | 'below', media, topic, reasons, explain }
+// items: { ref, kind, target, position, block: 'top' | 'below', media, topic, reasons, explain, card }  // card: an open-network post's (no URL), null for Minds
 // blocks: [{ id, type: stories|lead_video|clips|posts|people|groups|topics|viral|categories, refs, deferred?, entities?, categories?, viral? }]
 ```
 
@@ -694,6 +697,18 @@ for (const section of answer.order) render(section, answer.sections[section])
 
 `trending` joins when the answer is thin or old, so a search never dead-ends. `top_posts` is floored as `r.posts.search`'s relevance page is; `people` rows carry `followers_count`, `posts_count`, `empty` and `verified` (see `r.profiles.search`). Page further with `r.posts.search`. Needs `posts:read`; `people` needs `users:read`, `groups` `communities:read`; `open_network` and `stories` need `users:read` plus the caller's own app key on its network, `trending` that app key. What the key cannot have is in `omitted` (`scope` / `unavailable`).
 
+### r.curator — World Today and its story pages
+
+```typescript
+const { data: edition } = await r.curator.today()          // keyless works: new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false })
+const story = edition?.stories.find(s => s.discussion)     // story_key + discussion only when the server serves them (0.7.69)
+const { data: page } = await r.curator.storyPosts({ storyKey: story!.story_key!, network: 'bluesky', sort: 'latest' })
+const more = await r.curator.storyPosts({ storyKey: page.story_key, network: 'bluesky', sort: 'latest', cursor: page.cursor! })
+for await (const p of r.curator.storyPostPages({ storyKey: page.story_key }, { reader: 'member' })) render(p.items)
+```
+
+`discussion` = `{ total, people, by_network: { minds, bluesky, activitypub, nostr }, pool, capped, built_at, previews }` (≤2 network previews); absent means show the story as before. `storyPosts` is the visitor view (keyless, cached a minute); `memberStoryPosts` is the member's own view (their blocks, mutes and hidden posts removed; `users:read` + `posts:read`). Items narrow on `kind` (`'minds'` → `Post`, `'social'` → `SocialPost`); `text_only` = words only. A removed post counts in `withheld` and is never replaced, so items + `withheld` over every page = the page's `matched` (`discussion.total` for `network: 'all'`, `discussion.by_network[network]` for one network; `discussion` always counts the whole pool). `status: 'expired'` = the cursor's build is gone: restart from page one. 404 while the server does not serve story volume; a non-UUID key throws `ValidationError` before any request.
+
 ### r.communities
 
 ```typescript

package/package.json

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