@recursiv/sdk 0.7.58 → 0.7.62

package/dist/resources/protocols.d.ts

@@ -1,5 +1,5 @@
 import type { HttpClient } from '../client.js';
-import type { DiscoveryLayout, PaginatedResponse, PaginationParams, SingleResponse } from '../types.js';
+import type { CompassFilterMeta, DiscoveryLayout, PaginatedResponse, PaginationParams, SingleResponse } from '../types.js';
 /** Canonical protocol operation names returned by the adapter registry. */
 export declare const PROTOCOL_CAPABILITY_OPERATIONS: readonly ["discover", "stream", "backfill", "search", "resolveIdentity", "fetchProfile", "fetchThread", "publish", "reply", "react", "repost", "follow", "delete", "health", "checkpoint"];
 export declare const PROTOCOL_CAPABILITY_STATUSES: readonly ["supported", "planned", "unsupported"];
@@ -906,7 +906,8 @@ export interface SocialNetwork {
         url: string;
     };
     coverage: string;
-    capabilities: Array<'profile_search' | 'profile_read' | 'original_author_posts' | 'minds_subscription' | 'following_feed' | 'conversation_read' | 'public_trends' | 'trend_feed' | 'popular_accounts' | 'post_search'>;
+    /** `compass_filter`: the Politics filter is served to this viewer (an app offers it only then); listed on every network. */
+    capabilities: Array<'profile_search' | 'profile_read' | 'original_author_posts' | 'minds_subscription' | 'following_feed' | 'conversation_read' | 'public_trends' | 'trend_feed' | 'popular_accounts' | 'post_search' | 'compass_filter'>;
     profileSearchPagination: boolean;
     postSearchAccountRequired?: boolean;
     /** Categories available from the current app configuration. */
@@ -930,8 +931,22 @@ export interface SocialProfile {
     postsCount: number | null;
     /** Nostr only: the NIP-05 name its domain has confirmed for this key ("lyn@primal.net"); `handle` stays the key. */
     nip05?: string;
+    /** A bridge (Bridgy Fed, Mostr) made this account from one on another network (SocialBridge). Present only on a bridged account. */
+    bridge?: SocialBridge;
     subscription: SocialSubscription | null;
 }
