@recursiv/sdk 0.7.63 → 0.7.66

package/dist/resources/feeds.d.ts

@@ -0,0 +1,228 @@
+import type { HttpClient } from '../client.js';
+import type { CompassFilterMeta } from '../types.js';
+/**
+ * The top of a feed: what the member (or a visitor) is most likely to engage with, rotated by what they have seen.
+ * `feeds.top` and `feeds.stories` read it for a member with their own key of the app; `feeds.publicTop` reads a
+ * visitor's top keylessly. A feed session (`discovery.createFeed({ top })`) opens its first page with it.
+ *
+ * Every tap target is in the app: a Minds post by id, an open-network post by `/social/post/<protocol>/<id>`, a story
+ * by id. Nothing here is a URL on another network.
+ */
+/** The open networks whose lanes a top carries. */
+export type FeedTopNetwork = 'bluesky' | 'activitypub' | 'nostr';
+export declare const FEED_TOP_NETWORKS: readonly FeedTopNetwork[];
+/** Where a tap on an item goes, always in the app. `path` is the app's own page of a network post, never its URL there. */
+export type FeedTopTarget = {
+    kind: 'post';
+    id: string;
+} | {
+    kind: 'network_post';
+    protocol: string;
+    nativeId: string;
+    path: string;
+    readRef?: string;
+};
+/** Why an item is where it is. */
+export interface FeedTopExplain {
+    score: number;
+    engagement: {
+        source: string;
+        rate: number;
+    };
+    media: string;
+    origin: string;
+    /** Where the item came from: the Minds ranking, Watch's list, a radar story, the member's follows, or a network's trends. */
+    source: 'minds' | 'watch' | 'radar' | 'following' | 'trends';
+    /** 'safe' for everyone; 'open' only for a member who turned safe defaults off. */
+    label: 'safe' | 'open';
+    cluster: string | null;
+    topic: string | null;
+    /** 'demoted': the member viewed it in the last 6 hours (it sits below rank 20). A visitor's items are all 'fresh'. */
+    impression: 'fresh' | 'demoted';
+}
+/** One item of the top: a Minds post (`ref` is its id) or an open-network post (`ref` is '<protocol>/<nativeId>'). */
+export interface FeedTopItem {
+    ref: string;
+    kind: 'post' | 'network_post';
+    authorId: string;
+    target: FeedTopTarget;
+    position: number;
+    /** 'top' for the first 10: send `block: 'top'` and the position with a visible view of one (an impression). */
+    block: 'top' | 'below';
+    explain: FeedTopExplain;
+}
+/** What an app draws for an open-network lane entry. No URL on the post's network: the app opens it by `target.path`. */
+export interface FeedTopNetworkCard {
+    text: string;
+    createdAt: string;
+    author: {
+        nativeId: string;
+        handle: string;
+        displayName: string;
+        avatarUrl: string | null;
+    };
+    media: Array<{
+        type: 'image' | 'video';
+        url: string;
+        alt: string;
+        poster?: string;
+        width?: number;
+        height?: number;
+    }>;
+    counts: {
+        likes: number | null;
+        replies: number | null;
+        reposts: number | null;
+    };
+    sensitive: boolean;
+    /** The post quotes another; read the quote when the post is opened. */
+    hasQuote: boolean;
+}
+/** One entry of an open-network lane: up to six per network, ranked by engagement and rotated by impressions. */
+export interface FeedTopNetworkEntry extends FeedTopItem {
+    kind: 'network_post';
+    protocol: FeedTopNetwork;
+    card: FeedTopNetworkCard;
+}
+/** A story as the top names it: its id and in-app target, never an outlet's or a network's URL. */
+export interface FeedStory {
+    id: string;
+    /** 'cluster:<id>': what an impression of the story names. */
+    ref: string;
+    target: {
+        kind: 'story';
+        id: string;
+    };
+    label: string;
+    kind: 'breaking' | 'viral' | 'story';
+    breaking: boolean;
+    theme: string | null;
+    sources: Partial<Record<'outlet' | 'hackernews' | 'bluesky' | 'activitypub' | 'nostr' | 'minds', number>>;
+    media: {
+        images: number;
+        videos: number;
+    };
+    freshness: {
+        newestAt: string;
+        oldestAt: string;
+    };
+    explain: {
+        score: number;
+        parts: {
+            ageHours: number;
+            engagement: number;
+            media: number;
+            kind: number;
+            freshness: number;
+        };
+        impression: 'fresh' | 'demoted';
+    };
+}
+export interface FeedTopMeta {
+    ref: string;
+    poolBuiltAt: string;
+    poolSize: number;
+    /** Fewer items than asked for (a thin pool, the caps, or only items the member saw recently). */
+    short: boolean;
+    /** `impressions`: 'on' when the order uses what the member saw; otherwise the order is the pool's, jittered per session. */
+    flag: {
+        top: 'on';
+        impressions: 'on' | 'off' | 'unavailable';
+    };
+    stoppedBy: 'pool' | 'caps' | 'seen' | null;
+    /** 'safe' for a member on safe defaults, 'open' for one who turned them off. */
+    safety: 'safe' | 'open';
+    mindsSource: 'member' | 'anonymous' | 'none' | 'following';
+    networks: Record<FeedTopNetwork, 'ok' | 'unavailable'> | null;
+    compass_filter?: CompassFilterMeta;
+}
+/** GET /feeds/top. `networks` is null on a feed with no lanes (Following, a story); `lead` is null when the feed has no story. */
+export interface FeedTopResponse {
+    items: FeedTopItem[];
+    networks: Record<FeedTopNetwork, FeedTopNetworkEntry[]> | null;
+    lead: FeedStory | null;
+    meta: FeedTopMeta;
+}
+export interface FeedStoriesResponse {
+    data: FeedStory[];
+    meta: {
+        after: string | null;
+        limit: number;
+        short: boolean;
+        flag: {
+            top: 'on';
+            impressions: 'on' | 'off' | 'unavailable';
+        };
+        compass_filter?: CompassFilterMeta;
+    };
+}
+export interface PublicFeedTopMeta {
+    ref: string;
+    /** The 15-minute bucket the page was drawn for: the same for every visitor in it. */
+    bucket: number;
+    poolBuiltAt: string | null;
+    poolSize: number;
+    short: boolean;
+    flag: {
+        top: 'on';
+    };
+    compass_filter?: CompassFilterMeta;
+}
+/** A visitor's top (`feeds.publicTop`): safe items only, the same for every visitor in one 15-minute bucket. */
+export interface PublicFeedTopResponse {
+    items: FeedTopItem[];
+    networks: Record<FeedTopNetwork, FeedTopNetworkEntry[]> | null;
+    lead: FeedStory | null;
+    meta: PublicFeedTopMeta;
+}
+export interface FeedTopParams {
+    /** `builtin:all`, `category:<a browse category id>`, `following`, `watch` or `story:<a 64-character cluster id>`. */
+    ref: string;
+    /** 1..25, default 25. */
+    limit?: number;
+    /** Opaque per app session ([A-Za-z0-9_-], up to 64): the same token keeps one session's order stable across reads. */
+    session?: string;
+    /** A Politics choice, as `posts.list` takes it (refused on `following`). */
+    compass?: string;
+}
+export interface FeedStoriesParams {
+    /** The story the member is on (a 64-character cluster id): left out of the next ones. */
+    after?: string;
+    /** 1..10, default 10. */
+    limit?: number;
+    compass?: string;
+}
+export interface PublicFeedTopParams {
+    /** The app's project id. */
+    projectId: string;
+    /** `all` (default), `watch` or `category:<a browse category id>`. */
+    ref?: string;
+    /** 1..25 (the server's default is 25). */
+    limit?: number;
+    /** `all` or `hide`: a visitor's Politics choice. */
+    compass?: string;
+}
+export declare class FeedsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * The top of a feed for the signed-in member, with their own key of the app: the items they are most likely to engage
+     * with, rotated by what they have seen, the open-network lanes and the lead story. Off (404) until the app's operator
+     * turns it on; a 503 `feed_top_unavailable` carries Retry-After. Always private: never cached for anyone else.
+     */
+    top(params: FeedTopParams, options?: {
+        retry?: boolean;
+    }): Promise<FeedTopResponse>;
+    /** The stories the member should meet next (the story tail), by the same ranker as the top's lead. */
+    stories(params?: FeedStoriesParams, options?: {
+        retry?: boolean;
+    }): Promise<FeedStoriesResponse>;
+    /**
+     * A visitor's top of All, a category or Watch (tRPC `publicDiscovery.feedTop`): safe items only, the same for every
+     * visitor in one 15-minute bucket. Read with no credential at all (no key, no cookie: `credentials: 'omit'`), so the
+     * edge can hold it; a credentialed read would be private and uncached. Off (404) until the app's operator turns it on.
+     */
+    publicTop(params: PublicFeedTopParams, options?: {
+        timeoutMs?: number;
+    }): Promise<PublicFeedTopResponse>;
+}

