@recursiv/sdk 0.7.77 → 0.7.79

package/README.md

@@ -94,6 +94,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | Resource | Key methods |
 |----------|------------|
 | `r.posts` | `create`, `update`, `list`, `get`, `getMany(ids)` (up to 25 posts by id per request, no thread; a `Map` of each id's post or `NotFoundError`; 0.7.77), `liked`, `bookmarked`, `bookmark`, `unbookmark`, `search`, `replies`, `react` |
+| `r.search` | `query` (blended search in sections; a thin answer steps down the search ladder, each item labelled `via`, the answer's `ladder` says how) |
 | `r.bookmarks` | `save`, `unsave`, `posts`, `list`, `keys`, `merge` — the member's saved posts, open-network posts and articles, synced across devices; `collections`: `list`, `create`, `update`, `remove`, `add`, `removeItem`, `items`, `posts` — private named collections of saves (0.7.68, where `network.getConfig()` advertises `capabilities.bookmark_collections`) |
 | `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` |
@@ -120,7 +121,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | `r.moderation` | Moderation actions: `publicLog`, `mine`, `appeal`; staff `apply`, `resolveAppeal`, `list({ target_type?, target_id? })` (one target's recorded actions, newest first, at most 100; none named = the network's latest; 0.7.74) and `reverse(actionId)` (sent once: a repeat answers 404 `action_not_found`; 0.7.74); agent grants `listAgentGrants`, `grantAgent`, `revokeAgent` |
 | `r.dispatcher` | Task queue, claims, signals, outcomes, webhooks |
 | `r.goals` | Org goals with task rollups (group dispatcher tasks) |
-| `r.protocols` | Private Minds safety: `sourceControls` (current enablement and saved choices; filter with `control`, each item may carry a `display` label), `setSourceControl`, `onSourceControlChange`, `reportSource`. Delegated accounts: `nativeSocialAccounts`, `startNativeSocialConnection`, `finishNativeSocialConnection`, `disconnectNativeSocialAccount`. Native follows: `nativeFollowStates` (every connected account's state for one source, one read), `nativeFollowState`, `prepareNativeFollow`, `submitNativeFollow`, `nativeFollowStatus` (native following or pending approval, distinct from a Minds feed subscription; preserve the complete signed Nostr list). Native reposts and undo: `nativeRepostState`, `prepareNativeRepost`, `submitNativeRepost`, `nativeRepostStatus` (public posts, explicit approval, connected account, no uncertain retries). Native likes and unlikes: `nativeLikeState`, `prepareNativeLike`, `submitNativeLike`, `nativeLikeStatus` (connected authority, app enablement and explicit approval; resume pending actions instead of duplicating them). Reviewed replies and optional linked posts: `prepareNativeReply`, `submitNativeReply`, `nativeReplyStatus`, `nativeReplyHistory`, `prepareNativeReplyRemoval`, `removeNativeReply` (require deployed API support and app enablement). Keyless shared post links: `sharedNetworks(projectId)`, `getSharedConversation(projectId, { protocol, post, readRef? })`. Member public reading: `searchPublicPosts` (selected account required for Bluesky/ActivityPub; public Nostr search), `getConnectedSocialConversation` (preserve result readerAccountId/readRef), `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; radar stories: `getPublicRadarStory` (one story by id with its posts; one that left the radar within its minimum lifetime, or within the last half hour, still answers live with `liveUntil` and the story that continues it; one that has left for longer comes with its archived copy and the live story it continues as; the id may be a World Today edition story's, and the answer then names it in `editionStory` under the story's radar id; a story a World Today story seeded carries `volume`, the first page of the posts that story counts across Minds and the open networks, whose `cursor` goes on with `curator.storyPosts` or `curator.memberStoryPosts`), keyless `getSharedRadarStory(projectId, { cluster })` and `getSharedRadarPosts(projectId, { cluster })` (keyless reads carry images and videos only from outlets and members marked `visitorMedia`; signed-in reads keep all media, so a share card uses only those); the Viral read (fastest-moving posts across Bluesky, the Fediverse, Nostr and Minds, each against its own network's pace; 0.7.59): `getPublicViral({ network?, category?, media?: 'video', limit?: 5 | 10 | 20 | 40, cursor?, compass? })` under the member's key and keyless `getSharedViral(projectId, params)` (visitors: `compass` `all` or `hide` only; a visitor's `media: 'video'` read can carry items whose video the server withheld, so filter with the exported `viralItemHasVideo` before a video player; `item.post` narrows on `item.protocol`). `status: 'off'` resolves with no items until the app enables the read, and `getSharedViral` also resolves an older API's 401 `missing_api_key` as off; `getPublicViral` throws every 401 and 403, so a session failure is never read as off; private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. `list` returns bounded adapter `maturity`, `limitations`, and exhaustive `supported`/`planned`/`unsupported` implementation capabilities (not provider health or enablement); settings, candidate refresh/status, search, and read-only quarantined candidate review via `listCandidates` / `getCandidate` |
+| `r.protocols` | Private Minds safety: `sourceControls` (current enablement and saved choices; filter with `control`, each item may carry a `display` label), `setSourceControl`, `onSourceControlChange`, `reportSource`. Delegated accounts: `nativeSocialAccounts`, `startNativeSocialConnection`, `finishNativeSocialConnection`, `disconnectNativeSocialAccount`. Native follows: `nativeFollowStates` (every connected account's state for one source, one read), `nativeFollowState`, `prepareNativeFollow`, `submitNativeFollow`, `nativeFollowStatus` (native following or pending approval, distinct from a Minds feed subscription; preserve the complete signed Nostr list). Native reposts and undo: `nativeRepostState`, `prepareNativeRepost`, `submitNativeRepost`, `nativeRepostStatus` (public posts, explicit approval, connected account, no uncertain retries). Native likes and unlikes: `nativeLikeState`, `prepareNativeLike`, `submitNativeLike`, `nativeLikeStatus` (connected authority, app enablement and explicit approval; resume pending actions instead of duplicating them). Reviewed replies and optional linked posts: `prepareNativeReply`, `submitNativeReply`, `nativeReplyStatus`, `nativeReplyHistory`, `prepareNativeReplyRemoval`, `removeNativeReply` (require deployed API support and app enablement). Keyless shared post links: `sharedNetworks(projectId)`, `getSharedConversation(projectId, { protocol, post, readRef?, replies?: 'none' })` (`replies: 'none'`, 0.7.78: the post alone for a card, with `repliesStatus: 'not_requested'`; `getPublicConversation` and `getConnectedSocialConversation` take it too). Member public reading: `searchPublicPosts` (selected account required for Bluesky/ActivityPub; public Nostr search), `getConnectedSocialConversation` (preserve result readerAccountId/readRef), `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; radar stories: `getPublicRadarStory` (one story by id with its posts; one that left the radar within its minimum lifetime, or within the last half hour, still answers live with `liveUntil` and the story that continues it; one that has left for longer comes with its archived copy and the live story it continues as; the id may be a World Today edition story's, and the answer then names it in `editionStory` under the story's radar id; a story a World Today story seeded carries `volume`, the first page of the posts that story counts across Minds and the open networks, whose `cursor` goes on with `curator.storyPosts` or `curator.memberStoryPosts`), keyless `getSharedRadarStory(projectId, { cluster })` and `getSharedRadarPosts(projectId, { cluster })` (keyless reads carry images and videos only from outlets and members marked `visitorMedia`; signed-in reads keep all media, so a share card uses only those); the Viral read (fastest-moving posts across Bluesky, the Fediverse, Nostr and Minds, each against its own network's pace; 0.7.59): `getPublicViral({ network?, category?, media?: 'video', limit?: 5 | 10 | 20 | 40, cursor?, compass? })` under the member's key and keyless `getSharedViral(projectId, params)` (visitors: `compass` `all` or `hide` only; a visitor's `media: 'video'` read can carry items whose video the server withheld, so filter with the exported `viralItemHasVideo` before a video player; `item.post` narrows on `item.protocol`). `status: 'off'` resolves with no items until the app enables the read, and `getSharedViral` also resolves an older API's 401 `missing_api_key` as off; `getPublicViral` throws every 401 and 403, so a session failure is never read as off; private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. `list` returns bounded adapter `maturity`, `limitations`, and exhaustive `supported`/`planned`/`unsupported` implementation capabilities (not provider health or enablement); settings, candidate refresh/status, search, and read-only quarantined candidate review via `listCandidates` / `getCandidate` |
 
 Full reference: see [llm.md](./llm.md) (ships with this package) or the type definitions in `dist/`.
 