+/**
+ * A post or account a bridge copied from another network: Bridgy Fed (`*.brid.gy`), Mostr (`mostr.pub`), or a Nostr
+ * event's NIP-48 `proxy` tag naming no bridge the server knows (`proxy`). `originId` names the original, normalised (a
+ * Bluesky at-uri or DID, an ActivityPub object URL or `user@host`, a Nostr event id or key, a web URL), when the bridge
+ * says. Where the server reads both, feeds, search and the radar already fold a copy into its original; an app that
+ * merges several networks' pages itself can fold the same way: a copy whose original is shown is the same post.
+ */
+export interface SocialBridge {
+    via: 'bridgy_fed' | 'mostr' | 'proxy';
+    protocol: 'bluesky' | 'activitypub' | 'nostr' | 'web';
+    originId?: string;
+}
 export interface SocialSubscription {
     id: string;
     protocol: string;
@@ -1028,6 +1043,8 @@ export interface SocialPost {
      * to signed-out visitors.
      */
     authorOptOut?: true;
+    /** A bridge (Bridgy Fed, Mostr, a NIP-48 proxy tag) made this post from one on another network (SocialBridge). Present only on a copy read live. */
+    bridge?: SocialBridge;
 }
 export interface SocialPostSearch {
     items: SocialPost[];
@@ -1103,7 +1120,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[];
@@ -1229,10 +1251,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 {
@@ -1290,6 +1322,182 @@ export interface SocialRadarStory {
      */
     editionStory?: string;
 }
+/**
+ * The Viral read (`getPublicViral`, `getSharedViral`): what is moving fastest on Bluesky, the Fediverse, Nostr and
+ * Minds right now, each measured against its own network's pace, from a snapshot the server's rank tick rebuilds about
+ * every five minutes. A read never reaches a provider or the model. These types mirror the server's
+ * ViralSnapshotContract; a contract test compares them key by key.
+ */
+export type ViralNetwork = 'all' | 'minds' | 'bluesky' | 'activitypub' | 'nostr';
+export type ViralProtocol = 'bluesky' | 'activitypub' | 'nostr' | 'minds';
+/** The networks whose posts the read serves as a `SocialPost`. */
+export type ViralOpenProtocol = 'bluesky' | 'activitypub' | 'nostr';
+/**
+ * `viral`: a measured rate well above its network's baseline (z of 1 or more) with two or more kinds of engagement;
+ * `rising`: a measured rate speeding up (accel of 0.7 or more) on a post under six hours old; `hot`: everything else,
+ * including every post without a measured rate.
+ */
+export type ViralLabel = 'viral' | 'rising' | 'hot';
+/**
+ * `ok`: a build served. `building`: no build yet. `screening`: served, but fewer than 30% of the top 200 posts have
+ * a safety verdict yet. `off`: the read is not enabled for this app (or, on `getSharedViral` only, the API predates it):
+ * no items, and nothing to retry until it is turned on.
+ */
+export type ViralReadStatus = 'ok' | 'building' | 'screening' | 'off';
+/** Every parameter is optional. The server rejects any other parameter with a 400, so only these travel. */
+export interface ViralReadParams {
+    /** Default `all`: every network, with a per-network quota so no one network fills the page. */
+    network?: ViralNetwork;
+    /** A Discover category id: only posts judged into it. */
+    category?: string;
+    /**
+     * `video`: only posts whose own media includes a video. A member's read serves every such video. A visitor's read
+     * (`getSharedViral`) still serves a post's media only where the server cleared it, so some items can arrive with
+     * the video withheld (the card's `media` empty): keep `items.filter(viralItemHasVideo)` for a video-only player.
+     */
+    media?: 'video';
+    /** Page size, default 20. */
+    limit?: 5 | 10 | 20 | 40;
+    /** The previous page's `cursor`. A cursor names its build; one whose build expired (30 minutes) ends the list. */
+    cursor?: string;
+    /** A Politics choice. A visitor (`getSharedViral`) may send only `all` or `hide`; anything else is a 400. */
+    compass?: string;
+}
+/** How fast a post is gathering reactions, reposts and replies (per hour), against its network's baseline. */
+export interface ViralItemVelocity {
+    perHour1h: number;
+    perHour6h: number;
+    /** The 1-hour rate against its network's trailing baseline, from -2 to 4 (1 or more is well above). */
+    z: number;
+    /** ln((1 + perHour1h) / (1 + perHour6h)), from -1 to 2: above 0 is speeding up. */
+    accel: number;
+    /** Readings behind the rate; null for a Minds post. */
+    samples: number | null;
+    spanHours: number;
+    /** The rate comes from two or more readings over time (a Minds post's always does). An unmeasured post is never viral or rising. */
+    measured: boolean;
+    /** Who counted: Bluesky's AppView, one Fediverse server, a third party's report (Primal, for Nostr), or Minds itself. */
+    countsOrigin: 'appview' | 'instance_local' | 'provider_reported' | 'minds';
+    /** Minutes since the counts were last read, when known. */
+    countsAgeMin?: number;
+    /** Present when a third party reported the counts (`Primal`): show them as reported by it, never as verified. */
+    countsReportedBy?: string;
+}
+/** Another post in the same spread group: the same link posted on another network. */
+export interface ViralRef {
+    protocol: ViralProtocol;
+    nativeId: string;
+}
+export interface ViralItemSpread {
+    /** The networks sharing the post's link (its own alone when no other network carries it). */
+    protocols: ViralProtocol[];
+    /** Fediverse: how many servers' trends lists carried the post. */
+    instances?: number;
+    clusterId: null;
+    alsoOn: ViralRef[];
+}
+/** A Minds post's card as the read serves it; open it at /post/:id. A visitor's carries media only where the server cleared it. */
+export interface ViralMindsCard {
+    id: string;
+    title: string | null;
+    text: string;
+    createdAt: string;
+    author: {
+        name: string | null;
+        username: string | null;
+    } | null;
+    media: Array<{
+        type: string;
+        url: string;
+        width: number | null;
+        height: number | null;
+        thumbnailUrl: string | null;
+        hlsUrl: string | null;
+    }>;
+    likeCount: number;
+    repostCount: number;
+    replyCount: number;
+}
+/** What every ranked post carries, whichever network it comes from. */
+export interface ViralItemFields {
+    /** Stable across builds: use it to drop a post already shown. */
+    key: string;
+    label: ViralLabel;
+    score: number;
+    /** 1-based position in this read's ordering, across pages. */
+    rank: number;
+    category: string | null;
+    velocity: ViralItemVelocity;
+    spread: ViralItemSpread;
+}
+/** A ranked Minds post; open it at /post/:id. */
+export interface ViralMindsItem extends ViralItemFields {
+    protocol: 'minds';
+    post: ViralMindsCard;
+}
+/** A ranked Bluesky, Fediverse or Nostr post. */
+export interface ViralSocialItem extends ViralItemFields {
+    protocol: ViralOpenProtocol;
+    post: SocialPost;
+}
+/**
+ * One ranked post: check `protocol` and TypeScript narrows `post` (a `ViralMindsCard` for `minds`, a `SocialPost`
+ * otherwise). No item carries a compass value, an author id, a safety flag or its media kind. A visitor's card keeps
+ * its own images and video only where the server cleared them; a withheld one has empty `media` (a `SocialPost` also
+ * has `hasAdditionalContent: true`). Even under `media: 'video'` a visitor's item can arrive without its video, so
+ * test each one with `viralItemHasVideo` before a video player.
+ */
+export type ViralItem = ViralMindsItem | ViralSocialItem;
+/**
+ * Whether the item's own card carries a playable video. Use it on a `media: 'video'` read before a Watch-style
+ * player: a visitor's read can serve an item whose video the server withheld (its card's `media` is then empty).
+ * A video only in a quoted post does not count, as the server never counts a quote's media.
+ */
+export declare function viralItemHasVideo(item: ViralItem): boolean;
+/** A network's trailing pace that velocity is measured against. */
+export interface ViralBaseline {
+    median: number;
+    p90: number;
+    n: number;
+    source: 'trailing' | 'tick' | 'prior';
+}
+export interface ViralProvider {
+    name: string;
+    ok: boolean;
+    lastOkAt: string | null;
+    observedAt: string;
+}
+export interface ViralReadMeta {
+    network: ViralNetwork;
+    category_filter: {
+        selected: string;
+    } | null;
+    media_filter: 'video' | null;
+    /** Null unless the read named a filtering `compass`: what Hide politics left out (sides and Mix are not applied here). */
+    compass_filter: CompassFilterMeta | null;
+    safety_filter: {
+        withheld: number;
+        pending: number;
+    };
+}
+export interface ViralReadResponse {
+    items: ViralItem[];
+    /** Pass as `cursor` for the next page; null at the end of this build's list. */
+    cursor: string | null;
+    builtAt: string | null;
+    status: ViralReadStatus;
+    window: {
+        primary: '1h';
+        context: '6h';
+    };
+    baselines: Record<string, ViralBaseline>;
+    provenance: {
+        providers: ViralProvider[];
+    };
+    meta: ViralReadMeta;
+    /** True when no further page exists in this build (always on `off` and `building`). */
+    exhausted: boolean;
+}
 /** Read options for callers that hold their own deadline, such as a discovery page. */
 export interface SocialReadOptions {
     retry?: boolean;
@@ -1409,6 +1617,14 @@ export declare class ProtocolsResource {
     getSharedRadarStory(projectId: string, params: {
         cluster: string;
     }): Promise<SingleResponse<SocialRadarStory>>;
+    /**
+     * The Viral read without a key, for a signed-out visitor: posts whose authors allow wide reach only, and media only
+     * where the server cleared it, so a `media: 'video'` read can carry items whose video was withheld (filter with
+     * `viralItemHasVideo`). `status: 'off'` (no items, never thrown) until the server enables the read for the app;
+     * an API that predates the read answers this path 401 `missing_api_key`, which resolves as off too. Every other
+     * failure throws. Cacheable for a minute by a shared cache.
+     */
+    getSharedViral(projectId: string, params?: ViralReadParams, options?: SocialReadOptions): Promise<SingleResponse<ViralReadResponse>>;
     publicNetworks(): Promise<SingleResponse<SocialNetwork[]>>;
     /** Query the live public network. It does not import users or posts. */
     searchPublicPosts(params: SearchPublicPostsParams): Promise<SingleResponse<SocialPostSearch>>;
@@ -1442,7 +1658,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;
@@ -1451,6 +1670,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: {
@@ -1477,6 +1697,12 @@ export declare class ProtocolsResource {
     getPublicRadarStory(params: {
         cluster: string;
     }, options?: SocialReadOptions): Promise<SingleResponse<SocialRadarStory>>;
+    /**
+     * The Viral read under the signed-in member's app key (scopes `users:read` and `posts:read`): every network's posts
+     * the build keeps, less the member's own blocks, mutes and hidden posts. Never cached. `status: 'off'` resolves with
+     * no items; a 401 or 403 always throws (a session or key failure is never reported as off).
+     */
+    getPublicViral(params?: ViralReadParams, options?: SocialReadOptions): Promise<SingleResponse<ViralReadResponse>>;
     /** Provider-ranked public accounts with explicit provenance; served from the app's index when a fresh snapshot exists. */
     getPublicPopularProfiles(params: {
         protocol: string;

package/dist/resources/protocols.js

@@ -1,4 +1,4 @@
-import { ValidationError } from '../errors.js';
+import { AuthenticationError, ValidationError } from '../errors.js';
 /** Canonical protocol operation names returned by the adapter registry. */
 export const PROTOCOL_CAPABILITY_OPERATIONS = Object.freeze([
     'discover',
@@ -34,11 +34,43 @@ function hostedIdentityPath(id) {
     }
     return `/protocols/identities/${encodeURIComponent(id)}`;
 }
-/** Only the two radar fields travel; caller scope or destination extras never reach the query string. */
+/**
+ * Whether the item's own card carries a playable video. Use it on a `media: 'video'` read before a Watch-style
+ * player: a visitor's read can serve an item whose video the server withheld (its card's `media` is then empty).
+ * A video only in a quoted post does not count, as the server never counts a quote's media.
+ */
+export function viralItemHasVideo(item) {
+    return item.post.media.some(media => media.type === 'video');
+}
+/** 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) {
+    const query = {};
+    for (const key of ['network', 'category', 'media', 'limit', 'cursor', 'compass'])
+        if (params[key] !== undefined)
+            query[key] = params[key];
+    return query;
+}
+/** An off read is empty whatever else its body carried. Every other status is passed through as served. */
+function viralRead(response) {
+    if (response.data?.status !== 'off')
+        return response;
+    return { ...response, data: { ...response.data, items: [], cursor: null, exhausted: true } };
+}
+/** The server's own off answer (ViralReadService), built here for an API that predates the read. */
+function viralOff(params) {
+    return { data: {
+            items: [], cursor: null, builtAt: null, status: 'off', window: { primary: '1h', context: '6h' }, baselines: {}, provenance: { providers: [] },
+            meta: { network: params.network ?? 'all', category_filter: params.category !== undefined ? { selected: params.category } : null,
+                media_filter: params.media ?? null, compass_filter: null, safety_filter: { withheld: 0, pending: 0 } },
+            exhausted: true,
+        } };
 }
 /** Forward only the media contract fields; nothing else from the app's own media rows. */
 const nativeMediaInput = (media) => media.map(item => ({ url: item.url,
@@ -117,6 +149,23 @@ export class ProtocolsResource {
     getSharedRadarStory(projectId, params) {
         return this.client.get(`/protocols/public/${encodeURIComponent(projectId)}/radar/story`, { cluster: params.cluster });
     }
+    /**
+     * The Viral read without a key, for a signed-out visitor: posts whose authors allow wide reach only, and media only
+     * where the server cleared it, so a `media: 'video'` read can carry items whose video was withheld (filter with
+     * `viralItemHasVideo`). `status: 'off'` (no items, never thrown) until the server enables the read for the app;
+     * an API that predates the read answers this path 401 `missing_api_key`, which resolves as off too. Every other
+     * failure throws. Cacheable for a minute by a shared cache.
+     */
+    async getSharedViral(projectId, params = {}, options) {
+        try {
+            return viralRead(await this.client.get(`/protocols/public/${encodeURIComponent(projectId)}/viral`, viralQuery(params), ...readOptions(options)));
+        }
+        catch (error) {
+            if (error instanceof AuthenticationError && error.code === 'missing_api_key')
+                return viralOff(params);
+            throw error;
+        }
+    }
     publicNetworks() {
         return this.client.get('/protocols/social/networks');
     }
@@ -156,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) {
@@ -188,6 +241,14 @@ export class ProtocolsResource {
     getPublicRadarStory(params, options) {
         return this.client.get('/protocols/social/radar/story', { cluster: params.cluster }, ...readOptions(options));
     }
+    /**
+     * The Viral read under the signed-in member's app key (scopes `users:read` and `posts:read`): every network's posts
+     * the build keeps, less the member's own blocks, mutes and hidden posts. Never cached. `status: 'off'` resolves with
+     * no items; a 401 or 403 always throws (a session or key failure is never reported as off).
+     */
+    async getPublicViral(params = {}, options) {
+        return viralRead(await this.client.get('/protocols/social/viral', viralQuery(params), ...readOptions(options)));
+    }
     /** Provider-ranked public accounts with explicit provenance; served from the app's index when a fresh snapshot exists. */
     getPublicPopularProfiles(params) {
         return this.client.get('/protocols/social/popular-profiles', { protocol: params.protocol, limit: params.limit, cursor: params.cursor });

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,9 +57,45 @@ 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
+ * and Minds' own lists, `curator.forYou`). Counts only: never a post's placement, never the cells asked for.
+ * `unavailable` means nothing was applied (the filter is not served to this caller yet, or the judgments are not
+ * there). Under Choose sides every post counts once as kept or left out; `non_political`, `pending` and `unplaced`
+ * (with posts judged maybe) are the not-placed rest. `mix` is Mix sides' band counts over the page served.
+ */
+export interface CompassFilterMeta {
+    status: 'applied' | 'unavailable';
+    mode: 'all' | 'mix' | 'hide' | 'cells';
+    kept: number;
+    left_out: number;
+    unplaced: number;
+    pending: number;
+    non_political: number;
+    uncertain_shown: number;
+    truncated: boolean;
+    rubric?: string;
+    mix?: {
+        econ: {
+            l: number;
+            c: number;
+            r: number;
+        };
+        power: {
+            l: number;
+            m: number;
+            o: number;
+        };
+    };
+}
 export interface PaginationMeta {
     discovery?: DiscoveryLayout;
+    /** Present when the request named `compass`: what the Politics choice did to this page. */
+    compass_filter?: CompassFilterMeta;
     scanned?: number;
     category_filter?: {
         selected: string;
@@ -348,6 +388,21 @@ export interface ListPostsParams extends PaginationParams {
     discovery?: boolean;
     /** Public-only broad category. Requires an enabled app experiment; limit <=25. */
     category?: string;
+    /**
+     * A Politics choice on a discovery, category or Minds list read: `all`, `mix`, `hide`, or cells in the canonical
+     * order `lo,co,ro,lm,cm,rm,ll,cl,rl`, optionally followed by `np`. Any other spelling is 400 `invalid_compass`; on a
+     * profile, group, Following, liked or saved read it is 400 `compass_not_supported`. Mix sides and Choose sides
+     * spend the member's hourly budget (429 `compass_rate_limited`). The page says what it did in
+     * `meta.compass_filter`. Only Minds posts are filtered.
+     */
+    compass?: string;
+    /**
+     * `false` asks once: the first 5xx or 429 is thrown, with no retry and no Retry-After sleep. For a read that holds its
+     * own deadline, such as a Discover feed session's Minds read. Never sent to the server. It rides in the params, not
+     * in a second argument, so a reader wrapped by a function that forwards only its params (as the Minds app wraps the
+     * `posts.list` it hands a feed session, to add a Politics choice) still asks once.
+     */
+    retry?: boolean;
     community_id?: string;
     author_id?: string;
     organization_id?: string;
@@ -355,6 +410,8 @@ export interface ListPostsParams extends PaginationParams {
     tag_ids?: string;
     /** Pass 'me' to return only posts where audience_user_id matches the caller (personal agent feed). */
     audience_user_id?: 'me' | string;
+    /** Return only posts by accounts the authenticated caller follows, newest first (the Following feed). */
+    following?: boolean;
     /** Return only posts the authenticated caller has upvoted. */
     liked?: boolean;
     /**
@@ -584,6 +641,19 @@ 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;
+    /**
+     * In a private group, every member's request: `pending` until an invitee
+     * accepts. Declining stays private, so to anyone else a member who declined
+     * still reads `pending`. Omitted outside private groups and by older APIs.
+     */
+    request_status?: ChatRequestStatus;
 }
 export interface ConversationMemberDetail extends ConversationMember {
     joined_at: string;
@@ -633,6 +703,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. */
@@ -652,6 +728,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;