package/dist/resources/feeds.js

@@ -0,0 +1,61 @@
+import { NotFoundError, RecursivError } from '../errors.js';
+export const FEED_TOP_NETWORKS = ['bluesky', 'activitypub', 'nostr'];
+export class FeedsResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * The top of a feed for the signed-in member, with their own key of the app: the items they are most likely to engage
+     * with, rotated by what they have seen, the open-network lanes and the lead story. Off (404) until the app's operator
+     * turns it on; a 503 `feed_top_unavailable` carries Retry-After. Always private: never cached for anyone else.
+     */
+    top(params, options) {
+        return this.http.get('/feeds/top', { ref: params.ref, limit: params.limit, session: params.session, compass: params.compass }, options);
+    }
+    /** The stories the member should meet next (the story tail), by the same ranker as the top's lead. */
+    stories(params = {}, options) {
+        return this.http.get('/feeds/stories', { after: params.after, limit: params.limit, compass: params.compass }, options);
+    }
+    /**
+     * A visitor's top of All, a category or Watch (tRPC `publicDiscovery.feedTop`): safe items only, the same for every
+     * visitor in one 15-minute bucket. Read with no credential at all (no key, no cookie: `credentials: 'omit'`), so the
+     * edge can hold it; a credentialed read would be private and uncached. Off (404) until the app's operator turns it on.
+     */
+    async publicTop(params, options) {
+        // One fixed key order, so equal reads are one edge-cached URL.
+        const input = { projectId: params.projectId, ref: params.ref ?? 'all', ...(params.limit !== undefined ? { limit: params.limit } : {}),
+            ...(params.compass ? { compass: params.compass } : {}) };
+        const url = `${this.http.baseOrigin}/api/trpc/publicDiscovery.feedTop?input=${encodeURIComponent(JSON.stringify(input))}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), options?.timeoutMs ?? this.http.requestTimeoutMs);
+        try {
+            let response;
+            try {
+                response = await fetch(url, { method: 'GET', headers: { Accept: 'application/json' }, credentials: 'omit', signal: controller.signal });
+            }
+            catch (error) {
+                throw new RecursivError(0, { type: 'api_error', code: controller.signal.aborted ? 'timeout' : 'network_error',
+                    message: controller.signal.aborted ? 'The visitor top did not answer in time.' : `The visitor top could not be reached (${error instanceof Error ? error.message : String(error)}).` });
+            }
+            let body = null;
+            try {
+                body = await response.json();
+            }
+            catch {
+                body = null;
+            }
+            const data = body?.result?.data;
+            if (response.ok && data && typeof data === 'object')
+                return data;
+            const error = body?.error && typeof body.error === 'object' ? body.error : undefined;
+            const said = [error?.json?.message, error?.message].find((value) => typeof value === 'string' && value.length > 0);
+            const code = typeof error?.data?.code === 'string' ? error.data.code.toLowerCase() : 'unknown_error';
+            const failure = { type: response.status === 404 ? 'not_found_error' : 'api_error', code, message: said ?? `HTTP ${response.status}` };
+            throw response.status === 404 ? new NotFoundError(failure) : new RecursivError(response.ok ? 502 : response.status, failure);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/resources/profiles.d.ts

@@ -3,7 +3,10 @@ import type { PaginatedResponse, SingleResponse, SuccessResponse, Profile, Profi
 export declare class ProfilesResource {
     private client;
     constructor(client: HttpClient);
-    /** List users in the network */
+    /**
+     * List users in the network, newest first. Automated accounts are left out (a personal agent stays, `is_ai`), and
+     * so is an account wearing an official account's name; a page can come back shorter than `limit`.
+     */
     list(params?: {
         limit?: number;
         offset?: number;

package/dist/resources/profiles.js

@@ -3,7 +3,10 @@ export class ProfilesResource {
     constructor(client) {
         this.client = client;
     }
-    /** List users in the network */
+    /**
+     * List users in the network, newest first. Automated accounts are left out (a personal agent stays, `is_ai`), and
+     * so is an account wearing an official account's name; a page can come back shorter than `limit`.
+     */
     list(params) {
         return this.client.get('/profiles', params);
     }

package/dist/resources/protocols.d.ts

@@ -1043,11 +1043,10 @@ export interface SocialPost {
     };
     /**
      * Present, and only then, when the ActivityPub author opted out of indexing (`noindex`,
-     * `indexable: false`, or #nobot, #noindex or #noai in their bio). The keyless trends, trend-feed and
-     * radar reads leave such posts out, and no post served from the source index is one. The keyless
-     * author-feed and conversation reads (a profile or a post someone opened) and member reads of a
-     * provider window still return them with this mark, so an app should never re-share or promote one
-     * to signed-out visitors.
+     * `indexable: false`, or #nobot, #noindex or #noai in their bio). The trends, trend-feed and radar
+     * reads leave such posts out, keyless and for a member alike, and no post served from the source index
+     * is one. The author-feed and conversation reads (a profile or a post someone opened), keyless or a
+     * member's, still return them with this mark, so an app should never re-share or promote one.
      */
     authorOptOut?: true;
     /** A bridge (Bridgy Fed, Mostr, a NIP-48 proxy tag) made this post from one on another network (SocialBridge). Present only on a copy read live. */

package/dist/resources/search.d.ts

@@ -35,8 +35,9 @@ export interface SearchPerson {
     pro: boolean;
     founder: boolean;
     /**
-     * The account wears the display name of a verified or founder account it is not: it is listed after every account
-     * that is not such a copy. Label it as not the account at `name_matches_verified_handle`. Absent from an older API.
+     * The account wears the display name of a verified or founder account it is not. Such an account is listed only when
+     * the query asks for its handle ("@handle"), after every account that is not such a copy (an older API listed it
+     * last for any query). Label it as not the account at `name_matches_verified_handle`. Absent from an older API.
      */
     name_matches_verified?: boolean;
     name_matches_verified_handle?: string | null;

package/dist/types.d.ts

@@ -1261,8 +1261,9 @@ export interface ProfileSearchResult extends Profile {
     pro: boolean;
     founder: boolean;
     /**
-     * The account wears the display name of a verified or founder account it is not: it is listed after every account
-     * that is not such a copy. Label it as not the account at `name_matches_verified_handle`. Absent from an older API.
+     * The account wears the display name of a verified or founder account it is not. Such an account is listed only when
+     * the query asks for its handle ("@handle"), after every account that is not such a copy (an older API listed it
+     * last for any query). Label it as not the account at `name_matches_verified_handle`. Absent from an older API.
      */
     name_matches_verified?: boolean;
     name_matches_verified_handle?: string | null;

package/llm.md

@@ -639,6 +639,31 @@ await r.bookmarks.unsave(key)                                          // or uns
 
 Newest saved first. Pages can be short while they skip posts the member can no longer read: page on `meta.next_cursor`, not length. Needs the member's own app key (else 403 `project_binding_required`). 503 `bookmarks_unavailable` means the server has no synced bookmarks yet: keep saves on the device (pass `{ retry: false }` to the probe so the 503 is not retried).
 
+### r.curator.forYouWorld — For You as the world by the member's interests
+
+```typescript
+const head = r.curator.forYouWorld({ part: 'stories', session })                // member's own app key; read the two halves at once
+const page = await r.curator.forYouWorld({ part: 'items', session, snapshot })   // items + blocks; snapshot = a previous meta.snapshot
+// stories: { ref, id, source: today|radar|viral, target, label, kind, breaking, general, theme, counts, reasons, ... }
+// items: { ref, kind, target, position, block: 'top' | 'below', media, topic, reasons, explain }
+// blocks: [{ id, type: stories|lead_video|clips|posts|people|groups|topics|viral|categories, refs, deferred?, entities?, categories?, viral? }]
+```
+
+404 while the app's operator has it off; always private (`Cache-Control: private, no-store`). A story's or item's `target` is in the app (a radar story by cluster id, a Today story as `today_story`, a post id, `/social/post/<protocol>/<id>`), never a URL out. Send `block: 'top'` with a visible view of a story in the rail or one of the first 10 items: three such views without an open rest it for a week. `meta.partial` names a source that missed its deadline; `meta.interests` are category ids for chips, never for a URL; `meta.foryou_cursor` continues on `r.curator.forYou({ cursor })`.
+
+### r.feeds — The top of a feed (member and visitor)
+
+```typescript
+const top = await r.feeds.top({ ref: 'builtin:all', limit: 10, session })   // member's own app key; category:<id>, following, watch, story:<id>
+// top.items: { ref, kind, target, position, block: 'top' | 'below', explain }; top.networks: { bluesky, activitypub, nostr } lanes with a card each
+// top.lead: the story to open with; every target is in the app (post id, /social/post/<protocol>/<id>, story id), never a URL out
+const { data: next } = await r.feeds.stories({ after: storyId })             // the story tail, same ranker as the lead
+const page = await r.feeds.publicTop({ projectId, ref: 'all' })              // a visitor's top: safe items only, keyless, edge-cacheable
+const feed = r.discovery.createFeed({ networks, top: { ref: 'builtin:all', session }, seen: seenRefs })
+```
+
+Each answers 404 while the app's operator has it off; `feeds.top` is private to the member and 503 `feed_top_unavailable` carries Retry-After. With a visible view of a top item, send `block: 'top'` and its position. In a feed session the top's read starts with page 0's reads and the top holds the page at most 1.5 s from its start, the by-id reads of its posts included; off, failed or late, the session is unchanged, and the radar's story reads its posts as soon as the radar answers either way. Page 0 then opens with the top's lead story and items (each item carries `top: { ref, position, block }`), its lanes replace the networks' first reads, and no hot page repeats a top item. `seen` (Minds ids and `<protocol>/<nativeId>` refs) leaves seen posts out of the hot pages, walking on past a page left under five posts (up to three more). `seenClusters` (`Map<id, { n, clicked }>`) and a visitor's `bucket` rotate the story when the top names none (`pickRadarCluster`).
+
 ### r.search
 
 ```typescript

package/package.json

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