@recursiv/sdk 0.7.65 → 0.7.66

package/README.md

@@ -670,6 +670,25 @@ and says whether the member is personalized yet (`meta.personalized`). With a
 `category` (the member's first), the session also reads open-network posts from it;
 without, it is Minds only. It never carries the radar.
 
+### For You: the world by the member's interests
+
+`sdk.curator.forYouWorld({ part?, session?, snapshot?, compass? })` reads the For You overview
+for the signed-in member, with their own key of the app. `stories` are world stories (Today,
+the radar and the viral read) matched to the member's interests with breadth: at least four
+themes and two breaking or general stories in the first eight, at most two per theme, and a
+story shown three times without an open rests for a week. `items` are the member's For You
+picks interleaved with the most engaging posts of their top interests (half or more on their
+interests, no interest over 40%, videos weighted up), and `blocks` lay the page out like All:
+`stories`, `lead_video`, `clips`, `posts`, `people`, `groups`, `topics`, `viral` and
+`categories`, never the same type twice in a row, each naming the refs its views should send.
+Every story and item carries `reasons` (`interest:<category>`, `followed:@<handle>`, `breaking`,
+`general`, `for_you`, `engaging`, `breadth`). `part: 'stories'` and `part: 'items'` read the
+two halves on their own, so an app can draw each as it lands; a part=items answer keeps the
+stories rail as a `deferred` block. `meta.interests` are category ids for chips (never put them
+in a URL), `meta.partial` names a source that missed its deadline, and `meta.foryou_cursor`
+continues the same ranking with `curator.forYou({ cursor })`. 404 while the app's operator has
+it off; a 503 `for_you_world_unavailable` carries Retry-After.
+
 ### The top of a feed
 
 `sdk.feeds.top({ ref, limit?, session?, compass? })` answers the top of a feed for the

package/dist/index.d.ts

@@ -195,7 +195,7 @@ export { VideoResource } from './resources/video.js';
 export type { VideoUploadCreds, CreateVideoUploadResult, VideoStatusInfo, VideoPlaybackToken, VideoEntitlement, } from './resources/video.js';
 export { AppSubscriptionsResource } from './resources/app-subscriptions.js';
 export type { AppSubscriptionBoostCredit, AppSubscriptionCheckoutResult, AppSubscriptionPortalResult, AppSubscriptionStatusResult, AppSubscriptionTierChangePreview, AppSubscriptionTierChangeResult, } from './resources/app-subscriptions.js';
-export type { CuratorSource, CuratorPrompt, CuratorRunInput, CuratorRunResult, CuratorTodayEdition, CuratorTodayExcerpt, CuratorTodayLeadImage, CuratorTodayRadar, CuratorTodayReaction, CuratorTodayResponse, CuratorTodaySource, CuratorTodayStory, ForYouMeta, ForYouParams, ForYouSurface, } from './resources/curator.js';
+export type { CuratorSource, CuratorPrompt, CuratorRunInput, CuratorRunResult, CuratorTodayEdition, CuratorTodayExcerpt, CuratorTodayLeadImage, CuratorTodayRadar, CuratorTodayReaction, CuratorTodayResponse, CuratorTodaySource, CuratorTodayStory, ForYouMeta, ForYouParams, ForYouSurface, ForYouWorldBlock, ForYouWorldBlockType, ForYouWorldCategoryShortcut, ForYouWorldItem, ForYouWorldMeta, ForYouWorldParams, ForYouWorldPart, ForYouWorldResponse, ForYouWorldStory, ForYouWorldStoryTarget, ForYouWorldViral, } from './resources/curator.js';
 export { ReportsResource } from './resources/reports.js';
 export type { ReportTargetType, ReportStatus, CreateReportInput, ReportRecord, ResolveReportInput, } from './resources/reports.js';
 export { ModerationResource } from './resources/moderation.js';

package/dist/resources/curator.d.ts

@@ -1,5 +1,6 @@
 import type { HttpClient } from '../client.js';
-import type { DiscoveryLayout, PaginatedResponse, PaginationMeta, Post, SingleResponse } from '../types.js';
+import type { CompassFilterMeta, DiscoveryLayout, PaginatedResponse, PaginationMeta, Post, SingleResponse } from '../types.js';
+import type { FeedTopNetworkCard, FeedTopTarget } from './feeds.js';
 /** Which surface is asking: Home's For You (default) or Discover's For you. */
 export type ForYouSurface = 'home' | 'discover';
 export type ForYouParams = {
@@ -22,6 +23,158 @@ export interface ForYouMeta extends PaginationMeta {
     /** Whether the ranker can personalize for this member yet (3 follows or 3 upvoted authors). */
     personalized?: boolean;
 }
+/** Which half to read: the stories rail, the items, or both (the default). The app can read the two at once and draw each as it lands. */
+export type ForYouWorldPart = 'stories' | 'items' | 'all';
+export interface ForYouWorldParams {
+    part?: ForYouWorldPart;
+    /** 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 For You snapshot nonce the app holds (`meta.snapshot` of a previous answer): reused while the server holds it. */
+    snapshot?: string;
+    /** A Politics choice, as `posts.list` takes it. */
+    compass?: string;
+}
+/** Where a story opens in the app: a radar story by its cluster id, or a World Today story the radar has none for by its Today id. */
+export type ForYouWorldStoryTarget = {
+    kind: 'story';
+    id: string;
+} | {
+    kind: 'today_story';
+    id: string;
+};
+/** One world story: a radar story (with Today's headline when Today seeded it), a Today story, or a viral post. */
+export interface ForYouWorldStory {
+    /** What an impression of it names: 'cluster:<id>', 'today:<id>' or the post's ref. Send it with `block: 'top'` on a visible view. */
+    ref: string;
+    id: string;
+    source: 'today' | 'radar' | 'viral';
+    target: FeedTopTarget | ForYouWorldStoryTarget;
+    label: string;
+    kind: 'breaking' | 'viral' | 'story';
+    breaking: boolean;
+    /** A front-page or general-news story: one of those shown whatever the member's interests. */
+    general: boolean;
+    theme: string | null;
+    categories: string[];
+    /** How widely it is told: posts per source kind, and the outlets that ran it (Today), when known. */
+    counts: {
+        sources: Record<string, number>;
+        outlets: number | null;
+    };
+    media: {
+        images: number;
+        videos: number;
+    };
+    freshness: {
+        newestAt: string | null;
+    };
+    position: number;
+    /** Why it is here: `interest:<category>`, `breaking`, `general`, `viral`, `breadth` or `trending`. */
+    reasons: string[];
+    explain: {
+        score: number;
+        interest: number;
+        rank: number;
+        impression: 'fresh' | 'demoted';
+    };
+}
+/** One item: a Minds post (`ref` is its id) or an open-network post (`ref` is '<protocol>/<nativeId>'). */
+export interface ForYouWorldItem {
+    ref: string;
+    kind: 'post' | 'network_post';
+    authorId: string;
+    target: FeedTopTarget;
+    /** Reading order through the blocks. */
+    position: number;
+    /** 'top' for the first 10: send `block: 'top'` and the position with a visible view of one. */
+    block: 'top' | 'below';
+    media: 'video' | 'image' | 'none';
+    topic: string | null;
+    /** Why it is here: `interest:<category>`, `followed:@<handle>`, `for_you`, `engaging` or `breadth`. */
+    reasons: string[];
+    explain: {
+        score: number;
+        source: 'foryou' | 'category' | 'all';
+        label: 'safe' | 'open';
+        impression: 'fresh' | 'demoted';
+        engagement: {
+            source: string;
+            rate: number;
+        };
+    };
+}
+/** A viral post in the viral block. `card` is an open-network post's card (no URL on its network); null for a Minds post, read by id. */
+export interface ForYouWorldViral {
+    ref: string;
+    kind: 'post' | 'network_post';
+    protocol: string;
+    target: FeedTopTarget;
+    label: string;
+    category: string | null;
+    media: 'video' | 'image' | null;
+    rank: number;
+    velocity: {
+        perHour1h: number;
+        z: number;
+    };
+    card: FeedTopNetworkCard | null;
+}
+export interface ForYouWorldCategoryShortcut {
+    id: string;
+    name: string;
+    reason: 'interest' | 'breadth';
+    target: {
+        kind: 'category';
+        id: string;
+    };
+}
+/** The page's components, laid out like All: no type follows itself. */
+export type ForYouWorldBlockType = 'stories' | 'lead_video' | 'clips' | 'posts' | 'people' | 'groups' | 'topics' | 'categories' | 'viral';
+export interface ForYouWorldBlock {
+    id: string;
+    type: ForYouWorldBlockType;
+    /** What it shows, in order: item refs (lead_video, clips, posts), story refs, entity keys, category ids or viral refs. */
+    refs: string[];
+    /** The stories rail of a part=items answer: fill it from your own part=stories read. */
+    deferred?: true;
+    /** people, groups and topics: the recommender's suggestions (three showings without a tap rest one). */
+    entities?: Array<Record<string, unknown> & {
+        kind: string;
+        key: string;
+    }>;
+    categories?: ForYouWorldCategoryShortcut[];
+    viral?: ForYouWorldViral[];
+}
+export interface ForYouWorldMeta {
+    part: ForYouWorldPart;
+    flag: {
+        world: 'on';
+        impressions: 'on' | 'off' | 'unavailable';
+    };
+    /** Fewer than 3 follows and no signals yet: a breadth-only overview. */
+    cold_start: boolean;
+    personalized: boolean | null;
+    /** The member's top interests as browse category ids, for chips. Never put them in a URL. */
+    interests: string[];
+    /**
+     * Sources left out because they missed their deadline or failed. `consent` is the Bluesky consent read: when it is
+     * named, Bluesky posts from the category pools and the viral read were left out of this answer.
+     */
+    partial: string[];
+    safety: 'safe' | 'open' | null;
+    /** The For You snapshot the items came from; `foryou_cursor` continues it on `curator.forYou({ cursor })`. */
+    snapshot: string | null;
+    foryou_cursor: string | null;
+    short: boolean;
+    compass_filter?: CompassFilterMeta;
+}
+/** GET /curator/foryou/world: `stories` unless part=items, `items` and `blocks` unless part=stories. */
+export interface ForYouWorldResponse {
+    stories?: ForYouWorldStory[];
+    items?: ForYouWorldItem[];
+    blocks?: ForYouWorldBlock[];
+    meta: ForYouWorldMeta;
+}
 /** RSS / Atom source. Default — `type` may be omitted for back-compat. */
 export interface CuratorRssSource {
     type?: 'rss';
@@ -278,4 +431,13 @@ export declare class CuratorResource {
     forYou(params?: ForYouParams): Promise<PaginatedResponse<Post> & {
         meta: ForYouMeta;
     }>;
+    /**
+     * For You as an overview of the world by the member's interests, read with their own key of the app: world stories
+     * (interest-matched, with breadth), then a page of typed blocks laid out like All (a lead video, clip strips, posts,
+     * people and groups to follow, trending topics, viral posts, category shortcuts). `part` reads one half on its own.
+     * 404 until the app's operator turns it on; a 503 `for_you_world_unavailable` carries Retry-After. Always private.
+     */
+    forYouWorld(params?: ForYouWorldParams, options?: {
+        retry?: boolean;
+    }): Promise<ForYouWorldResponse>;
 }

package/dist/resources/curator.js

@@ -57,4 +57,13 @@ export class CuratorResource {
         const { retry, ...query } = params;
         return retry === false ? this.client.get('/curator/foryou', query, { retry: false }) : this.client.get('/curator/foryou', query);
     }
+    /**
+     * For You as an overview of the world by the member's interests, read with their own key of the app: world stories
+     * (interest-matched, with breadth), then a page of typed blocks laid out like All (a lead video, clip strips, posts,
+     * people and groups to follow, trending topics, viral posts, category shortcuts). `part` reads one half on its own.
+     * 404 until the app's operator turns it on; a 503 `for_you_world_unavailable` carries Retry-After. Always private.
+     */
+    forYouWorld(params = {}, options) {
+        return this.client.get('/curator/foryou/world', { part: params.part, session: params.session, snapshot: params.snapshot, compass: params.compass }, options);
+    }
 }

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/llm.md

@@ -639,6 +639,18 @@ 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

package/package.json

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