@recursiv/sdk 0.7.78 → 0.7.80

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

@@ -66,6 +66,7 @@ import { BookmarksResource } from './resources/bookmarks.js';
 import { FeedsResource } from './resources/feeds.js';
 import { AccountsResource } from './resources/accounts.js';
 import { SignalsResource } from './resources/signals.js';
+import { SealedResource } from './resources/sealed.js';
 import { RealtimeClient } from './realtime.js';
 import type { RecursivConfig } from './types.js';
 export declare class Recursiv {
@@ -141,6 +142,8 @@ export declare class Recursiv {
     readonly accounts: AccountsResource;
     /** The member's engagement signals (views, dwell, hides, "More like this") for their own ranking. */
     readonly signals: SignalsResource;
+    /** Sealed mode's config and transport: routers, models, allowance, and the sealed send (no crypto; flag-gated). */
+    readonly sealed: SealedResource;
     readonly realtime: RealtimeClient;
     constructor(config?: Partial<RecursivConfig>);
     /**
@@ -211,7 +214,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';
@@ -219,6 +222,8 @@ export type { BookmarkCollection, BookmarkCollectionInput, BookmarkCollectionKin
 export { AccountsResource } from './resources/accounts.js';
 export { SIGNAL_BATCH_MAX, SignalsResource } from './resources/signals.js';
 export type { SignalBatchResult, SignalEventInput, SignalEventType, SignalNotRecordedReason, SignalRecordResult, SignalSendOptions, } from './resources/signals.js';
+export { SEALED_ALLOWANCE_REMAINING_HEADER, SEALED_REFUSAL_HEADER, SealedResource, SealedTransportError, } from './resources/sealed.js';
+export type { SealedAllowance, SealedConfig, SealedSendInput, SealedTransportErrorCode } from './resources/sealed.js';
 export type { SiblingAccount, SiblingAccountsResponse, SwitchAccountResult, } from './resources/accounts.js';
 export type { LinkPreview, LinkPreviewResponse, } from './resources/link-preview.js';
 export type { AgentCapabilityConsentRequirement, AgentCapabilityDataSensitivity, AgentCapabilityDomain, AgentCapabilityExportBoundary, AgentCapabilityRetentionClass, AgentCapabilitySubdomain, AgentCapabilitySubject, AgentCapabilityTrustTier, AgentToolAudience, AgentToolScope, BrowserUseRunTaskInput, ProjectBrainSettings, ProjectToolBundleClassification, ProjectToolBundleKey, ProjectToolPermission, ProjectToolPermissionOverrides, UpdateProjectSettingsInput, } from './resources/project-brain.js';

package/dist/index.js

@@ -67,6 +67,7 @@ import { BookmarksResource } from './resources/bookmarks.js';
 import { FeedsResource } from './resources/feeds.js';
 import { AccountsResource } from './resources/accounts.js';
 import { SignalsResource } from './resources/signals.js';
+import { SealedResource } from './resources/sealed.js';
 import { RealtimeClient } from './realtime.js';
 export class Recursiv {
     /** Shared transport, kept so the client name can be set after construction. */
@@ -142,6 +143,8 @@ export class Recursiv {
     accounts;
     /** The member's engagement signals (views, dwell, hides, "More like this") for their own ranking. */
     signals;
+    /** Sealed mode's config and transport: routers, models, allowance, and the sealed send (no crypto; flag-gated). */
+    sealed;
     realtime;
     constructor(config) {
         const client = new HttpClient(config);
@@ -210,6 +213,7 @@ export class Recursiv {
         this.bookmarks = new BookmarksResource(client);
         this.accounts = new AccountsResource(client);
         this.signals = new SignalsResource(client);
+        this.sealed = new SealedResource(client);
         this.realtime = new RealtimeClient(client);
         this.#http = client;
     }
@@ -271,6 +275,7 @@ export { BOOKMARK_MERGE_MAX_ITEMS, BookmarkCollectionsResource, BookmarksResourc
 export { FEED_TOP_NETWORKS, FeedsResource } from './resources/feeds.js';
 export { AccountsResource } from './resources/accounts.js';
 export { SIGNAL_BATCH_MAX, SignalsResource } from './resources/signals.js';
+export { SEALED_ALLOWANCE_REMAINING_HEADER, SEALED_REFUSAL_HEADER, SealedResource, SealedTransportError, } from './resources/sealed.js';
 export { OrganizationSettingsResource } from './resources/organization-settings.js';
 export { ProjectSettingsResource } from './resources/project-settings.js';
 export { OrganizationSecurityResource } from './resources/organization-security.js';

package/dist/resources/discovery-first-screen.js

@@ -1,4 +1,4 @@
-import { DISCOVERY_RAIL_LANE, DISCOVERY_STORY_LANE, DiscoveryEngagementMerge, discoveryLeadable, discoveryModuleLane, discoveryShowsMedia, discoveryTopPlace, isColumnModule, isDiscoveryPostModule, poolDiscoveryGalleries, promotedDiscoveryVideoItems, } from './discovery-merge.js';
+import { DISCOVERY_RAIL_LANE, DISCOVERY_STORY_LANE, DiscoveryEngagementMerge, discoveryLeadable, discoveryModuleEngaged, discoveryModuleLane, discoveryShowsMedia, discoveryTopPlace, isColumnModule, isDiscoveryPostModule, poolDiscoveryGalleries, promotedDiscoveryVideoItems, } from './discovery-merge.js';
 // ──────────────────────────────────────────────────────────────────────────
 // Discover's first screen, composed from every source that answered in time.
 // Ported from the Minds app (lib/firstScreen, 2026-10-04).
@@ -15,7 +15,14 @@ import { DISCOVERY_RAIL_LANE, DISCOVERY_STORY_LANE, DiscoveryEngagementMerge, di
 //    gallery whose first card has one), from the best of the screen by
 //    engagement (FIRST_SCREEN_LEAD_WINDOW). A story, a suggestion rail, a
 //    video strip or a conversation never leads, and neither does a sensitive
-//    Minds post or an open-network post that links a porn site;
+//    Minds post or an open-network post that links a porn site. Nor does a post
+//    with no picture or clip that nobody engaged with, while the screen holds a
+//    post with either: live (Minds, 2026-10-05, 375x812) Gaming opened on an IGN
+//    link with no votes and a text post nobody had engaged with, both under two
+//    hours old, while it held a voted clip. Fresh posts with no engagement score
+//    as half a typical post, so nine of them ahead of a day-old voted clip put it
+//    past the lead's window. Then the best post with media and engagement leads,
+//    else the best with media, else the best with engagement;
 //  - then the posts by engagement, every source's together
 //    (DiscoveryEngagementMerge), with the network mix as a soft constraint. A
 //    column of several posts goes in from FIRST_SCREEN_FEATURE_SLOT on;
@@ -108,12 +115,22 @@ export function composeFirstScreen(parts, { keepLead = false, now = Date.now() }
     const stories = pooled.filter(module => module !== kept && discoveryModuleLane(module) === DISCOVERY_STORY_LANE);
     const rails = pooled.filter(module => module !== kept && discoveryModuleLane(module) === DISCOVERY_RAIL_LANE);
     // The lead: the top's first post when it is a video that can play; else the best post near the top of the screen's
-    // engagement order that opens on a picture or a video; else the best single post; else the best post.
+    // engagement order that opens on a picture or a video; else the best single post; else the best post. That one is
+    // passed over when it has no picture or clip and nobody engaged with it, for the best post with media and engagement,
+    // else with media, else with engagement, wherever it is in the order.
     const best = merge.rest().filter(mayLead);
-    const lead = kept
-        ?? discoveryTopVideoLead(pooled)
+    const quiet = (module) => !moduleOpensOnPicture(module) && !discoveryModuleEngaged(module);
+    // A kept lead, and the top's playable video, lead as they are: the engagement lanes own the top's order.
+    const owned = kept ?? discoveryTopVideoLead(pooled);
+    const pick = owned
         ?? best.slice(0, FIRST_SCREEN_LEAD_WINDOW).find(moduleOpensOnPicture)
         ?? best.find(module => !isColumnModule(module)) ?? best[0];
+    const lead = !owned && pick && quiet(pick)
+        ? best.find(module => moduleOpensOnPicture(module) && discoveryModuleEngaged(module))
+            ?? best.find(moduleOpensOnPicture)
+            ?? best.find(module => !isColumnModule(module) && discoveryModuleEngaged(module))
+            ?? pick
+        : pick;
     const out = [];
     if (lead) {
         merge.remove(lead);

package/dist/resources/discovery-merge.d.ts

@@ -98,6 +98,8 @@ export declare function isColumnModule(module: DiscoveryModule): boolean;
  * as it is stays as it is. `keep`: a module never pooled (a screen's lead).
  */
 export declare function poolDiscoveryGalleries(modules: readonly DiscoveryModule[], now: number, keep?: DiscoveryModule): DiscoveryModule[];
+/** Someone engaged with one of the module's posts: its counts are known and above zero (an unknown count is no engagement). */
+export declare function discoveryModuleEngaged(module: DiscoveryModule): boolean;
 /**
  * A batch of post modules, taken best first under the network mix's soft constraints (the rules above). Each `take`
  * reads the rows above the place it fills, so it fits the rows a feed already shows.
@@ -127,6 +129,16 @@ export declare class DiscoveryEngagementMerge {
         singles?: boolean;
         newNetwork?: boolean;
     }): DiscoveryModule | undefined;
+    /**
+     * The module for the first post row of a feed, or of the feed it turned to below a line. It opens a feed, so the rows
+     * above it (another feed's, or none) set none of take's network-mix rules: after five rows of another feed with no
+     * Minds post, the home network's floor would put this feed's quiet Minds post first. The floor and the mix hold again
+     * from the row under it. The top of the feed's posts lead in their order, as take has them. Otherwise the best post
+     * the reader may be shown first leads, unless it has no picture or clip and nobody engaged with it while the batch
+     * holds a post that has either: then the best post with media and engagement leads, else the best with media, else
+     * the best with engagement. A column never leads while a single post may.
+     */
+    takeLead(): DiscoveryModule | undefined;
 }
 /** Rows that arrive woven in one by one with the rows not seen yet, below the place a reader has reached: for a feed of one source. */
 export declare function weaveDiscoveryArrival<T extends {
@@ -137,7 +149,9 @@ export declare function weaveDiscoveryArrival<T extends {
  * moves: they go after the last row seen (`reached`, by id, and one more for a row only peeking in), never above `floor`;
  * with nothing seen yet, at the end. Below that place the arriving rows and the rows not seen yet are merged: the rows
  * that are not posts (a story, a rail, a row of the client's own) take the places they would have had woven in one by
- * one, and the posts fill the other places by engagement under the network mix (DiscoveryEngagementMerge).
+ * one, and the posts fill the other places by engagement under the network mix (DiscoveryEngagementMerge). The first
+ * post at the top of the feed, or below the line where it turned (`floor`), leads what comes under it (takeLead): never
+ * a post with no picture or clip that nobody engaged with while the batch holds one with either.
  */
 export declare function mergeDiscoveryArrival<T extends {
     id: string;

package/dist/resources/discovery-merge.js

@@ -359,6 +359,21 @@ export function poolDiscoveryGalleries(modules, now, keep) {
     return replaced.size ? modules.flatMap(module => replaced.get(module) ?? [module]) : [...modules];
 }
 const laneOfRow = (row) => (isDiscoveryPostModule(row) ? discoveryModuleLane(row) : null);
+/** A module of posts only, each one the reader may be shown first, never a strip of clips. */
+function mayLeadModule(module) {
+    const presentation = module.presentation;
+    const posts = module.items.filter(isPostItem);
+    return presentation !== 'video' && posts.length > 0 && posts.length === module.items.length && posts.every(discoveryLeadable);
+}
+/** The module opens on a picture or a clip: its first post shows one. */
+function opensOnMedia(module) {
+    const first = module.items[0];
+    return !!first && isPostItem(first) && discoveryShowsMedia(first);
+}
+/** Someone engaged with one of the module's posts: its counts are known and above zero (an unknown count is no engagement). */
+export function discoveryModuleEngaged(module) {
+    return module.items.some(item => isPostItem(item) && (discoveryEngagementPoints(item) ?? 0) > 0);
+}
 /**
  * A batch of post modules, taken best first under the network mix's soft constraints (the rules above). Each `take`
  * reads the rows above the place it fills, so it fits the rows a feed already shows.
@@ -373,7 +388,7 @@ export class DiscoveryEngagementMerge {
         this.left = modules.map((module, index) => {
             const rank = rankDiscoveryModule(module, reference, now) ?? { tier: 1, score: 0 };
             return { module, lane: discoveryModuleLane(module), title: discoveryRowTitle(module), column: isColumnModule(module), top: discoveryTopPlace(module),
-                tier: rank.tier, score: rank.score, order: order ? order(module, index) : index };
+                tier: rank.tier, score: rank.score, order: order ? order(module, index) : index, leads: mayLeadModule(module), media: opensOnMedia(module), engaged: discoveryModuleEngaged(module) };
         }).sort((a, b) => (a.top ?? Number.POSITIVE_INFINITY) - (b.top ?? Number.POSITIVE_INFINITY) || a.tier - b.tier || b.score - a.score || a.order - b.order);
     }
     get size() { return this.left.length; }
@@ -423,6 +438,30 @@ export class DiscoveryEngagementMerge {
             ?? pool[0];
         return pick(chosen);
     }
+    /**
+     * The module for the first post row of a feed, or of the feed it turned to below a line. It opens a feed, so the rows
+     * above it (another feed's, or none) set none of take's network-mix rules: after five rows of another feed with no
+     * Minds post, the home network's floor would put this feed's quiet Minds post first. The floor and the mix hold again
+     * from the row under it. The top of the feed's posts lead in their order, as take has them. Otherwise the best post
+     * the reader may be shown first leads, unless it has no picture or clip and nobody engaged with it while the batch
+     * holds a post that has either: then the best post with media and engagement leads, else the best with media, else
+     * the best with engagement. A column never leads while a single post may.
+     */
+    takeLead() {
+        if (this.left.some(candidate => candidate.top !== null))
+            return this.take([]);
+        const leads = this.left.filter(candidate => candidate.leads && !candidate.column);
+        const best = leads[0];
+        if (!best)
+            return this.take([], { singles: true });
+        const chosen = best.media || best.engaged ? best
+            : leads.find(candidate => candidate.media && candidate.engaged)
+                ?? leads.find(candidate => candidate.media) ?? leads.find(candidate => candidate.engaged);
+        if (!chosen)
+            return this.take([], { singles: true });
+        this.left.splice(this.left.indexOf(chosen), 1);
+        return chosen.module;
+    }
 }
 function weave(first, second) {
     const out = [];
@@ -451,7 +490,9 @@ export function weaveDiscoveryArrival(rows, arriving, reached, floor = 0) {
  * moves: they go after the last row seen (`reached`, by id, and one more for a row only peeking in), never above `floor`;
  * with nothing seen yet, at the end. Below that place the arriving rows and the rows not seen yet are merged: the rows
  * that are not posts (a story, a rail, a row of the client's own) take the places they would have had woven in one by
- * one, and the posts fill the other places by engagement under the network mix (DiscoveryEngagementMerge).
+ * one, and the posts fill the other places by engagement under the network mix (DiscoveryEngagementMerge). The first
+ * post at the top of the feed, or below the line where it turned (`floor`), leads what comes under it (takeLead): never
+ * a post with no picture or clip that nobody engaged with while the batch holds one with either.
  */
 export function mergeDiscoveryArrival(rows, arriving, reached, floor = 0, now = Date.now()) {
     const at = arrivalPlace(rows, reached, floor);
@@ -464,12 +505,14 @@ export function mergeDiscoveryArrival(rows, arriving, reached, floor = 0, now =
     const place = new Map(posts.map((module, index) => [module, index]));
     const merge = new DiscoveryEngagementMerge(pooled, { now, order: (module, index) => place.get(module) ?? posts.length + index });
     const out = [...head];
+    let leading = !head.slice(Math.min(floor, head.length)).some(isDiscoveryPostModule);
     for (const row of below) {
         if (!isDiscoveryPostModule(row)) {
             out.push(row);
             continue;
         }
-        const next = merge.take(out);
+        const next = leading ? merge.takeLead() : merge.take(out);
+        leading = false;
         if (next)
             out.push(next);
     }

package/dist/resources/sealed.d.ts

@@ -0,0 +1,97 @@
+import type { HttpClient } from '../client.js';
+/**
+ * Sealed mode's config and transport: where the app sends a sealed request, which routers and models it may use, and
+ * the member's allowance. No crypto lives here, so the SDK stays dependency-free: the app verifies the router's
+ * attestation and seals the body with Recursiv's verifier (packages/e2ee attest), then hands this resource the sealed
+ * bytes. The gateway relays them to the router without opening them.
+ *
+ * Off unless the API runs with SEALED_GATEWAY_ENABLED and SEALED_GATEWAY_PROJECTS names the app the key is bound to:
+ * until then `config()` and `send()` throw NotFoundError.
+ *
+ * React Native: the global fetch there (whatwg-fetch) cannot stream. It has no `response.body`, so a streamed answer
+ * cannot be read as it arrives, and it posts a ReadableStream body as the text "[object ReadableStream]". Pass a fetch
+ * that streams, such as expo/fetch's, as `send({ fetch })` for streamed answers or a ReadableStream body.
+ */
+/** What `config()` returns. */
+export interface SealedConfig {
+    /** The chat route, relative to the API base: `/sealed/v1/chat/completions`. */
+    chat_completions_path: string;
+    /**
+     * The routers the gateway forwards to, as exact origins (`https://inference.tinfoil.sh`). The app attests one of
+     * these, seals to the key that attestation proves, and names it in `send()`.
+     */
+    routers: string[];
+    /** The models the app offers in Sealed, e.g. `gemma4-31b`. */
+    models: string[];
+    /** The attestation policy version the app's verifier must pin; an older pinned policy means the app needs updating. */
+    verifier_policy_version: number;
+    allowance: SealedAllowance;
+}
+export interface SealedAllowance {
+    requests_per_day: number;
+    requests_per_minute: number;
+    max_concurrent: number;
+    /** The cap on one sealed request body, in bytes. */
+    max_request_bytes: number;
+}
+export interface SealedSendInput {
+    /** The router the app verified and sealed to: one of `config().routers`, exactly. */
+    enclaveOrigin: string;
+    /** The EHBP encapsulated key from sealing the body: 64 hex characters. */
+    encapsulatedKey: string;
+    /** The EHBP-framed sealed body. */
+    body: Uint8Array | ArrayBuffer | ReadableStream<Uint8Array>;
+    /** Ask for a streamed (server-sent events) answer. */
+    stream?: boolean;
+    /** The routers from a config already read. When omitted, `send()` reads the config first. */
+    routers?: readonly string[];
+    signal?: AbortSignal;
+    /**
+     * The fetch to send with; the global fetch when omitted. On React Native pass one that streams (expo/fetch's): the
+     * global one there cannot read a streamed answer as it arrives or send a ReadableStream body.
+     */
+    fetch?: typeof fetch;
+}
+/** Why `send()` refused before or after the request, with nothing shown to the member as the model's words. */
+export type SealedTransportErrorCode = 
+/** The router is not one the gateway lists: nothing was sent. */
+'enclave_not_allowed'
+/** The encapsulated key is not 32 bytes of hex: nothing was sent. */
+ | 'bad_encapsulated_key'
+/** A 2xx answer without a valid Ehbp-Response-Nonce: its body was discarded unread. */
+ | 'unsealed_answer';
+export declare class SealedTransportError extends Error {
+    readonly code: SealedTransportErrorCode;
+    constructor(code: SealedTransportErrorCode, message: string);
+}
+/** Set on a refusal the gateway wrote itself; a relayed router answer never carries it. */
+export declare const SEALED_REFUSAL_HEADER = "x-sealed-gateway-refusal";
+/**
+ * Requests left in the member's allowance today. The gateway sets it on every answer it relayed from the router and on
+ * no other, and the router cannot set it, so an error without it is one the API (or an edge in front of it) wrote.
+ */
+export declare const SEALED_ALLOWANCE_REMAINING_HEADER = "x-sealed-allowance-remaining";
+export declare class SealedResource {
+    private client;
+    constructor(client: HttpClient);
+    /** The routers, models, verifier policy version and allowance the app needs before it seals anything. */
+    config(): Promise<SealedConfig>;
+    /** The URL `send()` posts to. */
+    chatCompletionsUrl(): string;
+    /**
+     * Sends one sealed chat request through the gateway, once. It never retries: a repeated request runs and is billed
+     * again, and Sealed never falls back to anything else.
+     *
+     * Returns the gateway's Response:
+     * - a sealed answer (`Ehbp-Response-Nonce` set): open it with the context that sealed the request;
+     * - a router error the gateway relayed (it carries X-Sealed-Allowance-Remaining): unauthenticated plaintext when it
+     *   has no nonce, never to be shown as the model's words.
+     *
+     * Throws a RecursivError for every error the API wrote rather than relayed, whether or not it is marked
+     * X-Sealed-Gateway-Refusal: RateLimitError for an allowance used up (`code` `sealed_allowance_used` or
+     * `sealed_too_many_requests`) or the API's own per-IP limit (`rate_limited`), AuthenticationError for a revoked or
+     * expired key, NotFoundError while Sealed is off or not on for this app. Throws SealedTransportError when the router
+     * is not listed, the key is malformed, or a 2xx answer came back unsealed.
+     */
+    send(input: SealedSendInput): Promise<Response>;
+}

package/dist/resources/sealed.js

@@ -0,0 +1,145 @@
+import { AuthenticationError, AuthorizationError, NotFoundError, RateLimitError, RecursivError, ValidationError, errorBodyFromResponse, rateLimitDetailsFromResponse, } from '../errors.js';
+export class SealedTransportError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SealedTransportError';
+        this.code = code;
+    }
+}
+/** Set on a refusal the gateway wrote itself; a relayed router answer never carries it. */
+export const SEALED_REFUSAL_HEADER = 'x-sealed-gateway-refusal';
+/**
+ * Requests left in the member's allowance today. The gateway sets it on every answer it relayed from the router and on
+ * no other, and the router cannot set it, so an error without it is one the API (or an edge in front of it) wrote.
+ */
+export const SEALED_ALLOWANCE_REMAINING_HEADER = 'x-sealed-allowance-remaining';
+const HEX_32_BYTES = /^[0-9a-fA-F]{64}$/;
+function exactOrigin(value) {
+    try {
+        const url = new URL(value);
+        if (url.username || url.password || url.search || url.hash || url.pathname !== '/')
+            return null;
+        return url.origin;
+    }
+    catch {
+        return null;
+    }
+}
+export class SealedResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** The routers, models, verifier policy version and allowance the app needs before it seals anything. */
+    async config() {
+        return this.client.get('/sealed/config');
+    }
+    /** The URL `send()` posts to. */
+    chatCompletionsUrl() {
+        return this.client.buildUrl('/sealed/v1/chat/completions');
+    }
+    /**
+     * Sends one sealed chat request through the gateway, once. It never retries: a repeated request runs and is billed
+     * again, and Sealed never falls back to anything else.
+     *
+     * Returns the gateway's Response:
+     * - a sealed answer (`Ehbp-Response-Nonce` set): open it with the context that sealed the request;
+     * - a router error the gateway relayed (it carries X-Sealed-Allowance-Remaining): unauthenticated plaintext when it
+     *   has no nonce, never to be shown as the model's words.
+     *
+     * Throws a RecursivError for every error the API wrote rather than relayed, whether or not it is marked
+     * X-Sealed-Gateway-Refusal: RateLimitError for an allowance used up (`code` `sealed_allowance_used` or
+     * `sealed_too_many_requests`) or the API's own per-IP limit (`rate_limited`), AuthenticationError for a revoked or
+     * expired key, NotFoundError while Sealed is off or not on for this app. Throws SealedTransportError when the router
+     * is not listed, the key is malformed, or a 2xx answer came back unsealed.
+     */
+    async send(input) {
+        const origin = exactOrigin(input.enclaveOrigin);
+        const routers = input.routers ?? (await this.config()).routers;
+        if (!origin || !routers.includes(origin)) {
+            throw new SealedTransportError('enclave_not_allowed', 'That router is not one the gateway forwards to. Nothing was sent.');
+        }
+        if (!HEX_32_BYTES.test(input.encapsulatedKey)) {
+            throw new SealedTransportError('bad_encapsulated_key', 'The encapsulated key must be 32 bytes of hex. Nothing was sent.');
+        }
+        // Time out waiting for the answer to start; once it has, a long stream runs until it ends or the caller aborts.
+        const controller = new AbortController();
+        const onCallerAbort = () => controller.abort(input.signal?.reason);
+        if (input.signal?.aborted)
+            controller.abort(input.signal.reason);
+        else
+            input.signal?.addEventListener('abort', onCallerAbort, { once: true });
+        const timer = setTimeout(() => controller.abort(), this.client.requestTimeoutMs);
+        const fetchImpl = input.fetch ?? fetch;
+        const streamedBody = typeof ReadableStream !== 'undefined' && input.body instanceof ReadableStream;
+        let response;
+        try {
+            response = await fetchImpl(this.chatCompletionsUrl(), {
+                method: 'POST',
+                headers: {
+                    ...this.client.apiKeyAuthHeader(),
+                    'Content-Type': 'application/json',
+                    Accept: input.stream ? 'text/event-stream' : 'application/json',
+                    'Ehbp-Encapsulated-Key': input.encapsulatedKey,
+                    'X-Tinfoil-Enclave-Url': origin,
+                    // For the planned privacy_tier_mismatch 409 (S28 in the Minds AI choices spec): a Standard AI path that
+                    // receives a request marked Sealed is meant to refuse it. No server path reads this header yet, so nothing
+                    // enforces that today; the Sealed gateway strips it before the router.
+                    'X-Recursiv-Privacy-Tier': 'sealed',
+                },
+                body: input.body,
+                signal: controller.signal,
+                ...(streamedBody ? { duplex: 'half' } : {}),
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const detach = () => input.signal?.removeEventListener('abort', onCallerAbort);
+        if (response.headers.has(SEALED_REFUSAL_HEADER)) {
+            detach();
+            throw await gatewayRefusal(response);
+        }
+        const nonce = response.headers.get('ehbp-response-nonce');
+        if (response.ok && (!nonce || !HEX_32_BYTES.test(nonce))) {
+            detach();
+            await response.body?.cancel().catch(() => { });
+            throw new SealedTransportError('unsealed_answer', 'The answer was not sealed, so it was discarded unread.');
+        }
+        // An error the gateway did not relay: the API's 404 while Sealed is off or not on for this app, apiKeyAuth's 401
+        // for a revoked or expired key, the API's per-IP 429, or an edge's own error. None of these is the router's.
+        if (!response.ok && !response.headers.has(SEALED_ALLOWANCE_REMAINING_HEADER)) {
+            detach();
+            throw await gatewayRefusal(response);
+        }
+        if (!response.body)
+            detach();
+        return response;
+    }
+}
+/** A typed error for an answer the API wrote itself (the gateway's refusals and the API's own errors). */
+async function gatewayRefusal(response) {
+    let body = null;
+    try {
+        body = await response.json();
+    }
+    catch {
+        // Fall through to the generic body for the status.
+    }
+    const err = errorBodyFromResponse(response.status, response.statusText, body);
+    switch (response.status) {
+        case 400:
+            return new ValidationError(err);
+        case 401:
+            return new AuthenticationError(err);
+        case 403:
+            return new AuthorizationError(err);
+        case 404:
+            return new NotFoundError(err);
+        case 429:
+            return new RateLimitError(err, rateLimitDetailsFromResponse(response.headers, err));
+        default:
+            return new RecursivError(response.status, err);
+    }
+}

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
 
@@ -833,7 +833,7 @@ await r.appSubscriptions.changeTier({ tier: 'pro', proration_date: quote.prorati
   - 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`. 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.
+  - 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; 0.7.80: never a post with no picture or clip and no engagement while the screen holds one with either, which then leads: media and engagement, else media, else engagement, as `mergeDiscoveryArrival` leads a feed's top and the feed after a line), 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.
   - One outlet count per story (0.7.71): a radar story (list, story read, archive), a World Today story (`outlets`, with `outlet_count` its total and `lane_mix` its lanes), a category strip story, a `feeds.top`/`feeds.stories` story and a search story carry `outlets: { total, mainstream, independent, other }`, the distinct outlets of the articles the story lists (an allow-listed outlet once, an unlisted host in `other`; the buckets sum to `total`). Show `outlets.total`; `sources.outlet` counts articles. `DiscoveryCluster.outletCount` reads it. An older server omits it.

package/package.json

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