@recursiv/sdk 0.7.58 → 0.7.59

package/dist/resources/e2ee.d.ts

@@ -20,7 +20,54 @@ export interface E2eeDevice {
      * before 0.7.57.
      */
     lastSeenAt?: string | null;
+    /**
+     * Set on a root that a recorded reset of encrypted chat retired
+     * (`resetAccount`): when the old main device was revoked. Null on every
+     * other device, and on a root that stopped being the root without a
+     * recorded reset: treat that change as unexplained (compare security codes),
+     * never as a reset. Absent on relays without resets.
+     */
+    rootRetiredAt?: string | null;
+}
+/** `requestResetCode`'s answer: when the emailed code expires, and the masked address it went to. */
+export interface E2eeResetCodeSent {
+    expires_at: string;
+    /** Masked, e.g. `b***@minds.com`: show it so the person knows which inbox to open. */
+    sent_to: string;
+}
+/** What `resetAccount` did. The account's encrypted chat starts again from `device`. */
+export interface E2eeAccountReset {
+    reset: true;
+    resetAt: string;
+    /** The main device the reset retired; null when the account had none. */
+    retiredRoot: {
+        deviceId: string;
+        signingKey: string;
+    } | null;
+    /** Every device the reset revoked. */
+    revokedDeviceIds: string[];
+    /** This device, registered as the account's main device (root). */
+    device: E2eeDevice;
+    /**
+     * How many other sessions and API keys of the account were signed out, and
+     * how many AI clients connected over MCP OAuth were disconnected.
+     */
+    signedOut: {
+        sessions: number;
+        keys: number;
+        connectedApps: number;
+    };
 }
