@recursiv/sdk 0.7.62 → 0.7.65

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/human-input.d.ts

@@ -11,6 +11,10 @@ export interface RequestHumanInputInput {
     steps: string;
     /** One-tap answers (2-4 short words) — rendered as buttons on the phone. */
     options?: string[];
+    /** The option you recommend; must be one of `options`. Marked "Recommended" on the card. */
+    recommended?: string;
+    /** You keep working on `recommended` unless the human answers otherwise. Needs `recommended`. */
+    continuing_with_default?: boolean;
 }
 export interface HumanInputRequest {
     conversation_id: string;

package/dist/resources/protocols.d.ts

@@ -982,6 +982,13 @@ export interface SocialPost {
     author: Omit<SocialProfile, 'subscription'>;
     text: string;
     createdAt: string;
+    /**
+     * The language the post declares, as the lower-case primary subtag of its BCP-47 tag ("de", "en", "pt"): Bluesky's
+     * record `langs[0]`, a Mastodon status's `language`, a Nostr note's NIP-32 `ISO-639-1` self-label. Absent when the post
+     * declares none (most Nostr notes) or a malformed one, and on posts served from the open-network source index; the
+     * server never guesses it from the text and never drops a post for it. Use it to order the viewer's language first.
+     */
+    language?: string;
     replyCount: number | null;
     likeCount: number | null;
     repostCount: number | null;

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/resources/video.d.ts

@@ -13,6 +13,12 @@ export interface CreateVideoUploadResult {
     upload: VideoUploadCreds;
     /** The HLS URL the video will play from once encoding completes. */
     hlsUrl: string;
+    /**
+     * The creator's proof for `renewUpload` (valid 24 h): pass it back to get
+     * fresh credentials for this same video when a resume outlives the hour
+     * `upload` is signed for. Absent from servers older than 0.7.63's API.
+     */
+    resumeGrant?: string;
 }
 export interface VideoStatusInfo {
     status: string | null;
@@ -59,6 +65,20 @@ export declare class VideoResource {
     }): Promise<{
         data: CreateVideoUploadResult;
     }>;
+    /**
+     * Fresh upload credentials for a video this member started, so a TUS resume
+     * that outlives the hour `upload` is signed for continues the same video.
+     * Pass the `resumeGrant` from `createUpload`. 404 for anyone else's video, an
+     * expired grant or an older API without the route; 409 `upload_finished` once
+     * a post carries the video or Bunny holds the whole file; 402 as `createUpload`;
+     * 503 when the video provider could not answer: keep the partial upload and
+     * retry (it never means the video is gone).
+     */
+    renewUpload(playbackId: string, input: {
+        grant: string;
+    }): Promise<{
+        data: CreateVideoUploadResult;
+    }>;
     /** Encode status + metadata for a video. */
     getStatus(playbackId: string): Promise<{
         data: VideoStatusInfo;

package/dist/resources/video.js

@@ -19,6 +19,18 @@ export class VideoResource {
     createUpload(input) {
         return this.client.post('/video/create-upload', input ?? {});
     }
+    /**
+     * Fresh upload credentials for a video this member started, so a TUS resume
+     * that outlives the hour `upload` is signed for continues the same video.
+     * Pass the `resumeGrant` from `createUpload`. 404 for anyone else's video, an
+     * expired grant or an older API without the route; 409 `upload_finished` once
+     * a post carries the video or Bunny holds the whole file; 402 as `createUpload`;
+     * 503 when the video provider could not answer: keep the partial upload and
+     * retry (it never means the video is gone).
+     */
+    renewUpload(playbackId, input) {
+        return this.client.post(`/video/${encodeURIComponent(playbackId)}/renew-upload`, input);
+    }
     /** Encode status + metadata for a video. */
     getStatus(playbackId) {
         return this.client.get(`/video/${playbackId}/status`);

package/dist/types.d.ts

@@ -649,9 +649,15 @@ export interface ConversationMember {
      */
     role?: ChatMemberRole;
     /**
-     * In a private group, every member's request: `pending` until an invitee
-     * accepts. Declining stays private, so to anyone else a member who declined
-     * still reads `pending`. Omitted outside private groups and by older APIs.
+     * Each member's message request, in a private group or a one-on-one chat.
+     * Someone who follows the person who wrote (or who made the group), and an
+     * agent, start `accepted`, as the person who wrote does; a chat started
+     * without a request reads `accepted` for both. Anyone else starts `pending`
+     * and reads `accepted` once they accept or reply, or, in a one-on-one chat,
+     * start a chat back. So `accepted` alone does not mean they accepted
+     * anything. Declining stays private: to anyone else a member who declined
+     * still reads `pending`. Omitted in community rooms and by older APIs
+     * (one-on-one chats: before this field was served for them).
      */
     request_status?: ChatRequestStatus;
 }
@@ -1255,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

@@ -502,7 +502,7 @@ Methods: `conversations`, `communityConversation`, `conversation`, `messages`, `
 
 Scroll back with `messages(id, { cursor: page.meta.next_cursor })`, not a growing `offset`. Conversations carry `can_delete` / `can_leave`; check them before offering Delete or Leave.
 
-Private groups (0.7.59): each member has `role` (`admin` or `member`) and, in a group, `request_status`. Only the admin (the creator, then the longest-standing person left) may `addMembers(id, { member_ids })`, `removeMember(id, userId)` and `updateGroup(id, { name })` (else 403 `not_admin`). `createGroup({ name, member_ids, encrypted: true, device_id? })` makes an end-to-end encrypted group of people in the pilot, at most 8 counting pending invitees, or throws 409 `conversation_not_eligible` with `details.reason` and creates nothing. `r.realtime.onChatMembers` / `onChatConversation` tell you when people or the name change.
+Private groups (0.7.59): each member has `role` (`admin` or `member`) and, in a group or a one-on-one chat, `request_status`: `accepted` from the start for the person who wrote, anyone who follows them and agents, else `pending` until that person accepts or replies (a decline reads `pending` to anyone else), so `accepted` alone does not mean they accepted anything. Only the admin (the creator, then the longest-standing person left) may `addMembers(id, { member_ids })`, `removeMember(id, userId)` and `updateGroup(id, { name })` (else 403 `not_admin`). `createGroup({ name, member_ids, encrypted: true, device_id? })` makes an end-to-end encrypted group of people in the pilot, at most 8 counting pending invitees, or throws 409 `conversation_not_eligible` with `details.reason` and creates nothing. `r.realtime.onChatMembers` / `onChatConversation` tell you when people or the name change.
 
 ### r.e2ee — End-to-end encryption transport (flag-gated)
 
@@ -639,6 +639,19 @@ 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.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
@@ -685,7 +698,13 @@ the presign/PUT sequence in application code.
 
 Video: check `const { data } = await r.video.entitlement()` before offering the
 picker (`data.allowed`, `data.reason` 'tier' | 'quota', `data.remainingSeconds`),
-then `r.video.createUpload()`, which runs the same check.
+then `r.video.createUpload()`, which runs the same check. Upload in chunks
+(tus `chunkSize`) and keep the result for the attached file: a retry resumes the
+same video. The TUS signature lasts an hour; past it, call
+`r.video.renewUpload(playbackId, { grant: result.resumeGrant })` (0.7.63) for fresh
+credentials for the same video. 404 (not yours, expired grant, older API) or 409
+`upload_finished` means start a new upload instead. 503 means the video provider
+could not answer: keep the partial upload and ask again later (`Retry-After`).
 
 ### r.chat — Messaging
 
@@ -700,7 +719,7 @@ Methods: `conversations`, `communityConversation`, `conversation`, `messages`, `
 
 Scroll back with `messages(id, { cursor: page.meta.next_cursor })`, not a growing `offset`. Conversations carry `can_delete` / `can_leave`; check them before offering Delete or Leave.
 
-Private groups (0.7.59): each member has `role` (`admin` or `member`) and, in a group, `request_status`. Only the admin (the creator, then the longest-standing person left) may `addMembers(id, { member_ids })`, `removeMember(id, userId)` and `updateGroup(id, { name })` (else 403 `not_admin`). `createGroup({ name, member_ids, encrypted: true, device_id? })` makes an end-to-end encrypted group of people in the pilot, at most 8 counting pending invitees, or throws 409 `conversation_not_eligible` with `details.reason` and creates nothing. `r.realtime.onChatMembers` / `onChatConversation` tell you when people or the name change.
+Private groups (0.7.59): each member has `role` (`admin` or `member`) and, in a group or a one-on-one chat, `request_status`: `accepted` from the start for the person who wrote, anyone who follows them and agents, else `pending` until that person accepts or replies (a decline reads `pending` to anyone else), so `accepted` alone does not mean they accepted anything. Only the admin (the creator, then the longest-standing person left) may `addMembers(id, { member_ids })`, `removeMember(id, userId)` and `updateGroup(id, { name })` (else 403 `not_admin`). `createGroup({ name, member_ids, encrypted: true, device_id? })` makes an end-to-end encrypted group of people in the pilot, at most 8 counting pending invitees, or throws 409 `conversation_not_eligible` with `details.reason` and creates nothing. `r.realtime.onChatMembers` / `onChatConversation` tell you when people or the name change.
 
 ### r.tags
 
@@ -752,6 +771,7 @@ await r.appSubscriptions.changeTier({ tier: 'pro', proration_date: quote.prorati
   - 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`.
   - 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? })` (`compass: 'hide'` leaves out politics, 0.7.62); 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.
+  - Post language: a `SocialPost` may carry `language`, the lower-case primary subtag the post declares (`'de'`, `'en'`; Bluesky `langs[0]`, Mastodon `language`, a Nostr NIP-32 `ISO-639-1` label). It is absent when the post declares none (most Nostr notes) and on posts from the source index; it is never guessed and no post is dropped for it. Order by it (the viewer's language first, undeclared next), never filter on it.
   - `listCandidates({ protocol?, limit?, cursor? })` and `getCandidate(id)` are read-only quarantine review, not published-post search. Both require `admin` scope, a project-bound key, a live admin role, and existing project-admin access. The key supplies app/network scope; neither method accepts another project or network. They never invoke refresh, change settings, or publish.
   - Lists return `{ data: ProtocolQuarantinedCandidate[], meta: { limit, has_more, next_cursor } }`; use the opaque `next_cursor`, not offset pagination. The API defaults `limit` to 20 and permits at most 50. Details return `{ data: ProtocolQuarantinedCandidate }`. Every candidate has `state: 'quarantined'` and `content_format: 'plain'`; render its bounded `content` as text, respect `content_truncated`, and distinguish upstream `published_at` from local `observed_at` / `created_at`.
   - Safe source IDs are preserved byte-exact. `external_id: null` means unsafe or malformed provenance was withheld, not an invented ID; `author.native_id` may likewise be absent or withheld. Preserve nulls in both list and detail views, and use the candidate's own `id` for `getCandidate`.

package/package.json

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