@@ -875,7 +876,9 @@ key with `users:read`; `people` and `groups` need `users:read`). `sdk.discovery.
 is Watch's Minds read: the app's public video posts in hot order, from one list the server shares among every viewer of
 the app and rebuilds about once a minute, each post checked again on every call under the public floors and the viewer's
 blocks and mutes, in the `Post` shape with the viewer's own `user_reaction` and `reposted_by_viewer_id` (page on
-`meta.next_cursor`; a feed session's Minds slot can read it as its `list`). A plain category page
+`meta.next_cursor`; a feed session's Minds slot can read it as its `list`). With no category, about one row in four is
+an open-network clip (0.7.78): `{ kind: 'social', id, post }` (`WatchNetworkClip`, `isWatchNetworkClip(row)`), its `post`
+a `SocialPost` cleared for visitors; a feed session hands it on as a `social` item under the network's own key. A plain category page
 (`posts.list({ category })` with no other filter) reads on past a slice the safety floors
 thinned, up to six reads, until it holds `limit` posts or its candidates end: `meta.scanned`
 is how many it examined (the next offset is `offset + scanned`), and the stage ends on the

package/dist/index.d.ts

@@ -211,7 +211,7 @@ export { ModerationResource } from './resources/moderation.js';
 export type { ModerationTargetType, ModerationActionType, ModerationAppealStatus, ModerationPrinciple, PublicModerationAction, PublicModerationLog, OwnModerationAppeal, OwnModerationAction, OwnModerationLog, ApplyModerationActionInput, ModerationAction, ListModerationActionsParams, RecordedModerationTargetType, AgentModerationMode, AgentModerationGrant, } from './resources/moderation.js';
 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 type { PublicSearchPage, PublicSearchTab, SearchAnswer, SearchGroup, SearchLadder, SearchOmitReason, SearchParams, SearchPerson, SearchPost, SearchRelated, SearchResponse, SearchSection, SearchStage, SearchStory, SearchTopic, SearchVia, } from './resources/search.js';
 export { BOOKMARK_MERGE_MAX_ITEMS, BookmarkCollectionsResource, 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';

package/dist/resources/discovery.d.ts

@@ -60,9 +60,26 @@ export interface WatchVideoPost extends Post {
     reposted_by_viewer_id: string | null;
     media: WatchVideoMedia[];
 }
+/**
+ * An open-network clip in Watch's Everything list (0.7.78): a row of its own kind among the Minds posts, about one place
+ * in four, its `post` the network post as a signed-out visitor's trends read serves it (its video cleared for visitors,
+ * not sensitive, under Hide politics where asked). `id` (`social:<protocol>:<native id>`) is unique in the list and is
+ * never a Minds post id: open it, react to it and share it as the network's post. It has no `media` of its own, so an
+ * app that reads every row as a `Post` finds no clip in it. The discovery session hands it on as a `social` item.
+ */
+export interface WatchNetworkClip {
+    kind: 'social';
+    id: string;
+    post: SocialPost;
+}
+/** Whether a row of `discovery.videos` is an open-network clip rather than a Minds post. */
+export declare function isWatchNetworkClip(row: unknown): row is WatchNetworkClip;
 export interface WatchVideosResponse {
-    /** Public Minds video posts in hot order (with the viewer's own `user_reaction` and `reposted_by_viewer_id`). */
-    data: WatchVideoPost[];
+    /**
+     * Public Minds video posts in hot order (with the viewer's own `user_reaction` and `reposted_by_viewer_id`), and on
+     * a page with no category open-network clips among them (WatchNetworkClip, isWatchNetworkClip).
+     */
+    data: Array<WatchVideoPost | WatchNetworkClip>;
     meta: {
         limit: number;
         /** The position in the list this page started at. */
@@ -78,6 +95,17 @@ export interface WatchVideosResponse {
         reason?: 'no_app';
         /** Present when the request named a filtering `compass`: what the Politics choice did to this page. */
         compass_filter?: CompassFilterMeta;
+        /**
+         * A page with no category (0.7.78): the open-network clips it serves, how many the pool its Politics choice reads
+         * holds (0 when none was read in time: the page is then Minds' own), the video posts the visitor media floor withheld
+         * when the pool was built, and when it was built.
+         */
+        open_network?: {
+            served: number;
+            pool: number;
+            withheld: number;
+            built_at: string | null;
+        };
     };
 }
 /** What GET /discover/recommendations suggests: members, groups, tags, open-network accounts or World Today stories. */

package/dist/resources/discovery.js

@@ -5,6 +5,12 @@ export * from './discovery-first-screen.js';
 export * from './discovery-merge.js';
 export * from './discovery-progressive.js';
 export * from './discovery-safety.js';
+/** Whether a row of `discovery.videos` is an open-network clip rather than a Minds post. */
+export function isWatchNetworkClip(row) {
+    const value = row;
+    return !!value && value.kind === 'social' && typeof value.id === 'string' && !!value.post && typeof value.post.protocol === 'string'
+        && typeof value.post.nativeId === 'string' && !!value.post.author && Array.isArray(value.post.media);
+}
 export const isDiscoveryPost = (item) => item.kind === 'minds' || item.kind === 'social';
 /** At most this many candidates per recommendation module. */
 export const RECOMMENDATION_MAX_ITEMS = 6;
@@ -452,7 +458,11 @@ export class DiscoveryFeedSession {
                 const fallover = readFalloverSteps(response.meta.fallover);
                 if (fallover)
                     stream.fallover = fallover;
-                const items = response.data.map(post => ({ key: key('minds', post.id), kind: 'minds', post }));
+                // Watch's Everything list carries open-network clips among its Minds posts (WatchNetworkClip): each goes on as the
+                // network's post, under the key the network's own lane gives it, so the two never show it twice.
+                const items = response.data.map((row) => (isWatchNetworkClip(row)
+                    ? { key: key(row.post.protocol, row.post.nativeId), kind: 'social', post: row.post }
+                    : { key: key('minds', row.id), kind: 'minds', post: row }));
                 const read = { layout: response.meta.discovery ?? ordinary, partial: response.meta.category_filter?.status === 'partial',
                     ...(response.meta.compass_filter ? { compass: response.meta.compass_filter } : {}) };
                 if (!this.filtering)

package/dist/resources/protocols.d.ts

@@ -1725,6 +1725,13 @@ export interface SocialConversation {
     replies: SocialPost[];
     coverage: 'public_provider_window';
     limited: boolean;
+    /**
+     * Present only when the post's parents and replies were not read (`ancestors` and `replies` are empty, `limited` is
+     * true): `not_requested` when the caller asked for the post alone (`replies: 'none'`, 0.7.78), `unavailable` when they
+     * could not be read this time (ask again after `retryAfter` seconds).
+     */
+    repliesStatus?: 'unavailable' | 'not_requested';
+    retryAfter?: number;
     /**
      * The member hid this post, or blocks or mutes its author: `focus` is the post, so the app can show it on request,
      * `replies` is empty, and `viewerControls` are the member's controls to undo. Absent otherwise (a post the app's
@@ -1762,11 +1769,16 @@ export declare class ProtocolsResource {
     onSourceControlChange(listener: (change: SocialSourceControlChange) => void): () => void;
     /** Public-only conversation catalog for a configured app. Works with an anonymous client. */
     sharedNetworks(projectId: string): Promise<SingleResponse<SocialNetwork[]>>;
-    /** Keyless public post read with app moderation; no account state or connected write authority. */
+    /**
+     * Keyless public post read with app moderation; no account state or connected write authority. `replies: 'none'`
+     * (0.7.78) reads the post alone, for a card: `repliesStatus: 'not_requested'`, no parents or replies. An API older
+     * than 0.7.78 refuses it with a 400 `invalid_input`.
+     */
     getSharedConversation(projectId: string, params: {
         protocol: string;
         post: string;
         readRef?: string;
+        replies?: 'none';
     }): Promise<SingleResponse<SocialConversation>>;
     /** Public, app-moderated actor identity without member subscription/account state. */
     getSharedProfile(projectId: string, params: {
@@ -1836,12 +1848,16 @@ export declare class ProtocolsResource {
     publicNetworks(): Promise<SingleResponse<SocialNetwork[]>>;
     /** Query the live public network. It does not import users or posts. */
     searchPublicPosts(params: SearchPublicPostsParams): Promise<SingleResponse<SocialPostSearch>>;
-    /** Read public-only conversation content through the current owner's selected account. */
+    /**
+     * Read public-only conversation content through the current owner's selected account. `replies: 'none'` (0.7.78)
+     * reads the post alone, for a card, as getPublicConversation does.
+     */
     getConnectedSocialConversation(params: {
         protocol: 'bluesky' | 'activitypub';
         accountId: string;
         post: string;
         readRef?: string;
+        replies?: 'none';
     }): Promise<SingleResponse<SocialConversation>>;
     /** Search public profiles from a network's configured provider. */
     searchPublicProfiles(params: SearchPublicProfilesParams): Promise<SingleResponse<SocialProfilePage>>;
@@ -1858,11 +1874,17 @@ export declare class ProtocolsResource {
         protocol?: string;
         cursor?: string;
     }): Promise<SingleResponse<SocialFollowingFeed>>;
-    /** Read the selected source post and its bounded public conversation; never publishes or imports it. */
+    /**
+     * Read the selected source post and its bounded public conversation; never publishes or imports it. `replies: 'none'`
+     * (0.7.78) reads the post alone, for a card (a post shared into a chat): no parents or replies are read, the answer
+     * has `repliesStatus: 'not_requested'`, and a Nostr note answers in one relay read instead of a whole thread's. An API
+     * older than 0.7.78 refuses it with a 400 `invalid_input`: read the conversation without it.
+     */
     getPublicConversation(params: {
         protocol: string;
         post: string;
         readRef?: string;
+        replies?: 'none';
     }): Promise<SingleResponse<SocialConversation>>;
     /**
      * Current provider-ranked topics or posts, with explicit source and coverage. Does not ingest content.

package/dist/resources/protocols.js

@@ -106,10 +106,15 @@ export class ProtocolsResource {
     sharedNetworks(projectId) {
         return this.client.get(`/protocols/public/${encodeURIComponent(projectId)}/networks`);
     }
-    /** Keyless public post read with app moderation; no account state or connected write authority. */
+    /**
+     * Keyless public post read with app moderation; no account state or connected write authority. `replies: 'none'`
+     * (0.7.78) reads the post alone, for a card: `repliesStatus: 'not_requested'`, no parents or replies. An API older
+     * than 0.7.78 refuses it with a 400 `invalid_input`.
+     */
     getSharedConversation(projectId, params) {
         return this.client.get(`/protocols/public/${encodeURIComponent(projectId)}/conversation`, {
             protocol: params.protocol, post: params.post, readRef: params.readRef,
+            ...(params.replies !== undefined ? { replies: params.replies } : {}),
         });
     }
     /** Public, app-moderated actor identity without member subscription/account state. */
@@ -184,9 +189,13 @@ export class ProtocolsResource {
         return this.client.get('/protocols/social/post-search', { protocol: params.protocol, query: params.query,
             accountId: params.accountId, limit: params.limit, cursor: params.cursor });
     }
-    /** Read public-only conversation content through the current owner's selected account. */
+    /**
+     * Read public-only conversation content through the current owner's selected account. `replies: 'none'` (0.7.78)
+     * reads the post alone, for a card, as getPublicConversation does.
+     */
     getConnectedSocialConversation(params) {
-        return this.client.get('/protocols/social/connected-conversation', { protocol: params.protocol, accountId: params.accountId, post: params.post, readRef: params.readRef });
+        return this.client.get('/protocols/social/connected-conversation', { protocol: params.protocol, accountId: params.accountId, post: params.post, readRef: params.readRef,
+            ...(params.replies !== undefined ? { replies: params.replies } : {}) });
     }
     /** Search public profiles from a network's configured provider. */
     searchPublicProfiles(params) {
@@ -209,9 +218,15 @@ export class ProtocolsResource {
     getFollowingFeed(params = {}) {
         return this.client.get('/protocols/social/following-feed', { protocol: params.protocol, cursor: params.cursor });
     }
-    /** Read the selected source post and its bounded public conversation; never publishes or imports it. */
+    /**
+     * Read the selected source post and its bounded public conversation; never publishes or imports it. `replies: 'none'`
+     * (0.7.78) reads the post alone, for a card (a post shared into a chat): no parents or replies are read, the answer
+     * has `repliesStatus: 'not_requested'`, and a Nostr note answers in one relay read instead of a whole thread's. An API
+     * older than 0.7.78 refuses it with a 400 `invalid_input`: read the conversation without it.
+     */
     getPublicConversation(params) {
-        return this.client.get('/protocols/social/conversation', { protocol: params.protocol, post: params.post, readRef: params.readRef });
+        return this.client.get('/protocols/social/conversation', { protocol: params.protocol, post: params.post, readRef: params.readRef,
+            ...(params.replies !== undefined ? { replies: params.replies } : {}) });
     }
     /**
      * Current provider-ranked topics or posts, with explicit source and coverage. Does not ingest content.

package/dist/resources/search.d.ts

@@ -6,6 +6,58 @@ export declare const SEARCH_SECTIONS: readonly ["top_posts", "latest_posts", "op
 export type SearchSection = (typeof SEARCH_SECTIONS)[number];
 /** Why a section is absent: out of time, the server was busy, not available for this app, not allowed for this key, or it failed. */
 export type SearchOmitReason = 'timeout' | 'saturated' | 'unavailable' | 'scope' | 'error';
+/**
+ * Where an item of a search came from (the search ladder, server 0.7.79): the words as written, the word a typo meant,
+ * the known words with the rest dropped, and what is popular in the category the words are about or on the app. The
+ * deep rungs (`semantic`, `related_topic`, `open_network`) are named ahead of their servers.
+ */
+export type SearchVia = 'exact' | 'did_you_mean' | 'relaxed' | 'semantic' | 'related_topic' | 'open_network' | 'trending_category' | 'trending';
+/**
+ * The search ladder's account of an answer, so an app labels it honestly: "No exact matches for X" (`exactCount` 0),
+ * "Did you mean Y?" (`didYouMean`), "Showing posts about memes" (`keptTerms`, `droppedTerms`), "Related: Comedy"
+ * (`inferredCategories`), "Popular in Comedy right now". `steps` names the rungs that answered, in order (`['guarded']`
+ * alone: the query gets what is popular and no suggestion). `withheld` and `pending` count posts a visitor's floors held
+ * back. `unavailable` names sections this key cannot read: say so, never fill them.
+ */
+export interface SearchLadder {
+    exactCount: number;
+    didYouMean: string | null;
+    keptTerms: string[];
+    droppedTerms: string[];
+    inferredCategories: Array<{
+        id: string;
+        name: string;
+        via: 'name' | 'seed' | 'alias' | 'emoji';
+    }>;
+    expandedTags: string[];
+    steps: string[];
+    withheld: number;
+    pending: number;
+    unavailable: string[];
+}
+/** A post as a search lists it: `via` says how the ladder found it (absent from servers before 0.7.79). */
+export type SearchPost = Post & {
+    via?: SearchVia;
+};
+/** A visitor's search tabs (tRPC `publicDiscovery.search`, read keyless through the app's public client). */
+export type PublicSearchTab = 'top' | 'latest' | 'people' | 'groups' | 'videos' | 'news' | 'tag';
+/** `fast` answers within about a second; `deep` waits for the reads `fast` left running. */
+export type SearchStage = 'fast' | 'deep';
+/** One page of a visitor's search: every item labelled `via`, never empty while the app has anything popular. */
+export interface PublicSearchPage<T = Record<string, unknown>> {
+    tab: PublicSearchTab;
+    q: string;
+    items: Array<T & {
+        via: SearchVia;
+    }>;
+    ladder: SearchLadder;
+    meta: {
+        limit: number;
+        stage: SearchStage;
+        next_cursor: string | null;
+        has_more: boolean;
+    };
+}
 export interface SearchParams {
     q: string;
     /** Items per section, 1-20 (default 6). */
@@ -70,7 +122,7 @@ export type SearchTopic = {
     name: string;
 };
 export interface SearchStory {
-    /** Radar cluster id: open it with `protocols` radar story reads. */
+    /** Radar story id: open it with `protocols` radar story reads (an `article` opens as a one-article story). */
     id: string;
     label: string;
     kind: 'breaking' | 'viral' | 'story';
@@ -86,8 +138,18 @@ export interface SearchStory {
         width?: number;
         height?: number;
     } | null;
-    /** Where the words were found: the story's headline, or only one of its members'. */
-    matched: 'label' | 'member';
+    /**
+     * Where the words were found: the story's headline, or only its members'. `article` (a server newer than 0.7.74): no
+     * story is about the query, and this is one outlet's article whose headline carries its words. `related` (a server
+     * newer than 0.7.78): neither, and a visitor's search ladder served it as a story about what the words are about.
+     */
+    matched: 'label' | 'member' | 'article' | 'related';
+    /** An `article`'s link and outlet. */
+    article?: {
+        url: string;
+        outlet: string;
+        lane: 'mainstream' | 'independent';
+    };
 }
 export interface SearchRelated {
     categories: Array<{
@@ -108,12 +170,12 @@ export interface SearchAnswer {
     sections: {
         /** Relevance x recency x engagement, through the promotion safety floor. `has_more`: page further with `posts.search`. */
         top_posts?: {
-            items: Post[];
+            items: SearchPost[];
             has_more: boolean;
         };
         /** Newest first, never repeating a top post. `partial`: these are the newest of what was read in time. */
         latest_posts?: {
-            items: Post[];
+            items: SearchPost[];
             partial: boolean;
         };
         open_network?: {
@@ -135,12 +197,13 @@ export interface SearchAnswer {
         /** Categories and topics around the matches. */
         related?: SearchRelated;
         /** Present when the answer is thin or old: what is moving in the nearest category. */
+        /** `category` null with the ladder: what is popular on the app right now. */
         trending?: {
             category: {
                 id: string;
                 name: string;
             } | null;
-            items: Post[];
+            items: SearchPost[];
         };
     };
     /** Answered, non-empty sections in the order to render them. */
@@ -152,6 +215,8 @@ export interface SearchAnswer {
     }>;
     /** Fewer than five matches across Minds and the open networks. */
     few_results: boolean;
+    /** The search ladder's account of the answer (server 0.7.79): present when the server ran the ladder. */
+    ladder?: SearchLadder;
 }
 export interface SearchResponse {
     data: SearchAnswer;

package/llm.md

@@ -703,7 +703,7 @@ for (const section of answer.order) render(section, answer.sections[section])
 // top_posts, latest_posts, open_network, people, groups, topics, stories, related, trending
 ```
 