+/**
+ * Codes a reset, or a call a reset may be needed for, can be refused with:
+ * - `confirmation_failed` (403): the code is wrong, expired, spent or dead after five wrong tries.
+ * - `code_limit` (409, never 429): too many codes asked for; `details.retryAfterSeconds`.
+ * - `no_email_on_file` (400), `email_delivery_unavailable` (503): no code could be sent.
+ * - `reset_required` (409): from `createLink` when the account's main device is gone with
+ *   nothing left to approve a new one, and from `revokeDevice` on the main device. Only a reset goes on.
+ * - `conflict` (409): the device name or key was used before; start the device again with fresh ones.
+ */
+export type E2eeResetErrorCode = 'confirmation_failed' | 'code_limit' | 'no_email_on_file' | 'email_delivery_unavailable' | 'reset_required' | 'conflict';
 /** Opaque `recursiv-mls-v2-draft1` envelope with base64 MLS bytes. */
 export interface E2eeEnvelope {
     profile: 'recursiv-mls-v2-draft1';
@@ -111,6 +158,12 @@ export interface E2eeStatus {
      * makes, never switch to it on their behalf.
      */
     links?: boolean;
+    /**
+     * True when this network offers this account resetting encrypted chat
+     * (`requestResetCode`, `resetAccount`); never for an account the reset would
+     * refuse, such as a platform owner's. False or absent: do not offer it.
+     */
+    accountReset?: boolean;
 }
 /** A device link's state. An open link past `expiresAt` reads as `cancelled` with `cancelledBy: 'expired'`. */
 export type E2eeLinkState = 'open' | 'approved' | 'completed' | 'cancelled';
@@ -227,11 +280,41 @@ export declare class E2eeResource {
      * `details: E2eeHasDependentsDetails`, so the app can say which devices
      * would be signed out. Call again with `{ cascade: true }` to revoke it and
      * every device chained through it (relays from 0.7.58; older relays ignore
-     * the body and revoke only the device).
+     * the body and revoke only the device). Where this account is offered
+     * resetting encrypted chat (`status().accountReset`), the main device is never
+     * revoked this way: 409 `reset_required`; replace it with `resetAccount`.
      */
     revokeDevice(deviceId: string, input?: {
         cascade?: boolean;
     }): Promise<E2eeRevokeResponse>;
+    /**
+     * Email this account an eight-digit code to reset encrypted chat, and warn
+     * its owner that one was asked for. Only where `status().accountReset` is
+     * true. The account's code budget is shared with other confirmation codes:
+     * over it, a `ConflictError` with code `code_limit` and
+     * `details.retryAfterSeconds` (never a 429). Not retried.
+     */
+    requestResetCode(): Promise<SingleResponse<E2eeResetCodeSent>>;
+    /**
+     * Reset encrypted chat with the emailed code, and make this device the
+     * account's main device: pass it as `registerDevice` takes it, with a fresh
+     * name and key and its own self-signed credential. Every other device of
+     * the account is removed from encrypted chat, and the account is signed out
+     * of every other session and API key on this network (`keep_session_token`
+     * keeps a Better Auth session this device holds). Contacts see that the
+     * security code changed. A wrong, expired or spent code: `confirmation_failed`
+     * (403), nothing changed. Sending the same request again after it succeeded
+     * (from the same sign-in) answers the same result, so a retry after a lost
+     * answer is safe.
+     */
+    resetAccount(input: {
+        email_code: string;
+        device_name: string;
+        realm: string;
+        signing_key: string;
+        credential: Record<string, unknown>;
+        keep_session_token?: string;
+    }): Promise<SingleResponse<E2eeAccountReset>>;
     /** Publish one-time key packages for one of your devices; `available` is how many it now has. */
     publishKeyPackages(input: {
         device_id: string;
@@ -328,7 +411,9 @@ export declare class E2eeResource {
     /**
      * Start linking this new, not yet registered device: `POST /e2ee/links`.
      * Answers the open link (180 s on the relay's clock). A new link cancels
-     * this sign-in's previous open link. `label` is 1-48 letters, numbers,
+     * this sign-in's previous open link. `reset_required` (409): the account's
+     * main device is gone and nothing is left to approve this one; only
+     * `resetAccount` goes on. `label` is 1-48 letters, numbers,
      * spaces and `. , ' ( ) + -`; reserved words are refused (`invalid_label`).
      * Not retried: a 5xx is answered at once, and the caller decides.
      */

package/dist/resources/e2ee.js

@@ -35,11 +35,38 @@ export class E2eeResource {
      * `details: E2eeHasDependentsDetails`, so the app can say which devices
      * would be signed out. Call again with `{ cascade: true }` to revoke it and
      * every device chained through it (relays from 0.7.58; older relays ignore
-     * the body and revoke only the device).
+     * the body and revoke only the device). Where this account is offered
+     * resetting encrypted chat (`status().accountReset`), the main device is never
+     * revoked this way: 409 `reset_required`; replace it with `resetAccount`.
      */
     revokeDevice(deviceId, input) {
         return this.client.post(`/e2ee/devices/${encodeURIComponent(deviceId)}/revoke`, input ?? {});
     }
+    /**
+     * Email this account an eight-digit code to reset encrypted chat, and warn
+     * its owner that one was asked for. Only where `status().accountReset` is
+     * true. The account's code budget is shared with other confirmation codes:
+     * over it, a `ConflictError` with code `code_limit` and
+     * `details.retryAfterSeconds` (never a 429). Not retried.
+     */
+    requestResetCode() {
+        return this.client.post('/e2ee/account/reset-code', {}, { retry: false });
+    }
+    /**
+     * Reset encrypted chat with the emailed code, and make this device the
+     * account's main device: pass it as `registerDevice` takes it, with a fresh
+     * name and key and its own self-signed credential. Every other device of
+     * the account is removed from encrypted chat, and the account is signed out
+     * of every other session and API key on this network (`keep_session_token`
+     * keeps a Better Auth session this device holds). Contacts see that the
+     * security code changed. A wrong, expired or spent code: `confirmation_failed`
+     * (403), nothing changed. Sending the same request again after it succeeded
+     * (from the same sign-in) answers the same result, so a retry after a lost
+     * answer is safe.
+     */
+    resetAccount(input) {
+        return this.client.post('/e2ee/account/reset', input, { retry: true });
+    }
     /** Publish one-time key packages for one of your devices; `available` is how many it now has. */
     publishKeyPackages(input) {
         return this.client.post('/e2ee/key-packages', input);
@@ -109,7 +136,9 @@ export class E2eeResource {
     /**
      * Start linking this new, not yet registered device: `POST /e2ee/links`.
      * Answers the open link (180 s on the relay's clock). A new link cancels
-     * this sign-in's previous open link. `label` is 1-48 letters, numbers,
+     * this sign-in's previous open link. `reset_required` (409): the account's
+     * main device is gone and nothing is left to approve this one; only
+     * `resetAccount` goes on. `label` is 1-48 letters, numbers,
      * spaces and `. , ' ( ) + -`; reserved words are refused (`invalid_label`).
      * Not retried: a 5xx is answered at once, and the caller decides.
      */

package/dist/resources/email.d.ts

@@ -112,15 +112,39 @@ export interface SendEmailInput {
     reply_to?: string;
     /** File attachments (max 10). Content must be base64-encoded. */
     attachments?: EmailAttachment[];
+    /**
+     * Defaults to `'marketing'`, which is held unless the recipient has given
+     * marketing consent. Pass `'transactional'` for receipts, invites,
+     * confirmations and alerts.
+     */
+    category?: 'transactional' | 'product' | 'marketing';
+}
+export interface SendEmailMessage {
+    id: string | null;
+    to: string;
+    /** `queued`/`sent`/`retry` are on their way; `skipped`/`suppressed`/`failed`/`duplicate` are not. */
+    status: 'queued' | 'sent' | 'retry' | 'failed' | 'suppressed' | 'skipped' | 'duplicate' | (string & {});
+    /** Why a held recipient was not sent, e.g. "marketing consent not granted". */
+    reason?: string;
 }
 export interface SendEmailResult {
-    id: string;
-    status: string;
+    id: string | null;
+    /** `queued`: every recipient; `partial`: some held (see `messages`). A send where all were held throws `EmailNotSentError`. */
+    status: 'queued' | 'partial' | 'skipped' | (string & {});
+    messages?: SendEmailMessage[];
+    /** Present when any recipient was held: says why, in words. */
+    hint?: string;
 }
 export declare class EmailResource {
     private client;
     constructor(client: HttpClient);
-    /** Send a transactional email (uses org's BYOK Resend key if configured) */
+    /**
+     * Send an email as the organization (its BYOK Resend key when configured).
+     * Set `category: 'transactional'` for receipts, invites and alerts: the
+     * default is `'marketing'`, which needs the recipient's consent.
+     * Throws `EmailNotSentError` when every recipient was held; check
+     * `status === 'partial'` and `messages` for a send that reached only some.
+     */
     send(input: SendEmailInput): Promise<SingleResponse<SendEmailResult>>;
     /** List all campaigns */
     listCampaigns(): Promise<SingleResponse<CampaignSummary[]>>;

package/dist/resources/email.js

@@ -1,11 +1,26 @@
+import { EmailNotSentError } from '../errors.js';
 export class EmailResource {
     client;
     constructor(client) {
         this.client = client;
     }
-    /** Send a transactional email (uses org's BYOK Resend key if configured) */
-    send(input) {
-        return this.client.post('/email/send', input);
+    /**
+     * Send an email as the organization (its BYOK Resend key when configured).
+     * Set `category: 'transactional'` for receipts, invites and alerts: the
+     * default is `'marketing'`, which needs the recipient's consent.
+     * Throws `EmailNotSentError` when every recipient was held; check
+     * `status === 'partial'` and `messages` for a send that reached only some.
+     */
+    async send(input) {
+        const res = (await this.client.post('/email/send', input));
+        if (res?.data?.status === 'skipped') {
+            throw new EmailNotSentError({
+                message: 'Email not sent: every recipient was held.',
+                hint: res.data.hint,
+                details: res.data,
+            });
+        }
+        return res;
     }
     /** List all campaigns */
     listCampaigns() {

package/dist/resources/env-vars.d.ts

@@ -37,6 +37,25 @@ export interface DeleteEnvVarParams {
     /** Omit to remove the variable from every environment. */
     environment?: EnvVarEnvironment;
 }
+export interface CreateProjectApiKeyInput {
+    project_id: string;
+    /** The env var that receives the key. UPPER_SNAKE_CASE, e.g. RECURSIV_API_KEY. */
+    key: string;
+    /** Defaults to databases:read + databases:write. Never more than the calling key holds; never admin. */
+    scopes?: string[];
+    /** Defaults to 'both'. */
+    environment?: EnvVarEnvironment;
+}
+export interface CreateProjectApiKeyResult {
+    key: string;
+    environment: EnvVarEnvironment;
+    api_key_id: string;
+    /** The key's public prefix, for recognizing it in a key list. Not the key. */
+    api_key_prefix: string;
+    scopes: string[];
+    /** How many earlier keys minted into this env var were revoked. */
+    revoked_previous: number;
+}
 export declare class EnvVarsResource {
     private client;
     constructor(client: HttpClient);
@@ -47,6 +66,12 @@ export declare class EnvVarsResource {
      * changes what runs in production.
      */
     set(input: SetEnvVarInput): Promise<SingleResponse<Omit<EnvVar, 'value' | 'source' | 'updated_at'>>>;
+    /**
+     * Mint a project-bound API key straight into an env var. The key value goes
+     * to the encrypted variable and is never returned. Running it again rotates:
+     * the previous key in that variable is revoked. Requires project admin.
+     */
+    createProjectApiKey(input: CreateProjectApiKeyInput): Promise<SingleResponse<CreateProjectApiKeyResult>>;
     delete(params: DeleteEnvVarParams): Promise<SingleResponse<{
         key: string;
         deleted: boolean;

package/dist/resources/env-vars.js

@@ -17,6 +17,14 @@ export class EnvVarsResource {
     async set(input) {
         return this.client.put('/env-vars', input);
     }
+    /**
+     * Mint a project-bound API key straight into an env var. The key value goes
+     * to the encrypted variable and is never returned. Running it again rotates:
+     * the previous key in that variable is revoked. Requires project admin.
+     */
+    async createProjectApiKey(input) {
+        return this.client.post('/env-vars/api-key', input);
+    }
     async delete(params) {
         const query = new URLSearchParams({ project_id: params.project_id, key: params.key });
         if (params.environment)

package/dist/resources/moderation.d.ts

@@ -63,6 +63,18 @@ export interface ApplyModerationActionInput {
     actor_type?: 'human' | 'ai' | 'system';
     source_report_id?: string;
 }
+/** What a granted agent may do on the report queue: shadow reads it; act also resolves and dismisses. */
+export type AgentModerationMode = 'shadow' | 'act';
+/** A network admin's grant letting one AI agent work the report queue. */
+export interface AgentModerationGrant {
+    id: string;
+    network_id: string | null;
+    agent_id: string;
+    mode: AgentModerationMode;
+    granted_by_id: string | null;
+    created_at: string;
+    revoked_at: string | null;
+}
 export declare class ModerationResource {
     private client;
     constructor(client: HttpClient);
@@ -101,4 +113,14 @@ export declare class ModerationResource {
         action_id: string;
         outcome: 'upheld' | 'overturned';
     }>>;
+    /** Admin: the network's active agent moderation grants. */
+    listAgentGrants(): Promise<SingleResponse<AgentModerationGrant[]>>;
+    /**
+     * Admin: let an AI agent in the caller's network work the report queue. An
+     * active grant is replaced. The agent's own key also needs the
+     * `moderation:agent` scope.
+     */
+    grantAgent(agentId: string, mode: AgentModerationMode): Promise<SingleResponse<AgentModerationGrant>>;
+    /** Admin: revoke an agent's active moderation grant. */
+    revokeAgent(agentId: string): Promise<SingleResponse<AgentModerationGrant>>;
 }

package/dist/resources/moderation.js

@@ -34,4 +34,20 @@ export class ModerationResource {
     resolveAppeal(appealId, input) {
         return this.client.post(`/moderation/appeals/${encodeURIComponent(appealId)}/resolve`, input);
     }
+    /** Admin: the network's active agent moderation grants. */
+    listAgentGrants() {
+        return this.client.get('/moderation/agent-grants');
+    }
+    /**
+     * Admin: let an AI agent in the caller's network work the report queue. An
+     * active grant is replaced. The agent's own key also needs the
+     * `moderation:agent` scope.
+     */
+    grantAgent(agentId, mode) {
+        return this.client.post('/moderation/agent-grants', { agent_id: agentId, mode });
+    }
+    /** Admin: revoke an agent's active moderation grant. */
+    revokeAgent(agentId) {
+        return this.client.delete(`/moderation/agent-grants/${encodeURIComponent(agentId)}`);
+    }
 }

package/dist/resources/posts.d.ts

@@ -17,7 +17,7 @@ export interface CategoryOrderMeta {
 export declare class PostsResource {
     private client;
     constructor(client: HttpClient);
-    /** List posts with optional filters */
+    /** List posts with optional filters. `retry: false` asks once and is never sent (see ListPostsParams.retry). */
     list(params?: ListPostsParams): Promise<PaginatedResponse<Post>>;
     /**
      * Broad categories currently enabled for public posts in this app, in the order this member should see

package/dist/resources/posts.js

@@ -3,9 +3,13 @@ export class PostsResource {
     constructor(client) {
         this.client = client;
     }
-    /** List posts with optional filters */
+    /** List posts with optional filters. `retry: false` asks once and is never sent (see ListPostsParams.retry). */
     list(params) {
-        return this.client.get('/posts', params);
+        // Without `retry`, the same request older SDKs make.
+        if (!params || !('retry' in params))
+            return this.client.get('/posts', params);
+        const { retry, ...query } = params;
+        return retry === false ? this.client.get('/posts', query, { retry: false }) : this.client.get('/posts', query);
     }
     /**
      * Broad categories currently enabled for public posts in this app, in the order this member should see

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[];
@@ -1290,6 +1307,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 +1602,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>>;
@@ -1477,6 +1678,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;