@recursiv/sdk 0.7.59 → 0.7.63

package/README.md

@@ -96,10 +96,10 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | `r.posts` | `create`, `update`, `list`, `liked`, `bookmarked`, `bookmark`, `unbookmark`, `search`, `replies`, `react` |
 | `r.bookmarks` | `save`, `unsave`, `posts`, `list`, `keys`, `merge` — the member's saved posts, open-network posts and articles, synced across devices |
 | `r.communities` | `create`, `join`, `search`, `members` |
-| `r.chat` | `send`, `dm`, `createGroup`, `messages` (cursor paging), `acceptRequest`, `declineRequest`, `leave`, `deleteConversation` |
+| `r.chat` | `send`, `dm`, `createGroup` (`encrypted: true` for an end-to-end encrypted group, 0.7.59), `messages` (cursor paging), `acceptRequest`, `declineRequest`, `leave`, `deleteConversation`; a private group's admin: `addMembers`, `removeMember`, `updateGroup` (0.7.59) |
 | `r.tags` | `create`, `list` |
 | `r.uploads` | `uploadMedia` — upload post/chat bytes end to end |
-| `r.video` | `entitlement` (may the caller publish video, and how much is left), `createUpload`, `getStatus`, `getPlaybackToken` |
+| `r.video` | `entitlement` (may the caller publish video, and how much is left), `createUpload`, `renewUpload` (the creator's fresh TUS credentials for the same video, with `createUpload`'s `resumeGrant`, so a resume past the hour continues it; 0.7.63), `getStatus`, `getPlaybackToken` |
 
 ### Platform
 | Resource | Purpose |
@@ -653,8 +653,13 @@ sources; create a new session to refresh exhausted source windows. A topics netw
 (Bluesky) is read one topic page at a time; in a category the catalog's previews are not
 judged to be in it, so a read walks into the topics at once, and walks past a topic the
 provider no longer lists (`trend_unavailable`) or one with nothing in the category, up
-to five topic pages a read, so a page reaches a topic that carries posts. Any other
-failure marks the source failed until `retryFailed()`.
+to five topic pages a read, so a page reaches a topic that carries posts. A network read
+that fails for a passing reason (past the 15 s page deadline, a dropped connection, a 429
+or a 5xx) leaves the network out of that page and the next, named in `retryingSources`
+until a later page asks it again (from the page after, when its turn comes), up to two
+times in a row. Any other failure, or one past that, marks the source failed
+(`failedSources`) until `retryFailed()`. The Minds read is asked once and is never
+retried this way: any failure of it is in `failedSources` on that page.
 
 `sdk.discovery.createPersonalFeed({ networks, category?, learning?, recommend? })`
 builds the same kind of session for a member's For you tab: its Minds slot reads
@@ -671,6 +676,10 @@ Both take a Politics choice, `compass` (`all`, `mix`, `hide`, or cells in the or
 page carries its Minds read's answer as `page.compass` (`unavailable`: the page is unfiltered). Only Minds
 posts are filtered, so a view that leaves posts out reads best with `source: 'minds'`.
 The catalog lists `compass_filter` on every network when the filter is served to the viewer.
+Hide politics (`compass: 'hide'`) also applies on its own, with or without compass judgments on the server, to
+`sdk.discovery.videos`, `protocols.getPublicTrends` and the radar (`getPublicRadar`, keyless `getSharedRadar`; 0.7.62):
+it leaves out what is categorised politics (a story not themed yet, or `mixed`, too) and says what it did in
+`meta.compass_filter`. These reads answer a side or Mix unfiltered, marked `unavailable`.
 
 `sdk.discovery.recommendations({ kind, category?, limit?, session?, exclude? })` is
 the app's one recommender for suggestion rails: `kind` is `member`, `group`, `tag`,
@@ -690,14 +699,16 @@ history: every page's `meta.next` is `{ offset }`, `{ cursor }` or `null`, and w
 stage ends `meta.fallover` lists where to go, in order: `category_older` (the keyset
 cursor `next` also carries), `category_network` (the same category on the open
 networks), the member's next categories (`via` names the order they came from), `for_you`
-and `all`. A `DiscoveryFeedSession` follows the cursor itself and reports the Minds
-feed's `fallover` on its pages. `sdk.discovery.category({ category, session? })` answers a
+and `all`. A `feed` step (`ref`, the next feed's ref; 0.7.60) is declared but not sent yet:
+skip a kind your app cannot open. A `DiscoveryFeedSession` follows the cursor itself and
+reports the Minds feed's `fallover` on its pages, leaving out any step this SDK does not
+know or a malformed one. `sdk.discovery.category({ category, session? })` answers a
 category's surface in one call: `stories`, `network` and `clips` (each shared per app and
 category, refreshed after 30 s, kept up to 300 s and warmed as the warmer reaches the category, then filtered for the viewer on every call: the cached safety verdicts of story members, network posts and clips again, the term list, the viewer's blocks and mutes over clips, and the member's own hidden sources over network posts and story members) and the
 viewer's `people` and `groups`; a section that timed out, failed or is off is empty with a
 `reason` for that request only (a failure is never cached, so asking again retries it), and one this
 key may not read is empty with `refused` (`stories` and `network` need the member's own app
-key with `users:read`; `people` and `groups` need `users:read`). `sdk.discovery.videos({ category?, limit?, cursor?, offset? })`
+key with `users:read`; `people` and `groups` need `users:read`). `sdk.discovery.videos({ category?, limit?, cursor?, offset?, compass? })`
 is Watch's Minds read: the app's public video posts in hot order, from one list the server shares among every viewer of
 the app and rebuilds about once a minute, each post checked again on every call under the public floors and the viewer's
 blocks and mutes, in the `Post` shape with the viewer's own `user_reaction` and `reposted_by_viewer_id` (page on

package/dist/feed-definition.d.ts