-`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`); `groups` rows carry `description` (one line) and `last_active_at`, to tell groups of one name apart. 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`).
+`trending` joins when the answer is thin or old, so a search never dead-ends. A thin answer steps down the search ladder (0.7.79): the word a typo meant, the known words with the rest dropped ("wiggly memes" searches "memes"), what is popular in the category the words are about, then on the app. Every item says how in `via` (`SearchVia`) and `answer.ladder` (`SearchLadder`) says what happened: label it honestly ("No exact matches for X", "Did you mean Y?", "Popular in Comedy right now"); `ladder.unavailable` names sections the key cannot read. Visitors read the same ladder keyless through tRPC `publicDiscovery.search` (`PublicSearchPage`). `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`); `groups` rows carry `description` (one line) and `last_active_at`, to tell groups of one name apart. 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
 
@@ -829,10 +829,10 @@ await r.appSubscriptions.changeTier({ tier: 'pro', proration_date: quote.prorati
 - Native follows: `nativeFollowState({ accountId, protocol, nativeId })`, `prepareNativeFollow({ clientMutationId, accountId, protocol, nativeId, action: "follow" | "unfollow" })`, `submitNativeFollow(id, { approve: true, event? })`, `nativeFollowStatus(id)`. Show the acting identity and native following/requested/unfollowed state separately from the Minds feed subscription. Nostr must sign the complete review event without dropping other contacts; stale lists require a fresh review. Keep mutation IDs and reconcile ambiguous outcomes without replay. Requires current follow scopes and API `NATIVE_SOCIAL_FOLLOW_PROJECTS` plus source controls.
 - Native reposts: `nativeRepostState({ accountId, protocol, nativeId })`, `prepareNativeRepost({ clientMutationId, accountId, protocol, nativeId, action: "repost" | "unrepost" })`, `submitNativeRepost(id, { approve: true, event? })`, `nativeRepostStatus(id)`. Requires `NATIVE_SOCIAL_REPOST_PROJECTS`, account capability and explicit approval; Nostr signs the exact review (kind 6 or own kind 5). Unknown attempts only reconcile. Bluesky connections need the new repost scope; ActivityPub uses write:statuses. Native likes: `nativeLikeState({ accountId, protocol, nativeId })`, `prepareNativeLike({ clientMutationId, accountId, protocol, nativeId, action: "like" | "unlike" })`, `submitNativeLike(id, { approve: true, event? })`, and `nativeLikeStatus(id)`. Display the selected account, source and action before approval. Only Nostr supplies `event`: sign the exact public `signing.event` in the review; never transmit a private key. Preserve mutation IDs on ambiguous responses and refresh unknown results instead of resending. Read capabilities before offering actions; old reply-only connections need reconnecting for likes. Nostr results describe the connected relay, not every public relay. The app-specific `NATIVE_SOCIAL_LIKE_PROJECTS` switch and source controls must be enabled on the API.
 - Delegated social accounts: `r.protocols.nativeSocialAccounts()`, `startNativeSocialConnection({ protocol, identifier })`, `finishNativeSocialConnection({ protocol, state, code?, iss?, error? })`, `disconnectNativeSocialAccount(id)`. Example: `const { data } = await r.protocols.startNativeSocialConnection({ protocol: "bluesky", identifier: "alice.bsky.social" })`; open `data.authorizationUrl`, then complete with the same signed-in app user. Never log callback codes, send passwords, or auto-retry OAuth callbacks. Shared replies (off until schema/API deployment and live verification): `prepareNativeReply({ clientMutationId, text, parent: { protocol, nativeId, readRef? }, accountIds, media?, linkedPostAccountIds?, recoverFrom?: { batchId, deliveryIds } })`, `submitNativeReply(id, { approve: true, deliveryIds })`, `nativeReplyStatus(id)`, `nativeReplyHistory({ limit?, cursor? })`, `prepareNativeReplyRemoval(id, { deliveryIds })`, `removeNativeReply(id, { approve: true, removals })`. Review account, destination, `kind`, source, exact `wireText` and every reviewed `media` item with its alt text; connection is not publication approval. `media` takes the same `NativeMediaInput[]` as `prepareNativePost` and needs the account's `publish_media` capability. `linkedPostAccountIds` explicitly selects different-network standalone posts with a source link, never matching threaded replies or a same-network denial fallback. Preserve mutation IDs, show per-destination results and reconcile uncertain attempts without reposting. To review selected unsent or definitively rejected deliveries again, use recoverFrom with a new mutation ID, the same source/accounts and freshly reviewed text; preserve that ID on uncertain preparation. Only saved recoverable destinations qualify, current gates still apply, and replacedBy disables old sends atomically. Never restart unknown, accepted or published deliveries. The new preview still needs explicit approval. Saved delegated drafts/results: `const { data: history } = await r.protocols.nativeReplyHistory({ limit: 20 })`; use its opaque cursor for the next page and `nativeReplyStatus(item.id)` for details. This is a private read, not a write or provider refresh, and includes Nostr results marked type=nostr. Use nativeNostrReplyResult(item.id) to check that recorded event on its relay without signing or resending. Discard page state on owner/app changes. See README for examples and the callback, revocation and removal contracts.
-- `r.protocols` — Private app safety: `sourceControls` returns current `enabled` plus paged saved choices; `setSourceControl`, `onSourceControlChange` and `reportSource` share app scope. Example: `const choices = new Map(); const stop = r.protocols.onSourceControlChange(change => choices.set(JSON.stringify([change.source, change.control]), change.enabled));` then `await r.protocols.setSourceControl({ source: { protocol: "bluesky", kind: "actor", nativeId: "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa" }, control: "mute", enabled: true, scope: "minds" });` and call `stop(); choices.clear()` on account change/unmount. Notifications follow an exact server confirmation, never an uncertain response. These preferences and reports apply in Minds, not on the remote network. Keyless post links: `const visitor = new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false }); const { data: thread } = await visitor.protocols.getSharedConversation(projectId, { protocol: 'nostr', post: publicEventId })`; `sharedNetworks(projectId)` lists public conversation capabilities. Only configured apps; app moderation and rate limits apply, no member state or write authority. Member public reading: `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. Example after selecting a returned source post: `const { data: thread } = await r.protocols.getPublicConversation({ protocol: post.protocol, post: post.nativeId, readRef: post.readRef })`. Render `focus`, oldest-first `ancestors` and direct `replies`; `public_provider_window` never promises every reply, and `limited` marks known omissions. Requires both `users:read` and `posts:read` on the current human app key. Protocol discovery/settings: `const { data: adapters } = await r.protocols.list()` returns bounded `{ id, name, icon, color, maturity, capabilities, limitations }` metadata; `supported` means implemented, not configured, healthy, authorized, or enabled. Methods: `list`, `status`, `listCandidates`, `getCandidate`, `search`, `getSettings`, `refresh`, `updateSettings`.
+- `r.protocols` — Private app safety: `sourceControls` returns current `enabled` plus paged saved choices; `setSourceControl`, `onSourceControlChange` and `reportSource` share app scope. Example: `const choices = new Map(); const stop = r.protocols.onSourceControlChange(change => choices.set(JSON.stringify([change.source, change.control]), change.enabled));` then `await r.protocols.setSourceControl({ source: { protocol: "bluesky", kind: "actor", nativeId: "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa" }, control: "mute", enabled: true, scope: "minds" });` and call `stop(); choices.clear()` on account change/unmount. Notifications follow an exact server confirmation, never an uncertain response. These preferences and reports apply in Minds, not on the remote network. Keyless post links: `const visitor = new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false }); const { data: thread } = await visitor.protocols.getSharedConversation(projectId, { protocol: 'nostr', post: publicEventId })`; `sharedNetworks(projectId)` lists public conversation capabilities. Only configured apps; app moderation and rate limits apply, no member state or write authority. Member public reading: `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. Example after selecting a returned source post: `const { data: thread } = await r.protocols.getPublicConversation({ protocol: post.protocol, post: post.nativeId, readRef: post.readRef })`. Render `focus`, oldest-first `ancestors` and direct `replies`; `public_provider_window` never promises every reply, and `limited` marks known omissions. A card (a post shared into a chat, a link preview) asks for the post alone, 0.7.78: `getPublicConversation({ protocol, post, replies: 'none' })` (also `getSharedConversation` and `getConnectedSocialConversation`) answers `focus` with no `ancestors` or `replies` and `repliesStatus: 'not_requested'`; a Nostr note answers from one relay read instead of a whole thread's. An older API answers 400 `invalid_input`: read without it. Requires both `users:read` and `posts:read` on the current human app key. Protocol discovery/settings: `const { data: adapters } = await r.protocols.list()` returns bounded `{ id, name, icon, color, maturity, capabilities, limitations }` metadata; `supported` means implemented, not configured, healthy, authorized, or enabled. Methods: `list`, `status`, `listCandidates`, `getCandidate`, `search`, `getSettings`, `refresh`, `updateSettings`.
   - Native Nostr: `const { data: preview } = await r.protocols.prepareNativeNostr(identityId, { action: "publish", content: draft })`; review and sign the exact public event, then `submitNativeNostr(identityId, { intent: preview.intent, event, approve: true })`. Preparation/submission never auto-retry. After uncertainty, use `getNativeNostrPost(identityId, preview.postId ?? preview.eventId)` before a user-selected retry of the identical intent/event: deletion checks the original note's `postId`, publication checks `eventId`. Check `nativeNostrAccount()` enablement first; keys stay with the signer. For replies, after `nativeNostrAccount()` advertises `reply_text_note`, use `prepareNativeNostr(identityId, { action: "reply", content: draft, parentId: post.nativeId })`. Review returned parent/root/participants/relay and exact event, sign with the connected client signer, then `submitNativeNostr(identityId, { intent, event, approve: true })`. Requires users:read, posts:read and posts:write. Kind1 public notes only; reply enablement and shared UI/live proof remain pending. Do not inherit arbitrary notification tags or relay hints. Signing mutations never auto-retry; check `getNativeNostrPost(identityId, eventId)` after uncertainty before a user-selected identical-event retry.
   - Hosted Bluesky account on the app's own PDS: `const { data } = await r.protocols.createHostedIdentity({ protocol: 'atproto', handle: 'alice', email })`. Only the label is sent; `data.handle` carries the domain and `data.password` is returned this once, never stored. Never auto-retried. Either the account is finished or it is removed again. 409 `handle_unavailable` = choose another label; 503 `handle_dns_unavailable`/`handle_unresolvable`/`handle_unverified` = operator setup, retry later unchanged.
-  - Anonymous discovery: `const visitor = new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false }); const { data } = await visitor.protocols.getSharedTrends(projectId, { protocol: 'nostr', limit: 20, discovery: true })`. Use `sharedNetworks(projectId)` capabilities; open a returned topic with `getSharedTrendFeed(projectId, { protocol: 'bluesky', topic: trend.nativeId, cursor })`. Configured apps only; no account authority or writes. App moderation and per-IP/app rate limits apply. Categories and Jev layouts reuse cached judgments without initiating paid inference; handle partial categories and finite provider windows. Category depth: `r.posts.list({ category: 'science', sort: 'hot', discovery: true })` pages the hot window by offset and then by keyset (`meta.next` is `{ offset }`, `{ cursor }` or `null`; pass a cursor back as `cursor`); when a stage ends, `meta.fallover` lists the next feeds in order (`category_older`, `category_network`, `category` with `via`, `for_you`, `all`; `feed` with `ref` is declared in 0.7.60 but not sent yet, so skip kinds you cannot open). One call for a category's modules: `const { data } = await r.discovery.category({ category: 'science' })` returns `stories`, `network`, `clips`, `people`, `groups`, each `{ items, ms, reason? }`. Watch's Minds videos: `const { data, meta } = await r.discovery.videos({ limit: 12 })` returns public video posts in hot order from a list shared per app (rebuilt about once a minute), each re-checked per call for the viewer; page on `meta.next_cursor`.
+  - Anonymous discovery: `const visitor = new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false }); const { data } = await visitor.protocols.getSharedTrends(projectId, { protocol: 'nostr', limit: 20, discovery: true })`. Use `sharedNetworks(projectId)` capabilities; open a returned topic with `getSharedTrendFeed(projectId, { protocol: 'bluesky', topic: trend.nativeId, cursor })`. Configured apps only; no account authority or writes. App moderation and per-IP/app rate limits apply. Categories and Jev layouts reuse cached judgments without initiating paid inference; handle partial categories and finite provider windows. Category depth: `r.posts.list({ category: 'science', sort: 'hot', discovery: true })` pages the hot window by offset and then by keyset (`meta.next` is `{ offset }`, `{ cursor }` or `null`; pass a cursor back as `cursor`); when a stage ends, `meta.fallover` lists the next feeds in order (`category_older`, `category_network`, `category` with `via`, `for_you`, `all`; `feed` with `ref` is declared in 0.7.60 but not sent yet, so skip kinds you cannot open). One call for a category's modules: `const { data } = await r.discovery.category({ category: 'science' })` returns `stories`, `network`, `clips`, `people`, `groups`, each `{ items, ms, reason? }`. Watch's Minds videos: `const { data, meta } = await r.discovery.videos({ limit: 12 })` returns public video posts in hot order from a list shared per app (rebuilt about once a minute), each re-checked per call for the viewer; page on `meta.next_cursor`. With no category about one row in four is an open-network clip (0.7.78): `isWatchNetworkClip(row)` tells `{ kind: 'social', id, post: SocialPost }` from a `Post`; open and react to it as the network's post (its `id` is never a Minds id).
   - Progressive Discover feed (0.7.71): `const feed = r.discovery.createProgressiveFeed({ networks, category, recommend, top: { ref: 'builtin:all' }, seen, seenClusters }); const round = await feed.next(part => draw(part))` opens one `createFeed` session per source (Minds with the radar and suggestions, one per network with `public_trends`) and hands each source's page on as a `DiscoveryPart` (`{ source, round, modules, composed?, mixed? }`) the moment it lands, instead of a page that waits for its slowest network (up to 15 s); a round waits `DISCOVERY_STRAGGLER_MS` past its first answer and rejects only when every source failed. The first load is held until Minds and one other network answered (or `FIRST_SCREEN_MS`, 2.5 s, after the first answer; `firstScreenMs: VISITOR_FIRST_SCREEN_MS` for a visitor) and arrives as one `composed: true` part from `composeFirstScreen`: the top's first post when it is a playable video, else a picture lead from the best 8 by engagement (never a story, rail, video strip, column, `isSensitivePost` post or `linksAdultSite` porn link), then every network's posts by engagement (`DiscoveryEngagementMerge`) with row 2 from another network than the lead's when one is left (`FIRST_SCREEN_NETWORK_ROWS`), a story as row 3 and a rail as row 5, nothing dropped. Merge later `mixed` parts with `mergeDiscoveryArrival(rows, arriving, reachedIds)`. `top`/`seen`/`seenClusters`/`bucket` reach every session; the top is read once per open. Also `retryFailed()`, `onStatus(listener)`, `setNetworks(catalog)`; settings `perSource`, `firstScreen`, `onLanded`. For you: `createProgressiveFeed({ createFeed: o => r.discovery.createPersonalFeed(o) }, options, { perSource: false })`. A session's `seen` now also leaves seen network posts out of trend pages, previews and topic pages; in a category a topic page with nothing new ends its topic and after `DISCOVERY_EMPTY_TOPIC_PAGES` (3) in a row the network's other topics are skipped.
   - Viral read (0.7.59; off until the server enables it for the app): `const { data } = await r.protocols.getPublicViral({ media: 'video', category: 'science', limit: 20 })` (member key, users:read + posts:read, never cached) or keyless `visitor.protocols.getSharedViral(projectId, { media: 'video', compass: 'hide' })` (visitors send compass `all` or `hide` only). Params, all optional: `network` (all, minds, bluesky, activitypub, nostr), `category`, `media: 'video'`, `limit` 5/10/20/40, `cursor` (the last page's; a cursor whose 30-minute build expired ends the list), `compass`. Each item: `key` (stable; drop ones already shown), `protocol`, `post` (checking `protocol` narrows it: `ViralMindsCard` for minds, open at /post/:id; otherwise a `SocialPost`), `label` viral/rising/hot, `score`, `rank`, `category`, `velocity` (show counts with `countsReportedBy` as reported, never verified), `spread`. A visitor's read serves media only where the server cleared it, so even with `media: 'video'` some items arrive with the video withheld (empty `media`): `import { viralItemHasVideo } from '@recursiv/sdk'` and keep `data.items.filter(viralItemHasVideo)` before a vertical video player. `status` ok/building/screening/off: off resolves with no items, and `getSharedViral` also resolves an older API's 401 `missing_api_key` as off; `getPublicViral` throws every 401/403 (never off), so catch it and skip that step.
   - Public trends: require `public_trends` from `publicNetworks()`, then `getPublicTrends({ protocol, limit?, cursor?, compass?, media? })` (`compass: 'hide'` leaves out politics, 0.7.62; `media: 'video'`, 0.7.73, Bluesky: the network's own window of video posts, a `kind: posts` page paged by its cursor, no category or layout, 404 `unsupported_protocol` for a network without one, 400 on an API that predates it; keyless `getSharedTrends(projectId, { ..., media: 'video' })` holds only clips a visitor may see and counts the rest in `mediaFilter.withheld`); render `kind: topics` as source topics and `kind: posts` as source posts. With `trend_feed`, open only a returned current topic using `getPublicTrendFeed({ protocol, topic: trend.nativeId, limit?, cursor? })`. Show provider, observedAt and provider_ranked_window coverage; null rankingWindow is unknown, not a daily/global ranking. Preserve source order, canonical IDs and readRef, and opaque cursors. Topic catalogs do not paginate; Mastodon trends stop at 200 source positions. Both methods require users:read plus posts:read on the current human app key; Nostr trends are unsupported. Propagate errors; trend_unavailable means refresh the topic list. No ingestion or native writes.

package/package.json

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