@recursiv/sdk 0.7.78 → 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` |

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/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). */
@@ -88,9 +140,10 @@ export interface SearchStory {
     } | null;
     /**
      * 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.
+     * 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';
+    matched: 'label' | 'member' | 'article' | 'related';
     /** An `article`'s link and outlet. */
     article?: {
         url: string;
@@ -117,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?: {
@@ -144,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. */
@@ -161,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
 

package/package.json

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