@@ -0,0 +1,129 @@
+/**
+ * FeedDefinition v1, as apps read and write it: the one recipe behind every feed (a list of sources read as one union,
+ * a ranking mode, optional filters and exclusions). Types and constants only; the server
+ * (packages/server/src/features/feeds/FeedDefinition.ts) validates, canonicalises and digests a definition, and its
+ * FeedDefinitionSdkContract test holds these constants equal to its own.
+ *
+ * Nothing serves a definition yet: no route reads one before the cutover. Discover's built-in categories, All and
+ * For you are definitions held in code on the server (refs `builtin:category:<id>`, `builtin:all`, `builtin:for_you`).
+ *
+ * A definition never holds the viewer's safe/open setting, blocks or mutes, or a compass Mix or Choose-sides choice:
+ * `filters.politics: 'hide'` is the only Politics value a feed stores.
+ */
+export declare const FEED_DEFINITION_VERSION: 1;
+/** Sources a definition may name, read as one union. Only `builtin:all` and `builtin:for_you` have none. */
+export declare const FEED_SOURCES_MAX = 50;
+/** The largest canonical definition the server keeps, in bytes. */
+export declare const FEED_DEFINITION_MAX_BYTES: number;
+export declare const FEED_SOURCE_KINDS: readonly ["category", "tag", "account", "community", "collection", "list", "story", "bsky_feed", "bsky_list", "bsky_starterpack", "nostr_set"];
+export type FeedSourceKind = typeof FEED_SOURCE_KINDS[number];
+export declare const FEED_RANKING_MODES: readonly ["hot", "new", "top", "for_you", "viral"];
+export type FeedRankingMode = typeof FEED_RANKING_MODES[number];
+export declare const FEED_RANKING_RANGES: readonly ["24h", "7d", "30d", "1y"];
+export type FeedRankingRange = typeof FEED_RANKING_RANGES[number];
+export declare const FEED_MEDIA: readonly ["any", "images", "video", "longread"];
+export type FeedMedia = typeof FEED_MEDIA[number];
+export declare const FEED_NETWORKS: readonly ["minds", "bluesky", "activitypub", "nostr"];
+export type FeedNetwork = typeof FEED_NETWORKS[number];
+/** Source kinds a topical feed may hold (with a hot, new or top ranking); any other feed is 'wide'. */
+export declare const FEED_TOPICAL_SOURCE_KINDS: readonly ["category", "tag", "account", "community", "list", "collection", "story"];
+export declare const FEED_TOPICAL_MODES: readonly ["hot", "new", "top"];
+/** The one field that names what each source kind reads. */
+export declare const FEED_SOURCE_KEY: {
+    readonly category: "id";
+    readonly tag: "slug";
+    readonly account: "ref";
+    readonly community: "id";
+    readonly collection: "id";
+    readonly list: "id";
+    readonly story: "clusterId";
+    readonly bsky_feed: "uri";
+    readonly bsky_list: "uri";
+    readonly bsky_starterpack: "uri";
+    readonly nostr_set: "naddr";
+};
+/** An account by its native id: a Minds user, an atproto DID, a Nostr hex pubkey or a WebFinger account. */
+export type FeedAccountRef = `user:${string}` | `did:${string}` | `nostr:${string}` | `acct:${string}`;
+export type FeedSource = 
+/** A Discover category id, as `posts.categories()` lists them. */
+{
+    kind: 'category';
+    id: string;
+}
+/** A hashtag, without the `#`. */
+ | {
+    kind: 'tag';
+    slug: string;
+} | {
+    kind: 'account';
+    ref: FeedAccountRef;
+} | {
+    kind: 'community';
+    id: string;
+}
+/** A member's collection of saved posts, or a list (after the cutover). */
+ | {
+    kind: 'collection';
+    id: string;
+} | {
+    kind: 'list';
+    id: string;
+}
+/** A World Today story, by its radar cluster id. */
+ | {
+    kind: 'story';
+    clusterId: string;
+}
+/** Bluesky feeds, lists and starter packs by their at:// record URI (after the cutover). */
+ | {
+    kind: 'bsky_feed';
+    uri: string;
+} | {
+    kind: 'bsky_list';
+    uri: string;
+} | {
+    kind: 'bsky_starterpack';
+    uri: string;
+}
+/** A Nostr people, interest, bookmark or curation set by its NIP-19 naddr (after the cutover). */
+ | {
+    kind: 'nostr_set';
+    naddr: string;
+};
+export interface FeedRanking {
+    mode: FeedRankingMode;
+    range?: FeedRankingRange;
+}
+export interface FeedFilters {
+    /** Absent means any media. */
+    media?: FeedMedia;
+    /** Absent means every network. */
+    networks?: FeedNetwork[];
+    /** The only Politics value a feed stores. Mix and Choose sides stay the viewer's own. */
+    politics?: 'hide';
+    /** BCP 47 language tags such as `en` or `pt-br`; at most 10. */
+    languages?: string[];
+}
+export interface FeedExclude {
+    /** At most 50 tags. */
+    tags?: string[];
+    /** At most 50 accounts. */
+    accounts?: FeedAccountRef[];
+}
+export interface FeedDefinition {
+    v: typeof FEED_DEFINITION_VERSION;
+    /** 1 to 50, read as one union; empty only for `builtin:all` and `builtin:for_you`. */
+    sources: FeedSource[];
+    ranking: FeedRanking;
+    filters?: FeedFilters;
+    exclude?: FeedExclude;
+}
+export type BuiltinFeedRef = `builtin:category:${string}` | 'builtin:all' | 'builtin:for_you';
+/** A feed's address: a built-in, a member feed's current version (`feed:<uuid>`), or one version of it. */
+export type FeedRef = BuiltinFeedRef | `feed:${string}` | `feed:${string}@${number}`;
+/** Computed by the server, never stored: 'anon' feeds are ranked once and may be shared; 'viewer' feeds are ranked per viewer. */
+export type FeedAudience = 'anon' | 'viewer';
+/** Computed by the server: 'wide' feeds leave out Bluesky authors who asked not to be recommended. */
+export type FeedConsentClass = 'topical' | 'wide';
+/** The built-in feed for a Discover category. */
+export declare function builtinCategoryFeedRef(category: string): BuiltinFeedRef;

package/dist/feed-definition.js

