@recursiv/sdk 0.7.58 → 0.7.62

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

@@ -11,6 +11,10 @@ export type ForYouParams = {
     discovery?: boolean;
     /** `discover` ranks for Discover: fresher, beyond the member's follows, with their category order. */
     surface?: ForYouSurface;
+    /** A Politics choice, as `posts.list` takes it (`ListPostsParams.compass`); the page says what it did in `meta.compass_filter`. */
+    compass?: string;
+    /** `false` asks once and is never sent, as `posts.list` takes it (`ListPostsParams.retry`). */
+    retry?: boolean;
 };
 export interface ForYouMeta extends PaginationMeta {
     discovery?: DiscoveryLayout;
@@ -269,7 +273,7 @@ export declare class CuratorResource {
      * affinity, no model calls). Returns posts in the same shape as
      * `sdk.posts.list()`, so any feed UI renders it unchanged. Requires a
      * project-scoped key (the feed is per-app). Servers that predate `cursor`,
-     * `discovery` and `surface` ignore them.
+     * `discovery` and `surface` ignore them. `retry: false` asks once and is never sent (`ListPostsParams.retry`).
      */
     forYou(params?: ForYouParams): Promise<PaginatedResponse<Post> & {
         meta: ForYouMeta;

package/dist/resources/curator.js

@@ -48,9 +48,13 @@ export class CuratorResource {
      * affinity, no model calls). Returns posts in the same shape as
      * `sdk.posts.list()`, so any feed UI renders it unchanged. Requires a
      * project-scoped key (the feed is per-app). Servers that predate `cursor`,
-     * `discovery` and `surface` ignore them.
+     * `discovery` and `surface` ignore them. `retry: false` asks once and is never sent (`ListPostsParams.retry`).
      */
     forYou(params = {}) {
-        return this.client.get('/curator/foryou', params);
+        // Without `retry`, the same request older SDKs make.
+        if (!('retry' in params))
+            return this.client.get('/curator/foryou', params);
+        const { retry, ...query } = params;
+        return retry === false ? this.client.get('/curator/foryou', query, { retry: false }) : this.client.get('/curator/foryou', query);
     }
 }

package/dist/resources/discovery.d.ts

@@ -1,10 +1,78 @@
 import type { HttpClient } from '../client.js';
-import type { DiscoveryLayout, FalloverStep, Post } from '../types.js';
+import type { CompassFilterMeta, DiscoveryLayout, FalloverStep, MediaItem, Post } from '../types.js';
 import type { CuratorResource } from './curator.js';
 import type { DiscoveryLearning } from './discovery-learning.js';
 import type { PostsResource } from './posts.js';
 import type { ProtocolsResource, SocialNetwork, SocialPost, SocialRadar, SocialRadarPosts } from './protocols.js';
 export type DiscoveryRecommendationKind = 'groups' | 'people' | 'tags';
+/** A page of Watch's Minds videos (`discovery.videos`). */
+export interface WatchVideosParams {
+    /** A browse category id: the videos among the category's judged posts. Omitted: the whole app. */
+    category?: string;
+    /** Posts per page, 1 to 25 (default 12). */
+    limit?: number;
+    /** The `meta.next_cursor` of the page before. */
+    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 {
+    thumbnail_url: string | null;
+    /** Set while the file is not ready on the CDN; absent once it is. */
+    status?: string;
+    width?: number;
+    height?: number;
+    duration_sec?: number;
+    hls_url?: string;
+}
+/**
+ * A post as `discovery.videos` serves it: the `Post` shape (so a page is a valid `posts.list` page), with the engagement
+ * GET /posts sends (live votes plus imported likes, the replies the reader can open) and the viewer's own vote and repost.
+ */
+export interface WatchVideoPost extends Post {
+    title: string | null;
+    is_nsfw: boolean;
+    score: number;
+    upvote_count: number;
+    downvote_count: number;
+    /** The viewer's own reaction ('upvote', 'downvote', ...); null for a visitor or when they have none. */
+    user_reaction: string | null;
+    reply_count: number;
+    reply_count_external: number;
+    unique_commenters: number;
+    reposts_count: number;
+    /** Id of the viewer's own repost of the post; delete it to undo the repost. */
+    reposted_by_viewer_id: string | null;
+    media: WatchVideoMedia[];
+}
+export interface WatchVideosResponse {
+    /** Public Minds video posts in hot order (with the viewer's own `user_reaction` and `reposted_by_viewer_id`). */
+    data: WatchVideoPost[];
+    meta: {
+        limit: number;
+        /** The position in the list this page started at. */
+        offset: number;
+        has_more: boolean;
+        /** Pass as `cursor` for the next page; null at the end of the list. */
+        next_cursor: string | null;
+        /** Positions in the list this page examined (a client paging by offset adds it to the offset). */
+        scanned: number;
+        /** When the shared list the page was cut from was built; null when the app has none. */
+        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. */
 export type EntityKind = 'member' | 'group' | 'tag' | 'network_account' | 'story';
 /**
@@ -247,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 {
@@ -272,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
@@ -280,6 +375,12 @@ export interface DiscoveryFeedPage {
      * on servers that predate it.
      */
     fallover?: FalloverStep[];
+    /**
+     * What the session's Politics choice (`compass`, createFeed and createPersonalFeed) did to this page's Minds read:
+     * that read's `meta.compass_filter`, counts only. `unavailable` means the page was served unfiltered. Absent without
+     * a choice, on a page whose Minds read failed or was not made, and on servers that predate the filter.
+     */
+    compass?: CompassFilterMeta;
 }
 /** A gallery strip holds up to twelve image posts gathered from the whole page. */
 export declare const GALLERY_MAX_ITEMS = 12;
@@ -369,6 +470,16 @@ export declare class DiscoveryResource {
     }, options?: {
         retry?: boolean;
     }): Promise<CategorySurfaceResponse>;
+    /**
+     * Watch's Minds videos for the viewer: the app's public video posts in hot order (engagement decayed by age), from
+     * one list the server shares among every viewer of the app and rebuilds about once a minute, each post checked again
+     * on every read under the public floors (not NSFW, removed or hidden; no spam-labelled or adult author or group; the
+     * cached safety verdict) and the viewer's blocks and mutes. A video whose file is gone or not on the CDN yet is left
+     * out or marked `unplayable`. Page on `meta.next_cursor`. Needs posts:read; the app is the API key's project.
+     */
+    videos(params?: WatchVideosParams, options?: {
+        retry?: boolean;
+    }): Promise<WatchVideosResponse>;
     /**
      * A For you Discover feed: the member's For You ranking (asked for Discover's surface, with layouts and a
      * snapshot cursor) in a session's Minds slot. With a category, the session also reads open-network posts
@@ -380,12 +491,19 @@ export declare class DiscoveryResource {
         learning?: DiscoveryLearning;
         recommend?: DiscoveryRecommendationSources;
         category?: string;
+        compass?: string;
     }): DiscoveryFeedSession;
+    /**
+     * Discover's feed session. `compass` (a Politics choice, as `posts.list` takes it) goes on every Minds read, whose
+     * pages then carry `meta.compass_filter`; the open networks' reads and the radar are not filtered by it, so a view
+     * that leaves posts out (Hide politics, Choose sides) is best read with `source: 'minds'`.
+     */
     createFeed(options: {
         networks: SocialNetwork[];
         category?: string;
         source?: string;
         learning?: DiscoveryLearning;
         recommend?: DiscoveryRecommendationSources;
+        compass?: string;
     }): DiscoveryFeedSession;
 }

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;
@@ -191,7 +267,12 @@ export class DiscoveryFeedSession {
         if (stream.protocol === 'minds') {
             // Discover leads with what is moving now: the REST hot order (engagement
             // decayed by age). Hot pages by offset; the server sends no cursor for it.
-            const response = await this.posts.list({ ...params, sort: 'hot', ...(stream.cursor ? { cursor: stream.cursor } : { offset: stream.offset }) });
+            // Asked once, as the open networks are: a 503 retried twice with its Retry-After ran past this read's 15 s
+            // deadline, and the Minds lane failed (Bill 2026-10-01: "couldnt load discover minds posts didnt load"). The
+            // opt-out rides in the params (ListPostsParams.retry), which a reader handed to a session forwards to read the
+            // right page at all: a second argument was dropped by the Minds app's own wrappers (lib/discoverFeedResource,
+            // lib/compassStatus withCompass, lib/watchSource), which pass the params alone (review of #4047).
+            const response = await this.posts.list({ ...params, sort: 'hot', ...(stream.cursor ? { cursor: stream.cursor } : { offset: stream.offset }), retry: false });
             stream.offset += response.meta.scanned ?? response.meta.limit;
             const next = response.meta.next_cursor ?? undefined;
             stream.done = !response.meta.has_more || !!next && (next === stream.cursor || stream.used.includes(next));
@@ -199,10 +280,12 @@ 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' };
+                layout: response.meta.discovery ?? ordinary, partial: response.meta.category_filter?.status === 'partial',
+                ...(response.meta.compass_filter ? { compass: response.meta.compass_filter } : {}) };
         }
         const validatePosts = (data) => {
             if (data.coverage !== 'provider_ranked_window' || data.items.length > 25 || data.items.some(post => post.protocol !== stream.protocol || post.author.protocol !== stream.protocol))
@@ -211,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') {
@@ -254,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;
@@ -299,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.
@@ -311,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 {
@@ -402,9 +499,13 @@ export class DiscoveryFeedSession {
         if (cluster)
             modules.splice(page === 0 ? 0 : Math.min(2, modules.length), 0, this.radarModule(page, cluster, clusterItems));
         const fallover = this.streams.find(stream => stream.protocol === 'minds')?.fallover;
-        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),
-            ...(fallover ? { 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;
+        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. */
     async radarCluster(page) {
@@ -583,6 +684,18 @@ export class DiscoveryResource {
             throw new Error('category needs the HTTP client');
         return this.http.get('/discover/category', params, options);
     }
+    /**
+     * Watch's Minds videos for the viewer: the app's public video posts in hot order (engagement decayed by age), from
+     * one list the server shares among every viewer of the app and rebuilds about once a minute, each post checked again
+     * on every read under the public floors (not NSFW, removed or hidden; no spam-labelled or adult author or group; the
+     * cached safety verdict) and the viewer's blocks and mutes. A video whose file is gone or not on the CDN yet is left
+     * out or marked `unplayable`. Page on `meta.next_cursor`. Needs posts:read; the app is the API key's project.
+     */
+    videos(params = {}, options) {
+        if (!this.http)
+            throw new Error('videos needs the HTTP client');
+        return this.http.get('/discover/videos', { ...params }, options);
+    }
     /**
      * A For you Discover feed: the member's For You ranking (asked for Discover's surface, with layouts and a
      * snapshot cursor) in a session's Minds slot. With a category, the session also reads open-network posts
@@ -593,10 +706,13 @@ export class DiscoveryResource {
         const curator = this.curator;
         if (!curator)
             throw new Error('createPersonalFeed needs the curator resource');
+        const compass = options.compass;
         const list = {
-            // The session's `sort` and `category` are Discover's hot-order knobs; the ranker ignores them.
+            // The session's `sort` and `category` are Discover's hot-order knobs; the ranker ignores them. A Politics choice
+            // goes on every ranker read.
             list: async (params) => {
-                const response = await curator.forYou({ limit: params?.limit, offset: params?.offset, cursor: params?.cursor, discovery: true, surface: 'discover' });
+                const response = await curator.forYou({ limit: params?.limit, offset: params?.offset, cursor: params?.cursor, discovery: true, surface: 'discover',
+                    ...(compass ? { compass } : {}), ...(params?.retry === undefined ? {} : { retry: params.retry }) });
                 // A server that predates the cursor says has_more: false on a partial ranked page although its
                 // continuation serves the next offset. A cursor-aware server always says `personalized`, and its
                 // has_more is the end of the feed.
@@ -606,9 +722,16 @@ export class DiscoveryResource {
         };
         return new DiscoveryFeedSession(list, this.protocols, options.category ? options.networks : [], options.category, options.category ? 'all' : 'minds', options.learning, options.recommend);
     }
+    /**
+     * Discover's feed session. `compass` (a Politics choice, as `posts.list` takes it) goes on every Minds read, whose
+     * pages then carry `meta.compass_filter`; the open networks' reads and the radar are not filtered by it, so a view
+     * that leaves posts out (Hide politics, Choose sides) is best read with `source: 'minds'`.
+     */
     createFeed(options) {
+        const compass = options.compass;
+        const posts = compass ? { list: params => this.posts.list({ ...params, compass }) } : this.posts;
         // The radar rides along by default; an older server answers 404 and the session simply shows no story module.
-        return new DiscoveryFeedSession(this.posts, this.protocols, options.networks, options.category, options.source, options.learning, options.recommend, params => this.protocols.getPublicRadar(params, NO_RETRY), { social: params => this.protocols.getPublicRadarPosts(params, NO_RETRY), minds: id => this.posts.get(id) });
+        return new DiscoveryFeedSession(posts, this.protocols, options.networks, options.category, options.source, options.learning, options.recommend, params => this.protocols.getPublicRadar(params, NO_RETRY), { social: params => this.protocols.getPublicRadarPosts(params, NO_RETRY), minds: id => this.posts.get(id) });
     }
 }
 /** A read bounded to three seconds; a late or failed one resolves to `fallback`, never an error. */