@@ -0,0 +1,46 @@
+/**
+ * FeedDefinition v1, as apps read and write it: the one recipe behind every feed (a list of sources read as one union,
+ * a ranking mode, optional filters and exclusions). Types and constants only; the server
+ * (packages/server/src/features/feeds/FeedDefinition.ts) validates, canonicalises and digests a definition, and its
+ * FeedDefinitionSdkContract test holds these constants equal to its own.
+ *
+ * Nothing serves a definition yet: no route reads one before the cutover. Discover's built-in categories, All and
+ * For you are definitions held in code on the server (refs `builtin:category:<id>`, `builtin:all`, `builtin:for_you`).
+ *
+ * A definition never holds the viewer's safe/open setting, blocks or mutes, or a compass Mix or Choose-sides choice:
+ * `filters.politics: 'hide'` is the only Politics value a feed stores.
+ */
+export const FEED_DEFINITION_VERSION = 1;
+/** Sources a definition may name, read as one union. Only `builtin:all` and `builtin:for_you` have none. */
+export const FEED_SOURCES_MAX = 50;
+/** The largest canonical definition the server keeps, in bytes. */
+export const FEED_DEFINITION_MAX_BYTES = 16 * 1024;
+export const FEED_SOURCE_KINDS = [
+    'category', 'tag', 'account', 'community', 'collection', 'list', 'story',
+    'bsky_feed', 'bsky_list', 'bsky_starterpack', 'nostr_set',
+];
+export const FEED_RANKING_MODES = ['hot', 'new', 'top', 'for_you', 'viral'];
+export const FEED_RANKING_RANGES = ['24h', '7d', '30d', '1y'];
+export const FEED_MEDIA = ['any', 'images', 'video', 'longread'];
+export const FEED_NETWORKS = ['minds', 'bluesky', 'activitypub', 'nostr'];
+/** Source kinds a topical feed may hold (with a hot, new or top ranking); any other feed is 'wide'. */
+export const FEED_TOPICAL_SOURCE_KINDS = ['category', 'tag', 'account', 'community', 'list', 'collection', 'story'];
+export const FEED_TOPICAL_MODES = ['hot', 'new', 'top'];
+/** The one field that names what each source kind reads. */
+export const FEED_SOURCE_KEY = {
+    category: 'id',
+    tag: 'slug',
+    account: 'ref',
+    community: 'id',
+    collection: 'id',
+    list: 'id',
+    story: 'clusterId',
+    bsky_feed: 'uri',
+    bsky_list: 'uri',
+    bsky_starterpack: 'uri',
+    nostr_set: 'naddr',
+};
+/** The built-in feed for a Discover category. */
+export function builtinCategoryFeedRef(category) {
+    return `builtin:category:${category}`;
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from './resources/discovery-learning.js';
 import { DiscoveryResource } from './resources/discovery.js';
 export * from './resources/discovery.js';
+export * from './feed-definition.js';
 import { AuthResource } from './resources/auth.js';
 import { PostsResource } from './resources/posts.js';
 import { UsersResource } from './resources/users.js';
@@ -234,7 +235,7 @@ export type { Brief, BriefEmail, MyBrief, MyBriefEntry, BriefParams, BriefShippe
 export type { HumanAsk, HumanAskStatus, CreateHumanAskInput, ListHumanAsksParams } from './resources/human-asks.js';
 export { HumanInputResource } from './resources/human-input.js';
 export type { Goal, GoalTask, CreateGoalInput, UpdateGoalInput, ListGoalsParams, ReorderGoalTasksInput } from './resources/goals.js';
-export type { DispatcherTask, TaskClaim, ClaimRecord, DispatcherStats, CreateTaskInput, UpdateTaskInput, ListTasksParams, SignalRecord, OutcomeRecord, PauseState, PauseInput, SignalsParams, OutcomesParams, DiscoveryParams, StaleStuckParams } from './resources/dispatcher.js';
+export type { DispatcherTask, TaskClaim, ClaimRecord, DispatcherStats, CreateTaskInput, UpdateTaskInput, ListTasksParams, SignalRecord, OutcomeRecord, PauseState, PauseInput, SignalsParams, OutcomesParams, DiscoveryParams, StaleStuckParams, TaskPlan, TaskPlanStep, SetTaskPlanInput, UpdateTaskPlanStepInput } from './resources/dispatcher.js';
 export { SwarmsResource } from './resources/swarms.js';
 export type { Swarm, SwarmMember, CreateSwarmInput, ListSwarmsParams, ScheduledTask, ScheduleTaskInput } from './resources/swarms.js';
 export { TemplatesResource } from './resources/templates.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from './resources/discovery-learning.js';
 import { DiscoveryResource } from './resources/discovery.js';
 export * from './resources/discovery.js';
+export * from './feed-definition.js';
 import { HttpClient } from './client.js';
 import { AuthResource } from './resources/auth.js';
 import { PostsResource } from './resources/posts.js';

package/dist/realtime.d.ts

@@ -1,6 +1,7 @@
 import type { Socket } from 'socket.io-client';
 import { HttpClient } from './client.js';
 import type { E2eeDevicesRealtimeEvent, E2eeLinkRealtimeEvent, E2eeRealtimeEvent } from './resources/e2ee.js';
+import type { ChatConversationEvent, ChatMembersEvent } from './types.js';
 export interface ChatMessageEvent {
     id: string;
     conversationId: string;
@@ -147,7 +148,8 @@ export declare class RealtimeClient {
      *
      * Server events include `notification`, `feed_update`,
      * `conversation_created`, `chat_message`, `chat_typing`, `agent_thinking`,
-     * `e2ee:event`, `e2ee:link` and `e2ee:devices`.
+     * `chat:members`, `chat:conversation`, `e2ee:event`, `e2ee:link` and
+     * `e2ee:devices`.
      */
     on<T = unknown>(event: string, listener: (payload: T) => void): () => void;
     /** Join a conversation room now, and again after every reconnect, until you leave it. */
@@ -159,6 +161,14 @@ export declare class RealtimeClient {
     onMessageDelete(callback: (msg: ChatMessageDeleteEvent) => void): (() => void) | undefined;
     onTyping(callback: (event: TypingEvent) => void): (() => void) | undefined;
     onAgentThinking(callback: (event: AgentThinkingEvent) => void): (() => void) | undefined;
+    /**
+     * A private group's people changed (0.7.59): `{ conversationId, change, userIds, actorId }`,
+     * change `added`, `removed`, `left` or `invites_cancelled`. Sent to everyone in the group
+     * and to the people it is about. Read the conversation again; in an encrypted group, check its keys.
+     */
+    onChatMembers(callback: (event: ChatMembersEvent) => void): () => void;
+    /** A private group was renamed (0.7.59): `{ conversationId, change: 'renamed', name, actorId }`. */
+    onChatConversation(callback: (event: ChatConversationEvent) => void): () => void;
     /**
      * The E2EE doorbell after each append to an encrypted conversation this
      * account belongs to: `{ conversationId, seq }`, plus the stored `event`

package/dist/realtime.js

@@ -369,7 +369,8 @@ export class RealtimeClient {
      *
      * Server events include `notification`, `feed_update`,
      * `conversation_created`, `chat_message`, `chat_typing`, `agent_thinking`,
-     * `e2ee:event`, `e2ee:link` and `e2ee:devices`.
+     * `chat:members`, `chat:conversation`, `e2ee:event`, `e2ee:link` and
+     * `e2ee:devices`.
      */
     on(event, listener) {
         // Every call is its own subscription, even for a function that is already
@@ -426,6 +427,18 @@ export class RealtimeClient {
     onAgentThinking(callback) {
         return this.on('agent_thinking', callback);
     }
+    /**
+     * A private group's people changed (0.7.59): `{ conversationId, change, userIds, actorId }`,
+     * change `added`, `removed`, `left` or `invites_cancelled`. Sent to everyone in the group
+     * and to the people it is about. Read the conversation again; in an encrypted group, check its keys.
+     */
+    onChatMembers(callback) {
+        return this.on('chat:members', callback);
+    }
+    /** A private group was renamed (0.7.59): `{ conversationId, change: 'renamed', name, actorId }`. */
+    onChatConversation(callback) {
+        return this.on('chat:conversation', callback);
+    }
     /**
      * The E2EE doorbell after each append to an encrypted conversation this
      * account belongs to: `{ conversationId, seq }`, plus the stored `event`

package/dist/resources/chat.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../client.js';
-import type { PaginatedResponse, SingleResponse, SuccessResponse, Conversation, ConversationDetail, Message, SendMessageInput, SentMessage, DmInput, DmResult, PaginationParams, ConversationRequestResult, LeaveConversationResult } from '../types.js';
+import type { PaginatedResponse, SingleResponse, SuccessResponse, Conversation, ConversationDetail, Message, SendMessageInput, SentMessage, DmInput, DmResult, PaginationParams, ConversationRequestResult, LeaveConversationResult, CreateGroupInput, AddGroupMembersResult, RemoveGroupMemberResult, UpdateGroupResult } from '../types.js';
 export declare class ChatResource {
     private client;
     constructor(client: HttpClient);
@@ -37,11 +37,42 @@ export declare class ChatResource {
     }): Promise<SingleResponse<SentMessage>>;
     /** Get or create a DM conversation with a user */
     dm(input: DmInput): Promise<SingleResponse<DmResult>>;
-    /** Create a group conversation */
-    createGroup(input: {
-        name: string;
+    /**
+     * Create a group conversation. Invitees who do not follow you get it as a
+     * message request (`request_status: 'pending'`); you are its admin
+     * (`role: 'admin'`).
+     *
+     * `encrypted: true` (0.7.59) creates an end-to-end encrypted private group:
+     * people only, all inside the encryption pilot, at most 8 counting you.
+     * Otherwise it throws 409 `conversation_not_eligible` with `details.reason`
+     * (EncryptedGroupRefusalReason) and creates nothing: never a plaintext group
+     * instead. Pass `device_id` when you have an encrypted-chat device; your
+     * device then sets up the group's keys (only the admin's device may).
+     */
+    createGroup(input: CreateGroupInput): Promise<SingleResponse<ConversationDetail>>;
+    /**
+     * Add people to a private group (0.7.59). Only its admin may (403
+     * `not_admin`). Someone who does not follow you is added as a message
+     * request (`pending`); someone already in it is listed in
+     * `already_members`. In an encrypted group the group's rule must still
+     * hold afterwards, or nobody is added (409 `conversation_not_eligible`,
+     * `details.reason`); a plaintext group holds at most 101 people (409 `group_full`).
+     * Everyone in the group gets the realtime `chat:members` event.
+     */
+    addMembers(conversationId: string, input: {
         member_ids: string[];
-    }): Promise<SingleResponse<ConversationDetail>>;
+    }): Promise<SingleResponse<AddGroupMembersResult>>;
+    /**
+     * Remove someone from a private group, or cancel their invite (0.7.59).
+     * Only its admin may (403 `not_admin`); to remove yourself, `leave()` (409
+     * `use_leave`). They lose the conversation at once; in an encrypted group
+     * the members' devices then take them out of its keys before sending again.
+     */
+    removeMember(conversationId: string, userId: string): Promise<SingleResponse<RemoveGroupMemberResult>>;
+    /** Rename a private group (0.7.59). Only its admin may (403 `not_admin`). */
+    updateGroup(conversationId: string, input: {
+        name: string;
+    }): Promise<SingleResponse<UpdateGroupResult>>;
     /**
      * Delete a conversation for every member. Allowed when the conversation's
      * `can_delete` is true: the caller started it, or every other member is an
@@ -53,7 +84,10 @@ export declare class ChatResource {
      * Remove the caller from a conversation (a group, or a room whose other
      * members are all agents). The last person to leave removes the room. A
      * one-on-one with another person cannot be left (409 `dm_leave_unsupported`);
-     * check `can_leave` on the conversation first.
+     * check `can_leave` on the conversation first. When a group's admin leaves,
+     * the longest-standing person left becomes its admin; in an encrypted group
+     * the invites the admin sent that nobody accepted are cancelled
+     * (`invites_cancelled`).
      *
      * This changes membership. It is not `realtime.leaveConversation()`, which
      * only stops listening for live events.

package/dist/resources/chat.js

@@ -44,10 +44,46 @@ export class ChatResource {
     dm(input) {
         return this.client.post('/chat/dm', input);
     }
-    /** Create a group conversation */
+    /**
+     * Create a group conversation. Invitees who do not follow you get it as a
+     * message request (`request_status: 'pending'`); you are its admin
+     * (`role: 'admin'`).
+     *
+     * `encrypted: true` (0.7.59) creates an end-to-end encrypted private group:
+     * people only, all inside the encryption pilot, at most 8 counting you.
+     * Otherwise it throws 409 `conversation_not_eligible` with `details.reason`
+     * (EncryptedGroupRefusalReason) and creates nothing: never a plaintext group
+     * instead. Pass `device_id` when you have an encrypted-chat device; your
+     * device then sets up the group's keys (only the admin's device may).
+     */
     createGroup(input) {
         return this.client.post('/chat/conversations/group', input);
     }
+    /**
+     * Add people to a private group (0.7.59). Only its admin may (403
+     * `not_admin`). Someone who does not follow you is added as a message
+     * request (`pending`); someone already in it is listed in
+     * `already_members`. In an encrypted group the group's rule must still
+     * hold afterwards, or nobody is added (409 `conversation_not_eligible`,
+     * `details.reason`); a plaintext group holds at most 101 people (409 `group_full`).
+     * Everyone in the group gets the realtime `chat:members` event.
+     */
+    addMembers(conversationId, input) {
+        return this.client.post(`/chat/conversations/${conversationId}/members`, input);
+    }
+    /**
+     * Remove someone from a private group, or cancel their invite (0.7.59).
+     * Only its admin may (403 `not_admin`); to remove yourself, `leave()` (409
+     * `use_leave`). They lose the conversation at once; in an encrypted group
+     * the members' devices then take them out of its keys before sending again.
+     */
+    removeMember(conversationId, userId) {
+        return this.client.delete(`/chat/conversations/${conversationId}/members/${userId}`);
+    }
+    /** Rename a private group (0.7.59). Only its admin may (403 `not_admin`). */
+    updateGroup(conversationId, input) {
+        return this.client.patch(`/chat/conversations/${conversationId}`, input);
+    }
     /**
      * Delete a conversation for every member. Allowed when the conversation's
      * `can_delete` is true: the caller started it, or every other member is an
@@ -61,7 +97,10 @@ export class ChatResource {
      * Remove the caller from a conversation (a group, or a room whose other
      * members are all agents). The last person to leave removes the room. A
      * one-on-one with another person cannot be left (409 `dm_leave_unsupported`);
-     * check `can_leave` on the conversation first.
+     * check `can_leave` on the conversation first. When a group's admin leaves,
+     * the longest-standing person left becomes its admin; in an encrypted group
+     * the invites the admin sent that nobody accepted are cancelled
+     * (`invites_cancelled`).
      *
      * This changes membership. It is not `realtime.leaveConversation()`, which
      * only stops listening for live events.

package/dist/resources/discovery.d.ts

@@ -15,6 +15,13 @@ export interface WatchVideosParams {
     cursor?: string;
     /** A position in the list to start a first read at (0 to 400); a later page sends `cursor`. */
     offset?: number;
+    /**
+     * A Politics choice, spelled as `posts.list` takes it. Only Hide politics (`hide`) is applied here: the videos whose
+     * browse category is politics (or whose compass judgment places them in politics) leave the page and the next ones
+     * fill it, with or without compass judgments on the server. A side or Mix is answered unfiltered, marked
+     * `unavailable`. The page says what it did in `meta.compass_filter`.
+     */
+    compass?: string;
 }
 /** A media item as `discovery.videos` serves it: the poster, and the player's size, length and HLS address when known. */
 export interface WatchVideoMedia extends MediaItem {
@@ -62,6 +69,8 @@ export interface WatchVideosResponse {
         built_at: string | null;
         /** `no_app`: the API key is bound to no app, so there is no list. */
         reason?: 'no_app';
+        /** Present when the request named a filtering `compass`: what the Politics choice did to this page. */
+        compass_filter?: CompassFilterMeta;
     };
 }
 /** What GET /discover/recommendations suggests: members, groups, tags, open-network accounts or World Today stories. */
@@ -306,6 +315,23 @@ export declare const isDiscoveryPost: (item: DiscoveryItem) => item is Discovery
 export declare const RECOMMENDATION_MAX_ITEMS = 6;
 /** Clusters read from the radar per session; the server never holds more. */
 export declare const RADAR_MAX_CLUSTERS = 40;
+/** How long one source's read may take before the page goes on without it (DiscoveryFeedSession). */
+export declare const DISCOVERY_SOURCE_TIMEOUT_MS = 15000;
+/**
+ * Times in a row an open network whose read failed for a passing reason (a timeout, a dropped connection, a 429 or a
+ * 5xx) sits out one page and is asked again, before it is left out until `retryFailed()`. Before, one such failure left
+ * the network out of the rest of the session: one Bluesky blip and Watch or Discover never read Bluesky again. The Minds
+ * read is not retried this way: its failure is named in `failedSources` at once (#4047), which the Minds app shows as
+ * "Minds posts didn't load" with Try again and which its Politics fallback (minds#1212) waits for.
+ */
+export declare const DISCOVERY_SOURCE_RETRIES = 2;
+/**
+ * Whether a source's read failed for a reason that passes: it ran past its deadline, its call never got an answer (a
+ * failed connection or an abort, as the session's read reports it), or the server answered 408, 425, 429 or 5xx (or no
+ * status at all, 0). A response the session refuses (the wrong shape or protocol, including a TypeError thrown while
+ * checking it) and any other 4xx are the source's own failure and are not asked again.
+ */
+export declare function transientSourceFailure(error: unknown): boolean;
 /** json-render Spec: values are references to authenticated SDK results, never
  * arbitrary executable components, links, generated text or provider markup. */
 export interface DiscoveryModule {
@@ -331,7 +357,17 @@ export interface DiscoveryModule {
 export interface DiscoveryFeedPage {
     modules: DiscoveryModule[];
     hasMore: boolean;
+    /**
+     * Sources left out of the rest of the session (until `retryFailed()`): any failed Minds read (#4047), a network read
+     * the session refused, or a network's passing failures past DISCOVERY_SOURCE_RETRIES.
+     */
     failedSources: string[];
+    /**
+     * Open networks whose read failed for a passing reason (a timeout, a dropped connection, a 429 or a 5xx): missing from
+     * this page and the next, and named here until a later page asks them again (from the page after the next, when the
+     * round-robin reaches them). Never 'minds'. Absent when there are none, and on SDKs that predate it.
+     */
+    retryingSources?: string[];
     partialCategories: boolean;
     /**
      * The Minds feed's fall-through, once its category feed has ended a stage (the server's

package/dist/resources/discovery.js

@@ -32,6 +32,53 @@ const TOPIC_WALK_MS = 8000;
  * new counts as an empty topic.
  */
 const INDEX_CURSOR = 'idx:tf:';
+/** How long one source's read may take before the page goes on without it (DiscoveryFeedSession). */
+export const DISCOVERY_SOURCE_TIMEOUT_MS = 15_000;
+/**
+ * Times in a row an open network whose read failed for a passing reason (a timeout, a dropped connection, a 429 or a
+ * 5xx) sits out one page and is asked again, before it is left out until `retryFailed()`. Before, one such failure left
+ * the network out of the rest of the session: one Bluesky blip and Watch or Discover never read Bluesky again. The Minds
+ * read is not retried this way: its failure is named in `failedSources` at once (#4047), which the Minds app shows as
+ * "Minds posts didn't load" with Try again and which its Politics fallback (minds#1212) waits for.
+ */
+export const DISCOVERY_SOURCE_RETRIES = 2;
+/** The page deadline a source's read ran past. */
+class SourceTimedOut extends Error {
+    constructor() { super('Discovery source timed out'); this.name = 'SourceTimedOut'; }
+}
+/** A source's own call that never got an answer: the connection failed (fetch's TypeError) or was aborted. */
+class SourceUnreachable extends Error {
+    reason;
+    constructor(reason) {
+        super('Discovery source unreachable');
+        this.reason = reason;
+        this.name = 'SourceUnreachable';
+    }
+}
+/**
+ * A source's own call, with a failed connection told apart from a TypeError thrown while checking its answer (an
+ * answer with no `items` throws one at `data.items.length`): only the call's own TypeError or abort is unreachable.
+ */
+function reach(call) {
+    return call.catch((error) => {
+        const name = typeof error === 'object' && error !== null ? error.name : undefined;
+        throw name === 'TypeError' || name === 'AbortError' || name === 'TimeoutError' ? new SourceUnreachable(error) : error;
+    });
+}
+/**
+ * Whether a source's read failed for a reason that passes: it ran past its deadline, its call never got an answer (a
+ * failed connection or an abort, as the session's read reports it), or the server answered 408, 425, 429 or 5xx (or no
+ * status at all, 0). A response the session refuses (the wrong shape or protocol, including a TypeError thrown while
+ * checking it) and any other 4xx are the source's own failure and are not asked again.
+ */
+export function transientSourceFailure(error) {
+    if (error instanceof SourceTimedOut || error instanceof SourceUnreachable)
+        return true;
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const { status } = error;
+    return typeof status === 'number' && (status === 0 || status === 408 || status === 425 || status === 429 || status >= 500);
+}
 const RECOMMENDATION_KINDS = ['groups', 'people', 'tags'];
 const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0 && value.length <= 512;
 function recommendationItem(kind, candidate) {
@@ -121,6 +168,32 @@ function radarCluster(value) {
     return { id: c.id, label: c.label.slice(0, 300), kind: c.kind, ...(theme ? { theme } : {}), outletCount: mainstream + independent, laneMix: { mainstream, independent }, sources,
         velocity: { normalized: typeof normalized === 'number' && Number.isFinite(normalized) && normalized >= 0 ? normalized : 0 }, newestAt, ...(lead ? { lead } : {}), links, memberKeys };
 }
+const FALLOVER_VIA = new Set(['personal', 'popular', 'static']);
+const filled = (value) => typeof value === 'string' && value.length > 0;
+/**
+ * The Minds read's `meta.fallover`, step by step. A step of a kind this SDK knows (`feed` included, 0.7.60) that carries
+ * the fields its kind declares is kept as the server sent it; a step of a kind a later server added, or a malformed
+ * one, is left out and never guessed at, so every step a page reports is a FalloverStep. Undefined when the page has
+ * no list (a server before the contract, or a feed that is not a category's).
+ */
+function readFallover(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value.filter((raw) => {
+        if (!raw || typeof raw !== 'object')
+            return false;
+        const step = raw;
+        switch (step.kind) {
+            case 'category_older': return filled(step.category) && filled(step.cursor);
+            case 'category_network': return filled(step.category);
+            case 'category': return filled(step.category) && typeof step.via === 'string' && FALLOVER_VIA.has(step.via);
+            case 'for_you':
+            case 'all': return true;
+            case 'feed': return filled(step.ref);
+            default: return false;
+        }
+    });
+}
 const ordinary = { version: 'discovery-layout-v1', presentation: 'posts', source: 'fallback' };
 const key = (protocol, id) => JSON.stringify([protocol, id]);
 const presentations = new Set(['posts', 'visual', 'conversation', 'video', 'thread', 'longread']);
@@ -175,8 +248,11 @@ export class DiscoveryFeedSession {
         this.streams = ['minds', ...sources].filter(protocol => !source || source === 'all' || source === protocol)
             .map(protocol => ({ protocol, offset: 0, done: false, failed: false, used: [] }));
     }
-    retryFailed() { for (const stream of this.streams)
-        stream.failed = false; }
+    retryFailed() { for (const stream of this.streams) {
+        stream.failed = false;
+        stream.failures = 0;
+        stream.retryAt = undefined;
+    } }
     next() {
         if (this.pending)
             return this.pending;
@@ -204,8 +280,9 @@ export class DiscoveryFeedSession {
                 stream.used = [...stream.used, stream.cursor].slice(-32);
             stream.cursor = next;
             // A category feed that ended a stage says where to go next; kept on the stream and reported on every page from here.
-            if (Array.isArray(response.meta.fallover))
-                stream.fallover = response.meta.fallover;
+            const fallover = readFallover(response.meta.fallover);
+            if (fallover)
+                stream.fallover = fallover;
             return { items: response.data.map(post => ({ key: key('minds', post.id), kind: 'minds', post })),
                 layout: response.meta.discovery ?? ordinary, partial: response.meta.category_filter?.status === 'partial',
                 ...(response.meta.compass_filter ? { compass: response.meta.compass_filter } : {}) };
@@ -217,7 +294,7 @@ export class DiscoveryFeedSession {
         const started = Date.now();
         if (stream.topics)
             return this.walkTopics(stream, params, validatePosts, false, started);
-        const { data } = await this.protocols.getPublicTrends({ ...params, protocol: stream.protocol, cursor: stream.cursor, includePreviews: true }, NO_RETRY);
+        const { data } = await reach(this.protocols.getPublicTrends({ ...params, protocol: stream.protocol, cursor: stream.cursor, includePreviews: true }, NO_RETRY));
         if (data.coverage !== 'provider_ranked_window' || data.items.length > 25 || data.items.some(item => item.protocol !== stream.protocol))
             throw new Error('Invalid discovery source response');
         if (data.kind === 'topics') {
@@ -260,7 +337,7 @@ export class DiscoveryFeedSession {
             // continuation, not the network: the stream may start again from a later topic's page. A provider topic
             // read that fails any other way than gone is still the network's failure.
             const indexContinuation = !!topic.cursor?.startsWith(INDEX_CURSOR);
-            const response = await this.protocols.getPublicTrendFeed({ ...params, protocol: stream.protocol, topic: topic.topic, cursor: topic.cursor }, NO_RETRY)
+            const response = await reach(this.protocols.getPublicTrendFeed({ ...params, protocol: stream.protocol, topic: topic.topic, cursor: topic.cursor }, NO_RETRY))
                 .catch((error) => {
                 if (isGone(error))
                     return null;
@@ -305,11 +382,18 @@ export class DiscoveryFeedSession {
             void this.radarLoading.then(clusters => { const lead = this.pickCluster(clusters, 0); if (lead)
                 void this.memberPosts(lead); });
         }
-        const active = this.streams.filter(stream => !stream.done && !stream.failed);
+        // A network that failed for a passing reason sat out the page after its failure; from this one it takes its turn
+        // again. It stays failed, and named in retryingSources, until a page asks it: with more than three networks the
+        // round-robin may pass it over on the page it is due (Codex review of #4037).
+        const active = this.streams.filter(stream => !stream.done && (!stream.failed || (stream.retryAt !== undefined && this.page >= stream.retryAt)));
         const native = active.find(stream => stream.protocol === 'minds');
         const remote = active.filter(stream => stream.protocol !== 'minds');
         const selected = [...(native ? [native] : []), ...Array.from({ length: Math.min(native ? 3 : 4, remote.length) }, (_, index) => remote[(this.nextSource + index) % remote.length])];
         this.nextSource += 3;
+        for (const stream of selected) {
+            stream.failed = false;
+            stream.retryAt = undefined;
+        }
         const reads = await Promise.all(selected.map(async (stream) => {
             // Commit continuation state only if this page finishes within its UI
             // deadline. A late provider cannot move the cursor past unseen content.
@@ -317,14 +401,21 @@ export class DiscoveryFeedSession {
             let cancel = () => { };
             try {
                 const read = await Promise.race([this.read(candidate), new Promise((_resolve, reject) => {
-                        const timer = setTimeout(() => reject(new Error('Discovery source timed out')), 15000);
+                        const timer = setTimeout(() => reject(new SourceTimedOut()), DISCOVERY_SOURCE_TIMEOUT_MS);
                         cancel = () => clearTimeout(timer);
                     })]);
                 Object.assign(stream, candidate);
+                stream.failures = 0;
                 return read;
             }
-            catch {
+            catch (error) {
+                // A network's passing failure sits out the next page and is asked again from the one after, up to
+                // DISCOVERY_SOURCE_RETRIES times in a row; any other failure, or one past that, leaves the source out until
+                // retryFailed(). The Minds read fails at once, whatever the reason (#4047): the app's "Minds posts didn't load"
+                // notice, its Try again and its Politics fallback (minds#1212) all wait for 'minds' in failedSources.
                 stream.failed = true;
+                stream.failures = (stream.failures ?? 0) + 1;
+                stream.retryAt = stream.protocol !== 'minds' && transientSourceFailure(error) && stream.failures <= DISCOVERY_SOURCE_RETRIES ? this.page + 2 : undefined;
                 return { items: [], layout: ordinary, partial: false };
             }
             finally {
@@ -410,8 +501,10 @@ export class DiscoveryFeedSession {
         const fallover = this.streams.find(stream => stream.protocol === 'minds')?.fallover;
         // Only the Minds read carries what a Politics choice did (the open networks' reads are not filtered by it).
         const compass = reads.find(read => read.compass)?.compass;
-        return { modules, hasMore: this.streams.some(stream => !stream.done && !stream.failed),
-            failedSources: this.streams.filter(stream => stream.failed).map(stream => stream.protocol), partialCategories: reads.some(read => read.partial),
+        const retrying = this.streams.filter(stream => stream.failed && stream.retryAt !== undefined).map(stream => stream.protocol);
+        return { modules, hasMore: this.streams.some(stream => !stream.done && (!stream.failed || stream.retryAt !== undefined)),
+            failedSources: this.streams.filter(stream => stream.failed && stream.retryAt === undefined).map(stream => stream.protocol),
+            ...(retrying.length ? { retryingSources: retrying } : {}), partialCategories: reads.some(read => read.partial),
             ...(fallover ? { fallover } : {}), ...(compass ? { compass } : {}) };
     }
     /** Page 0: the top breaking cluster, else the top cluster. Every second later page: the next unused story or viral cluster. */

package/dist/resources/dispatcher.d.ts

@@ -1,5 +1,54 @@
 import type { HttpClient } from '../client.js';
 import type { SingleResponse, DeleteResponse, PaginationParams } from '../types.js';
+/** One step of a task's plan, as the checklist card shows it. */
+export interface TaskPlanStep {
+    position: number;
+    title: string;
+    status: 'pending' | 'in_progress' | 'done' | 'skipped' | 'blocked';
+    /** Why a step is blocked or was skipped. */
+    reason: string | null;
+    /** The specialist agent doing the step. */
+    agent: {
+        id: string;
+        name: string;
+    } | null;
+    /** The approval or question a blocked step waits on, in the plan's conversation. */
+    waitingOn: {
+        executionId: string | null;
+        messageId: string | null;
+    } | null;
+    startedAt: string | null;
+    finishedAt: string | null;
+}
+export interface TaskPlan {
+    taskId: string;
+    title: string;
+    /** The chat the plan's card lives in. */
+    conversationId: string | null;
+    steps: TaskPlanStep[];
+}
+export interface SetTaskPlanInput {
+    agent?: string;
+    /** The chat to post the card in. Only the first plan that names one posts it. */
+    conversation_id?: string | null;
+    steps: Array<{
+        title: string;
+        agent_id?: string | null;
+    }>;
+    organization_id?: string;
+}
+export interface UpdateTaskPlanStepInput {
+    agent?: string;
+    status: TaskPlanStep['status'];
+    title?: string;
+    /** Kept only for 'blocked' and 'skipped'. */
+    reason?: string | null;
+    /** Only for 'blocked': the approval it waits on. */
+    waiting_on_execution_id?: string | null;
+    /** Only for 'blocked': the question message it waits on. */
+    waiting_on_message_id?: string | null;
+    organization_id?: string;
+}
 export interface DispatcherTask {
     id: string;
     title: string;
@@ -275,6 +324,13 @@ export declare class DispatcherResource {
     }): Promise<SingleResponse<{
         ok: true;
     }>>;
+    /**
+     * Write a claimed task's step plan (the checklist card). Replaces every step
+     * that has not finished; done and skipped steps stay. Requires the claim.
+     */
+    setPlan(taskId: string, input: SetTaskPlanInput): Promise<SingleResponse<TaskPlan>>;
+    /** Move one step of a claimed task's plan. Started and finished times are stamped server-side. */
+    updatePlanStep(taskId: string, position: number, input: UpdateTaskPlanStepInput): Promise<SingleResponse<TaskPlan>>;
     /**
      * Mark a task as done. A task with a thresholded check that has no passing
      * run refuses with 409 and the failing check names — run

package/dist/resources/dispatcher.js

@@ -28,6 +28,19 @@ export class DispatcherResource {
         const { organization_id, ...body } = input;
         return this.client.post(`/dispatcher/heartbeat/${encodeURIComponent(taskId)}${orgQuery(organization_id)}`, body);
     }
+    /**
+     * Write a claimed task's step plan (the checklist card). Replaces every step
+     * that has not finished; done and skipped steps stay. Requires the claim.
+     */
+    setPlan(taskId, input) {
+        const { organization_id, ...body } = input;
+        return this.client.put(`/dispatcher/tasks/${encodeURIComponent(taskId)}/plan${orgQuery(organization_id)}`, body);
+    }
+    /** Move one step of a claimed task's plan. Started and finished times are stamped server-side. */
+    updatePlanStep(taskId, position, input) {
+        const { organization_id, ...body } = input;
+        return this.client.patch(`/dispatcher/tasks/${encodeURIComponent(taskId)}/plan/steps/${position}${orgQuery(organization_id)}`, body);
+    }
     /**
      * Mark a task as done. A task with a thresholded check that has no passing
      * run refuses with 409 and the failing check names — run

package/dist/resources/e2ee.d.ts

@@ -95,9 +95,13 @@ export interface E2eeEvent {
  * quiet one; never a commit, never a Welcome, never one whose envelope is over
  * 16 KB), and only on a socket whose credential could read it with `events()`:
  * one authenticated by the account owner's session or by an owner key whose
- * app or organization binding reaches the conversation. A socket opened with
- * an agent-scoped key gets the content-free form only. When present it is the
- * stored event exactly as `events()` returns it, JSON byte for byte.
+ * app or organization binding reaches the conversation, once that sign-in has
+ * called `registerDevice`, `publishKeyPackages`, `keyPackageStatus`,
+ * `events`, `acknowledge` or `appendEvent` for one of the account's active
+ * devices since the socket connected, as a sync after connecting does. A
+ * socket opened with an agent-scoped key, or whose sign-in spoke only for a
+ * device since revoked, gets the content-free form only. When present it is
+ * the stored event exactly as `events()` returns it, JSON byte for byte.
  *
  * With the shared engine, hand `event` to `applyPushed(conversationId, event)`
  * on the device session: it applies the event without a relay read when it is

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;
@@ -1120,7 +1127,12 @@ export type SocialTrends = SocialTrendProvenance & ({
     safetyFilter?: {
         withheld: number;
     };
-});
+}) & {
+    /** Present when `getPublicTrends` named a filtering `compass`: what Hide politics did to this page (counts only). */
+    meta?: {
+        compass_filter?: CompassFilterMeta;
+    };
+};
 export interface SocialTrendFeed extends SocialTrendProvenance {
     trend: SocialTrend;
     items: SocialPost[];
@@ -1246,10 +1258,20 @@ export interface SocialRadar {
         selected: string;
         status: 'complete' | 'partial';
     };
+    /** Present when the read named a filtering `compass`: what Hide politics did to the stories listed (counts only). */
+    meta?: {
+        compass_filter?: CompassFilterMeta;
+    };
 }
 export interface SocialRadarParams {
     category?: string;
     limit?: number;
+    /**
+     * A Politics choice. Hide politics (`hide`) leaves out the stories whose theme is politics, and the ones not themed yet
+     * or themed `mixed` (a story has no compass placement, so it fails closed); the stories after them fill the list.
+     * A side or Mix is answered unfiltered, marked `unavailable`; the keyless `getSharedRadar` takes only `all` or `hide`.
+     */
+    compass?: string;
 }
 /** One radar story's social member posts, in the cluster's member order. Empty once the story leaves the snapshot. */
 export interface SocialRadarPosts {
@@ -1643,7 +1665,10 @@ export declare class ProtocolsResource {
     }): Promise<SingleResponse<SocialConversation>>;
     /**
      * Current provider-ranked topics or posts, with explicit source and coverage. Does not ingest content.
-     * Every page, previews included, gets the safety floor; `discovery` only asks for a layout.
+     * Every page, previews included, gets the safety floor; `discovery` only asks for a layout. `compass` (a Politics
+     * choice, spelled as `posts.list` takes it): Hide politics (`hide`) leaves out the topics and posts whose cached
+     * browse category is politics, where the filter is served to the member; a side or Mix is answered unfiltered. The
+     * page then says what it did in `meta.compass_filter`.
      */
     getPublicTrends(params: {
         protocol: string;
@@ -1652,6 +1677,7 @@ export declare class ProtocolsResource {
         includePreviews?: boolean;
         category?: string;
         discovery?: boolean;
+        compass?: string;
     }, options?: SocialReadOptions): Promise<SingleResponse<SocialTrends>>;
     /** Open a topic currently listed by the provider. Use its nativeId as topic and preserve the opaque cursor. Screened like `getPublicTrends`. */
     getPublicTrendFeed(params: {

package/dist/resources/protocols.js

@@ -42,11 +42,12 @@ function hostedIdentityPath(id) {
 export function viralItemHasVideo(item) {
     return item.post.media.some(media => media.type === 'video');
 }
-/** Only the two radar fields travel; caller scope or destination extras never reach the query string. */
+/** Only the radar's own fields travel; caller scope or destination extras never reach the query string. */
 /** Forwarded only when given, so a default read makes exactly the call it always made. */
 const readOptions = (options) => options ? [options] : [];
 function radarQuery(params) {
-    return { ...(params.category !== undefined ? { category: params.category } : {}), ...(params.limit !== undefined ? { limit: params.limit } : {}) };
+    return { ...(params.category !== undefined ? { category: params.category } : {}), ...(params.limit !== undefined ? { limit: params.limit } : {}),
+        ...(params.compass !== undefined ? { compass: params.compass } : {}) };
 }
 /** Only the six Viral read fields travel, each only when given: the read answers any other parameter with a 400. */
 function viralQuery(params) {
@@ -204,13 +205,17 @@ export class ProtocolsResource {
     }
     /**
      * Current provider-ranked topics or posts, with explicit source and coverage. Does not ingest content.
-     * Every page, previews included, gets the safety floor; `discovery` only asks for a layout.
+     * Every page, previews included, gets the safety floor; `discovery` only asks for a layout. `compass` (a Politics
+     * choice, spelled as `posts.list` takes it): Hide politics (`hide`) leaves out the topics and posts whose cached
+     * browse category is politics, where the filter is served to the member; a side or Mix is answered unfiltered. The
+     * page then says what it did in `meta.compass_filter`.
      */
     getPublicTrends(params, options) {
         return this.client.get('/protocols/social/trends', { protocol: params.protocol, limit: params.limit, cursor: params.cursor,
             ...(params.includePreviews !== undefined ? { includePreviews: params.includePreviews } : {}),
             ...(params.category !== undefined ? { category: params.category } : {}),
-            ...(params.discovery !== undefined ? { discovery: params.discovery } : {}) }, ...readOptions(options));
+            ...(params.discovery !== undefined ? { discovery: params.discovery } : {}),
+            ...(params.compass !== undefined ? { compass: params.compass } : {}) }, ...readOptions(options));
     }
     /** Open a topic currently listed by the provider. Use its nativeId as topic and preserve the opaque cursor. Screened like `getPublicTrends`. */
     getPublicTrendFeed(params, options) {

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

@@ -37,6 +37,10 @@ export type FeedNext = {
  * cursor; the same continuation `next` carries), the same category on the open networks, the member's
  * next categories (`via`: the order they came from, the one `posts.categories()` serves), For you
  * (signed in), All.
+ *
+ * `feed` (0.7.60) names the next feed by its ref (e.g. `builtin:category:science`, or a member's `feed:<id>`). No
+ * server sends it yet: it comes with feeds. Skip a step whose kind your app cannot open yet; a feed session
+ * (`discovery.createFeed`) already leaves out any step this SDK does not know, or a malformed one.
  */
 export type FalloverStep = {
     kind: 'category_older';
@@ -53,6 +57,9 @@ export type FalloverStep = {
     kind: 'for_you';
 } | {
     kind: 'all';
+} | {
+    kind: 'feed';
+    ref: string;
 };
 /**
  * What a Politics choice (`compass`) did to a page, on the feeds that take one (`posts.list` on discovery, category
@@ -634,6 +641,25 @@ export interface ConversationMember {
     username: string;
     image: string | null;
     is_ai: boolean;
+    /**
+     * `admin` for a private group's admin: the one person who adds, removes and
+     * renames, and whose device sets up an encrypted group's keys. The creator,
+     * then, once they leave, the longest-standing person left. `member` for
+     * everyone else. Omitted by APIs before SDK 0.7.59's group routes.
+     */
+    role?: ChatMemberRole;
+    /**
+     * 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;
 }
 export interface ConversationMemberDetail extends ConversationMember {
     joined_at: string;
@@ -683,6 +709,12 @@ export interface LeaveConversationResult {
     left: true;
     /** True when the caller was the last person in it, so the room was removed. */
     conversation_deleted: boolean;
+    /**
+     * When the admin of an encrypted group leaves: the invitees who had not
+     * accepted, whose invites were cancelled with them (the next admin
+     * re-invites). Omitted when there were none.
+     */
+    invites_cancelled?: string[];
 }
 export interface ConversationDetail {
     /** Missing on older APIs: treat as unknown, never as plaintext permission. */
@@ -702,6 +734,67 @@ export interface ConversationDetail {
     can_leave?: boolean;
     created_at: string;
 }
+export type ChatMemberRole = 'admin' | 'member';
+/**
+ * Why an encrypted group refused someone: `details.reason` of a 409
+ * `conversation_not_eligible` (`RecursivError`) from
+ * `chat.createGroup({ encrypted: true })` or `chat.addMembers`, beside
+ * `details.max_people`. The group must be a private group (not a DM, not a
+ * community room) of people only (no agents), all inside the encryption
+ * pilot, and at most `max_people` (8 at launch) counting pending invitees.
+ */
+export type EncryptedGroupRefusalReason = 'not_a_private_group' | 'community' | 'too_many_people' | 'agent' | 'outside_pilot';
+export interface CreateGroupInput {
+    name: string;
+    /** Up to 100 people, invited in this order. */
+    member_ids: string[];
+    /**
+     * End-to-end encrypted. The group and its encryption record are created
+     * together or not at all: a refusal never leaves a plaintext group behind.
+     */
+    encrypted?: boolean;
+    /** With `encrypted`: the creator's active encrypted-chat device, when they have one. */
+    device_id?: string;
+}
+export interface AddGroupMembersResult {
+    id: string;
+    /** Who was added, in the order asked; `pending` for someone who does not follow you (a message request). */
+    added: Array<{
+        id: string;
+        request_status: ChatRequestStatus;
+    }>;
+    /** Asked for but already in the group: nothing changed for them. */
+    already_members: string[];
+}
+export interface RemoveGroupMemberResult {
+    id: string;
+    user_id: string;
+    removed: true;
+}
+export interface UpdateGroupResult {
+    id: string;
+    name: string;
+}
+/**
+ * Realtime `chat:members`: a private group's people changed. Ids only: read
+ * the conversation again (and, in an encrypted group, check its keys).
+ * `actorId` is the admin for `added` and `removed`, and the leaver for `left`
+ * and `invites_cancelled` (the invites an encrypted group's admin sent, which
+ * went with them).
+ */
+export interface ChatMembersEvent {
+    conversationId: string;
+    change: 'added' | 'removed' | 'left' | 'invites_cancelled';
+    userIds: string[];
+    actorId: string;
+}
+/** Realtime `chat:conversation`: a private group was renamed by its admin. */
+export interface ChatConversationEvent {
+    conversationId: string;
+    change: 'renamed';
+    name: string;
+    actorId: string;
+}
 export interface MessageReaction {
     type: string;
     user_id: string;

package/llm.md

@@ -498,10 +498,12 @@ const { data: group } = await r.chat.createGroup({ name: 'Team', member_ids: ['u
 const { data: msgs } = await r.chat.messages(dm.id, { limit: 50 })
 ```
 
-Methods: `conversations`, `communityConversation`, `conversation`, `messages`, `send`, `dm`, `createGroup`, `deleteConversation`, `leave`, `acceptRequest`, `declineRequest`, `reactToMessage`, `editMessage`, `deleteMessage`, `markAsRead`, `unreadCount`
+Methods: `conversations`, `communityConversation`, `conversation`, `messages`, `send`, `dm`, `createGroup`, `addMembers`, `removeMember`, `updateGroup`, `deleteConversation`, `leave`, `acceptRequest`, `declineRequest`, `reactToMessage`, `editMessage`, `deleteMessage`, `markAsRead`, `unreadCount`
 
 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 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)
 
 Relays opaque MLS envelopes, public device credentials and one-time key packages for the shared E2EE core; the server never sees keys or plaintext. Requires the `e2eeV2` network feature flag (otherwise `feature_disabled`) and a key acting as the account owner (agent-scoped keys get `agent_key_not_allowed`). The realm is the network id. Only a direct conversation between two people with an accepted request can start encryption (`conversation_not_eligible` otherwise), and every later append to it is checked the same way again (both people still accepted, still in the pilot, still only the two of them), so a client need not read the policy before each send; a resend of an event already stored still returns `duplicate: true`, even once a Welcome's target device is gone; blocks apply (`blocked`), to resends too; commits must send `expected_commit_seq`.
@@ -519,7 +521,8 @@ await r.e2ee.appendEvent(conversationId, { device_id: device.id, envelope: react
 const { data: page } = await r.e2ee.events(conversationId, { device_id: device.id, after_seq: 0 });
 await r.e2ee.acknowledge(conversationId, { device_id: device.id, seq: page.headSeq });
 // Doorbell after every append: { conversationId, seq, event? }. `event` (a small application message, as events() returns it) comes only to a socket of the owner's session or an owner key, never an agent-scoped key.
-r.realtime.onE2eeEvent(({ conversationId, event }) => (event ? controller.applyPushed(conversationId, event) : controller.sync(conversationId)));
+// The policy is required: policyForConversationType(conversation.type) from @recursiv/e2ee ('direct' or 'group').
+r.realtime.onE2eeEvent(({ conversationId, event }) => (event ? controller.applyPushed(conversationId, event, policy) : controller.sync(conversationId, undefined, policy)));
 ```
 
 Link a new device by scanning (0.7.57; `status()` reports `links: true` when the relay can). The new device N shows the link id in a QR code; an approved device A of the same account scans it. The relay is a short-lived mailbox (180 s, 120 s more once scanned; one open link per sign-in, at most 3 per account; 10 creates per sign-in and 20 per account an hour, refused with 409 `link_limit`, never 429). `approval` and `tag` go only to the sign-in that created the link. Reserved labels get 400 `invalid_label`; a 503 `storage_unavailable` is temporary, so keep polling until `expiresAt`. Own devices carry `createdAt` and `lastSeenAt`.
@@ -616,6 +619,8 @@ const { data: results } = await r.posts.search({ query: 'shipped', community_id:
 
 Methods: `list`, `get`, `create`, `update`, `delete`, `search`, `replies(id, { limit, cursor })` (after `replies_next_cursor` on `get`), `react`, `unreact`, `liked`, `bookmarked`, `bookmark`, `unbookmark`
 
+Feed definitions (types only; no route serves one yet): `FeedDefinition` is `{ v: 1, sources, ranking: { mode, range? }, filters?, exclude? }`, with 1-`FEED_SOURCES_MAX` (50) sources read as one union (`FEED_SOURCE_KINDS`; `FEED_SOURCE_KEY[kind]` names each kind's one field, e.g. `{ kind: 'tag', slug: 'rust' }`, `{ kind: 'account', ref: 'did:plc:…' }`). `filters.politics` stores only `'hide'`; viewer settings, blocks, mutes and compass Mix/Sides never go in a definition. Built-in feeds: `builtinCategoryFeedRef('science')` → `'builtin:category:science'`, plus `'builtin:all'` and `'builtin:for_you'`.
+
 `search` ranks relevance x recency x engagement (recency falls as a power of age: this month outranks years ago) through the promotion safety floor; `sort: 'new'` lists newest first. Page with `meta.next_cursor` as `cursor`: later relevance pages are slices of the ranking the first page kept for ten minutes (nothing skipped or repeated while it lives; after that, the page continues past the last post's score boundary), newest-first pages continue by (created_at, id). A cursor is bound to its search and sort: another search's, or the other sort's, is 400 `invalid_cursor`. The first relevance page carries `latest` (up to three of the newest matches not on the page, one per author, for a Latest strip); the last page carries `fall_over.lanes` (`new`, `open_network`, `tag`): draw a way on, not a wall.
 
 ### r.bookmarks — Synced saves (per member, per app)
@@ -680,7 +685,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
 
@@ -691,10 +702,12 @@ const { data: group } = await r.chat.createGroup({ name: 'Team', member_ids: ['u
 const { data: msgs } = await r.chat.messages(dm.id, { limit: 50 })
 ```
 
-Methods: `conversations`, `communityConversation`, `conversation`, `messages`, `send`, `dm`, `createGroup`, `deleteConversation`, `leave`, `acceptRequest`, `declineRequest`, `reactToMessage`, `editMessage`, `deleteMessage`, `markAsRead`, `unreadCount`
+Methods: `conversations`, `communityConversation`, `conversation`, `messages`, `send`, `dm`, `createGroup`, `addMembers`, `removeMember`, `updateGroup`, `deleteConversation`, `leave`, `acceptRequest`, `declineRequest`, `reactToMessage`, `editMessage`, `deleteMessage`, `markAsRead`, `unreadCount`
 
 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 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
 
 ```typescript
@@ -742,9 +755,10 @@ await r.appSubscriptions.changeTier({ tier: 'pro', proration_date: quote.prorati
 - `r.protocols` — Private app safety: `sourceControls` returns current `enabled` plus paged saved choices; `setSourceControl`, `onSourceControlChange` and `reportSource` share app scope. Example: `const choices = new Map(); const stop = r.protocols.onSourceControlChange(change => choices.set(JSON.stringify([change.source, change.control]), change.enabled));` then `await r.protocols.setSourceControl({ source: { protocol: "bluesky", kind: "actor", nativeId: "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa" }, control: "mute", enabled: true, scope: "minds" });` and call `stop(); choices.clear()` on account change/unmount. Notifications follow an exact server confirmation, never an uncertain response. These preferences and reports apply in Minds, not on the remote network. Keyless post links: `const visitor = new Recursiv({ anonymous: true, inheritEnvironmentApiKey: false }); const { data: thread } = await visitor.protocols.getSharedConversation(projectId, { protocol: 'nostr', post: publicEventId })`; `sharedNetworks(projectId)` lists public conversation capabilities. Only configured apps; app moderation and rate limits apply, no member state or write authority. Member public reading: `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. Example after selecting a returned source post: `const { data: thread } = await r.protocols.getPublicConversation({ protocol: post.protocol, post: post.nativeId, readRef: post.readRef })`. Render `focus`, oldest-first `ancestors` and direct `replies`; `public_provider_window` never promises every reply, and `limited` marks known omissions. Requires both `users:read` and `posts:read` on the current human app key. Protocol discovery/settings: `const { data: adapters } = await r.protocols.list()` returns bounded `{ id, name, icon, color, maturity, capabilities, limitations }` metadata; `supported` means implemented, not configured, healthy, authorized, or enabled. Methods: `list`, `status`, `listCandidates`, `getCandidate`, `search`, `getSettings`, `refresh`, `updateSettings`.
   - 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`). 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`.
+  - 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? })`; 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.
+  - 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.59",
+  "version": "0.7.63",
   "description": "TypeScript SDK for the Recursiv API",
   "license": "FSL-1.1-ALv2",
   "type": "module",