@recursiv/sdk 0.7.46 → 0.7.48

package/README.md

@@ -75,7 +75,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | Resource | Key methods |
 |----------|------------|
 | `r.agents` | `create`, `update`, `chat`, `chatStream`, `grantProjectAccess`, `conversations` |
-| `r.e2ee` | `registerDevice`, `devices`, `revokeDevice`, `publishKeyPackages`, `claimKeyPackage`, `appendEvent`, `events`, `acknowledge` (flag-gated E2EE v2 transport) |
+| `r.e2ee` | `registerDevice`, `devices`, `revokeDevice`, `publishKeyPackages`, `keyPackageStatus`, `claimKeyPackage`, `appendEvent`, `events`, `acknowledge` (flag-gated E2EE v2 transport) |
 | `r.brain` | `sendMessage` |
 | `r.commands` | `execute`, `gatePrompt` |
 | `r.projectBrain` | `tasks`, `decisions`, `milestones`, `completeTask`, `usage` |
@@ -514,8 +514,10 @@ const { data: preview } = await r.protocols.prepareNativeReply({
   parent: { protocol: 'bluesky', nativeId: selectedPost.nativeId },
   accountIds: [blueskyAccount.id, activityPubAccount.id],
   linkedPostAccountIds: [activityPubAccount.id],
+  // Optional, needs each account's `publish_media` capability:
+  media: [{ url: uploadedImageUrl, alt: memberWrittenAltText }],
 })
-// Review each delivery's account, protocol, kind, parent and exact wireText.
+// Review each delivery's account, protocol, kind, parent, media and exact wireText.
 // After the user approves selected delivery IDs:
 await r.protocols.submitNativeReply(preview.id, { approve: true, deliveryIds: approvedDeliveryIds })
 ```
@@ -590,7 +592,7 @@ connections or signing authority. Missing configuration or unavailable safety ch
 closed. Signed-in members continue using `getPublicConversation` to apply personal
 blocks/mutes as well. All reply and account endpoints still require authentication.
 
-Standalone public text publication uses `protocols.prepareNativePost({ clientMutationId, text, accountIds })`, then explicitly approved `submitNativePost`. Keep the same mutation ID after uncertain preparation; previously attempted deliveries are reconciled without resending. `nativePostStatus` and paginated `nativePostHistory` expose private app/user-owned outcomes. Review current own posts with `prepareNativePostRemoval`, then approve exact removal IDs through `removeNativePost`. Check connected-account `publish_text` capabilities; only explicitly enabled apps may publish. Text is sent unchanged, public only, with each provider’s actual limits. These methods do not accept media, a reply parent or caller-supplied authority.
+Standalone public publication uses `protocols.prepareNativePost({ clientMutationId, text, accountIds, media? })`, then explicitly approved `submitNativePost`. Keep the same mutation ID after uncertain preparation; previously attempted deliveries are reconciled without resending. `nativePostStatus` and paginated `nativePostHistory` expose private app/user-owned outcomes. Review current own posts with `prepareNativePostRemoval`, then approve exact removal IDs through `removeNativePost`. Check connected-account `publish_text` capabilities; only explicitly enabled apps may publish. Text is sent unchanged, public only, with each provider’s actual limits. Optional `media` is a `NativeMediaInput[]` of at most four already-uploaded Minds images (`{ url, alt?, width?, height?, mimeType? }`, JPEG/PNG/WebP/GIF, Minds-hosted HTTPS URLs only, a Mastodon GIF must be the only attachment). It additionally requires the account's `publish_media` capability; accounts connected before image permissions existed must reconnect. Pass the member's own `alt` — an omitted one is sent as an empty description, never an invented one — and read `receipt.media` (`{ count, alt_missing }`) after sending. These methods still do not accept a reply parent or caller-supplied authority.
 
 For Bluesky accounts advertising `quote`, prepare the same publication with `quote: { protocol: 'bluesky', nativeId: sourceAtUri }`. The server resolves the exact source CID using each connected account, checks quote permission and Minds safety, and rechecks before writing. Review each delivery’s `quote` alongside the account and comment before submitting. Changed or unavailable sources cannot publish; uncertain deliveries reconcile the original record key. ActivityPub/Nostr quotes are not provided by this method. Public post reads include at most one filtered `quote` with `state: 'available'` and `post`, or `state: 'unavailable'` without source content. Available quotes may include `embeddedReferences`: exact standalone source-reference lines in the unchanged outer `text`. Omit them only when the quoted original is actually visible; retain them for unavailable or locally hidden quotes. Nostr references are decoded and matched by the server, without following relay hints.
 

package/dist/client.d.ts

@@ -29,7 +29,10 @@ export declare class HttpClient {
     apiKeyAuthHeader(): Record<string, string>;
     private getAuthHeaders;
     private handleResponse;
-    get<T>(path: string, params?: Record<string, unknown>): Promise<T>;
+    /** `retry: false` answers after one attempt: for a caller with its own deadline, a retried 5xx only adds wait. */
+    get<T>(path: string, params?: Record<string, unknown>, options?: {
+        retry?: boolean;
+    }): Promise<T>;
     post<T>(path: string, body?: unknown, options?: {
         retry?: boolean;
     }): Promise<T>;

package/dist/client.js

@@ -1,4 +1,4 @@
-import { RecursivError, AuthenticationError, AuthorizationError, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, } from './errors.js';
+import { RecursivError, AuthenticationError, AuthorizationError, NotFoundError, ValidationError, InsufficientCreditsError, RateLimitError, ConflictError, errorBodyFromResponse, httpStatusMessage, } from './errors.js';
 const DEFAULT_BASE_URL = 'https://api.recursiv.io/api/v1';
 export class HttpClient {
     #apiKey;
@@ -118,8 +118,20 @@ export class HttpClient {
                 code: 'no_response',
             });
         }
+        // From here on the server answered. Every error below carries its HTTP
+        // status, so callers can tell a refusal from an unreachable server; only a
+        // fetch that produced no response (network failure, abort) is statusless.
         if (response.ok) {
-            return response.json();
+            try {
+                return (await response.json());
+            }
+            catch {
+                throw new RecursivError(response.status, {
+                    type: 'api_error',
+                    message: `${httpStatusMessage(response.status, response.statusText)}: response body is not valid JSON`,
+                    code: 'invalid_response',
+                });
+            }
         }
         let body;
         try {
@@ -128,16 +140,13 @@ export class HttpClient {
         catch {
             throw new RecursivError(response.status, {
                 type: 'api_error',
-                message: `HTTP ${response.status}: ${response.statusText}`,
+                message: httpStatusMessage(response.status, response.statusText),
                 code: 'unknown_error',
             });
         }
-        // Handle both { error: { message, type, code } } (standard) and
-        // { error: "string" } (legacy dispatcher routes) response formats
-        const rawErr = body.error;
-        const err = typeof rawErr === 'string'
-            ? { type: 'api_error', message: rawErr, code: 'unknown_error' }
-            : rawErr;
+        // Handles { error: { message, type, code } } (standard), { error: "string" }
+        // (legacy dispatcher routes) and any other JSON, which gets a generic body.
+        const err = errorBodyFromResponse(response.status, response.statusText, body);
         switch (response.status) {
             case 400:
                 throw new ValidationError(err);
@@ -157,12 +166,11 @@ export class HttpClient {
                 throw new RecursivError(response.status, err);
         }
     }
-    async get(path, params) {
+    /** `retry: false` answers after one attempt: for a caller with its own deadline, a retried 5xx only adds wait. */
+    async get(path, params, options) {
         const url = this.buildUrl(path, params);
-        const response = await this.fetchWithRetry(url, {
-            method: 'GET',
-            headers: this.getAuthHeaders(),
-        });
+        const request = { method: 'GET', headers: this.getAuthHeaders() };
+        const response = await (options?.retry === false ? this.fetchWithTimeout(url, request) : this.fetchWithRetry(url, request));
         return this.handleResponse(response);
     }
     async post(path, body, options) {

package/dist/errors.d.ts

@@ -1,4 +1,15 @@
 import type { ApiErrorBody } from './types.js';
+/** `HTTP 403: Forbidden`, or `HTTP 403` when the response has no reason phrase (HTTP/2). */
+export declare function httpStatusMessage(status: number, statusText?: string): string;
+/**
+ * Turn whatever JSON an error response carried into a complete error body.
+ * The standard shape passes through unchanged; the legacy `{ error: "text" }`
+ * shape keeps its text; anything else (no `error`, a null/number/array error,
+ * a non-object body) becomes a generic body. A partial error object keeps the
+ * fields it has and gains defaults for `type`, `code` and `message`, so the
+ * thrown error always has the response status and never a TypeError.
+ */
+export declare function errorBodyFromResponse(status: number, statusText: string | undefined, body: unknown): ApiErrorBody['error'];
 export declare class RecursivError extends Error {
     readonly status: number;
     readonly type: string;

package/dist/errors.js

@@ -1,3 +1,30 @@
+/** `HTTP 403: Forbidden`, or `HTTP 403` when the response has no reason phrase (HTTP/2). */
+export function httpStatusMessage(status, statusText) {
+    return statusText ? `HTTP ${status}: ${statusText}` : `HTTP ${status}`;
+}
+/**
+ * Turn whatever JSON an error response carried into a complete error body.
+ * The standard shape passes through unchanged; the legacy `{ error: "text" }`
+ * shape keeps its text; anything else (no `error`, a null/number/array error,
+ * a non-object body) becomes a generic body. A partial error object keeps the
+ * fields it has and gains defaults for `type`, `code` and `message`, so the
+ * thrown error always has the response status and never a TypeError.
+ */
+export function errorBodyFromResponse(status, statusText, body) {
+    const fallback = { type: 'api_error', code: 'unknown_error', message: httpStatusMessage(status, statusText) };
+    const raw = body && typeof body === 'object' && !Array.isArray(body) ? body.error : undefined;
+    if (typeof raw === 'string')
+        return { ...fallback, message: raw };
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return fallback;
+    const error = raw;
+    return {
+        ...error,
+        type: typeof error.type === 'string' ? error.type : fallback.type,
+        code: typeof error.code === 'string' ? error.code : fallback.code,
+        message: typeof error.message === 'string' ? error.message : fallback.message,
+    };
+}
 function composeMessage(body) {
     // Surface the hint inline so LLM callers see the resolution path without
     // having to inspect a structured field. The base message stays first so

package/dist/index.d.ts

@@ -144,7 +144,7 @@ export { UsersResource } from './resources/users.js';
 export { CommunitiesResource } from './resources/communities.js';
 export { ChatResource } from './resources/chat.js';
 export { E2eeResource } from './resources/e2ee.js';
-export type { E2eeDevice, E2eeEnvelope, E2eeEvent } from './resources/e2ee.js';
+export type { E2eeDevice, E2eeEnvelope, E2eeEvent, E2eeKeyPackageStatus } from './resources/e2ee.js';
 export { ProjectsResource } from './resources/projects.js';
 export { AgentsResource, SUPPORTED_MODELS } from './resources/agents.js';
 export { EvidenceResource } from './resources/evidence.js';
@@ -198,7 +198,7 @@ export type { UploadMediaInput, UploadUrlInput, UploadUrlResult } from './resour
 export { WalletResource } from './resources/wallet.js';
 export { ProtocolsResource } from './resources/protocols.js';
 export { PROTOCOL_ADAPTER_MATURITIES, PROTOCOL_CAPABILITY_OPERATIONS, PROTOCOL_CAPABILITY_STATUSES, } from './resources/protocols.js';
-export type { SocialProfile, SocialSubscription, SocialSubscriptionChange, SocialProfilePage, SocialNetwork, SocialPost, SocialConversation, SocialTrend, SocialTrendProvenance, SocialTrends, SocialTrendFeed, SocialPopularProfiles, SocialAuthorFeed, SocialFollowingFeed, SocialFollowingSource, SearchPublicProfilesParams, SearchPublicPostsParams, SocialPostSearch, HostedProtocolConnections, HostedProtocol, HostedProtocolIdentity, HostedNostrChallenge, HostedNostrIdentityProof, NativeNostrPrepareInput, NativeNostrPrepared, NativeNostrAccount, NativeNostrPostState, NativeNostrReceipt, NativeSocialProtocol, FederationIdentity, FederationIdentityView, NativeSocialAccount, NativeSocialCallbackInput, NativeReplyPrepareInput, NativePostPrepareInput, NativePostBatch, NativePostHistory, NativeFollowSourceInput, NativeFollowPrepareInput, NativeFollowTarget, NativeFollowReceipt, NativeFollowState, NativeFollowReview, NativeLikeSourceInput, NativeRepostSourceInput, NativeLikePrepareInput, NativeRepostPrepareInput, NativeLikeTarget, NativeRepostTarget, NativeLikeReceipt, NativeRepostReceipt, NativeLikeState, NativeRepostState, NativeLikeReview, NativeRepostReview, NativeReplyReceipt, NativeReplyBatch, NativeReplyHistory, NativeDelegatedReplyHistoryItem, NativeNostrReplyResult, NativeNostrReplyHistoryItem, NativeReplyRemovalReceipt, NativeReplyRemovalPreview, SocialSourceRef, SocialSourceControl, SocialSourceControlChange, HostedPostPreview, ConnectHostedIdentityInput, PreviewHostedPostInput, PublishHostedPostInput, ListProtocolCandidatesParams, ProtocolAdapterMaturity, ProtocolAdapterMetadata, ProtocolCandidateListResponse, ProtocolCandidatePageMeta, ProtocolCapabilityOperation, ProtocolCapabilityStatus, ProtocolCollectionStatus, ProtocolIngestionReplayResult, ProtocolIngestionStatus, ProtocolQuarantinedCandidate, ProtocolRefreshResult, ProtocolSettings, ProtocolSettingsUpdateResult, ReplayProtocolIngestionJobInput, UpdateSettingsInput as UpdateProtocolSettingsInput, } from './resources/protocols.js';
+export type { SocialProfile, SocialSubscription, SocialSubscriptionChange, SocialProfilePage, SocialNetwork, SocialPost, SocialConversation, SocialTrend, SocialTrendProvenance, SocialTrends, SocialTrendFeed, SocialPopularProfiles, SocialAuthorFeed, SocialFollowingFeed, SocialFollowingSource, SearchPublicProfilesParams, SearchPublicPostsParams, SocialPostSearch, HostedProtocolConnections, HostedProtocol, HostedProtocolIdentity, HostedNostrChallenge, HostedNostrIdentityProof, NativeNostrPrepareInput, NativeNostrPrepared, NativeNostrAccount, NativeNostrPostState, NativeNostrReceipt, NativeSocialProtocol, FederationIdentity, FederationIdentityView, NativeSocialAccount, NativeSocialCallbackInput, NativeReplyPrepareInput, NativePostPrepareInput, NativeMediaInput, NativeMediaItem, NativePostBatch, NativePostHistory, NativeFollowSourceInput, NativeFollowPrepareInput, NativeFollowTarget, NativeFollowReceipt, NativeFollowState, NativeFollowReview, NativeLikeSourceInput, NativeRepostSourceInput, NativeLikePrepareInput, NativeRepostPrepareInput, NativeLikeTarget, NativeRepostTarget, NativeLikeReceipt, NativeRepostReceipt, NativeLikeState, NativeRepostState, NativeLikeReview, NativeRepostReview, NativeReplyReceipt, NativeReplyBatch, NativeReplyHistory, NativeDelegatedReplyHistoryItem, NativeNostrReplyResult, NativeNostrReplyHistoryItem, NativeReplyRemovalReceipt, NativeReplyRemovalPreview, SocialSourceRef, SocialSourceControl, SocialSourceControlChange, HostedPostPreview, ConnectHostedIdentityInput, PreviewHostedPostInput, PublishHostedPostInput, ListProtocolCandidatesParams, ProtocolAdapterMaturity, ProtocolAdapterMetadata, ProtocolCandidateListResponse, ProtocolCandidatePageMeta, ProtocolCapabilityOperation, ProtocolCapabilityStatus, ProtocolCollectionStatus, ProtocolIngestionReplayResult, ProtocolIngestionStatus, ProtocolQuarantinedCandidate, ProtocolRefreshResult, ProtocolSettings, ProtocolSettingsUpdateResult, ReplayProtocolIngestionJobInput, UpdateSettingsInput as UpdateProtocolSettingsInput, } from './resources/protocols.js';
 export { InboxResource } from './resources/inbox.js';
 export { NetworkResource } from './resources/network.js';
 export { SimulatorResource } from './resources/simulator.js';

package/dist/resources/deployments.d.ts

@@ -41,6 +41,12 @@ export interface DeleteDeploymentParams {
 export interface PrepareProtocolServersInput {
     project_id: string;
     network_id: string;
+    /**
+     * `production` reserves the stack in the operator's production environment
+     * with the API's HOSTED_* settings (handle domain, SMTP, invites, relay name);
+     * hostnames must be allow-listed. Default `staging`.
+     */
+    target?: 'staging' | 'production';
     hosts: {
         pds: string;
         activitypub: string;
@@ -52,7 +58,9 @@ export interface PrepareProtocolServersInput {
         activitypub: string;
         nostr: string;
     };
+    /** A staging PLC, or https://plc.directory for a production PDS whose operator set HOSTED_PDS_PRODUCTION_PLC=true. */
     test_plc_url: string;
+    /** Relay publisher whitelist; may be empty for a public production relay. */
     test_publisher_pubkeys: string[];
 }
 export interface PreparedProtocolServers {

package/dist/resources/discovery.d.ts

@@ -1,7 +1,7 @@
 import type { DiscoveryLayout, Post } from '../types.js';
 import type { DiscoveryLearning } from './discovery-learning.js';
 import type { PostsResource } from './posts.js';
-import type { ProtocolsResource, SocialNetwork, SocialPost, SocialRadar } from './protocols.js';
+import type { ProtocolsResource, SocialNetwork, SocialPost, SocialRadar, SocialRadarPosts } from './protocols.js';
 export type DiscoveryRecommendationKind = 'groups' | 'people' | 'tags';
 export interface DiscoveryGroupCandidate {
     id: string;
@@ -82,6 +82,21 @@ export type DiscoveryRadarSource = (params: {
 }) => Promise<{
     data: SocialRadar;
 }>;
+/**
+ * Readers for a story's own member posts. A member found by the radar's search lane is almost never
+ * in the page's hot or trend window, so without these a story counts posts it cannot show.
+ * Optional, like the radar: an older server answers 404 and the story shows the posts its page carried.
+ */
+export interface DiscoveryRadarMemberSources {
+    social?: (params: {
+        cluster: string;
+    }) => Promise<{
+        data: SocialRadarPosts;
+    }>;
+    minds?: (id: string) => Promise<{
+        data: Post;
+    }>;
+}
 export type DiscoveryRadarPresentation = 'breaking' | 'story';
 export type DiscoveryPostItem = {
     key: string;
@@ -153,6 +168,7 @@ export declare class DiscoveryFeedSession {
     private category?;
     private learning?;
     private recommend?;
+    private members?;
     private streams;
     private pending;
     private seen;
@@ -162,13 +178,22 @@ export declare class DiscoveryFeedSession {
     private clusters;
     private radarUsed;
     private radar?;
-    constructor(posts: Pick<PostsResource, 'list'>, protocols: Pick<ProtocolsResource, 'getPublicTrends' | 'getPublicTrendFeed'>, networks: SocialNetwork[], category?: string | undefined, source?: string, learning?: DiscoveryLearning | undefined, recommend?: DiscoveryRecommendationSources | undefined, radar?: DiscoveryRadarSource);
+    /** Page 0's radar read, started before its stream reads rather than after the slowest of them. */
+    private radarLoading;
+    /** Member reads per story, started as soon as the story is known and shared by whichever page shows it. */
+    private memberReads;
+    constructor(posts: Pick<PostsResource, 'list'>, protocols: Pick<ProtocolsResource, 'getPublicTrends' | 'getPublicTrendFeed'>, networks: SocialNetwork[], category?: string | undefined, source?: string, learning?: DiscoveryLearning | undefined, recommend?: DiscoveryRecommendationSources | undefined, radar?: DiscoveryRadarSource, members?: DiscoveryRadarMemberSources | undefined);
     retryFailed(): void;
     next(): Promise<DiscoveryFeedPage>;
     private read;
     private readPage;
     /** Page 0: the top breaking cluster, else the top cluster. Every second later page: the next unused story or viral cluster. */
     private radarCluster;
+    /** Page 0: the top breaking cluster, else the top cluster. Later pages: the next unused story or viral cluster. */
+    private pickCluster;
+    /** The story's members as feed items, read once per story and bounded to three seconds; a failed read is simply none. */
+    private memberPosts;
+    private readMembers;
     private loadRadar;
     private radarModule;
     private recommendation;

package/dist/resources/discovery.js

@@ -4,6 +4,10 @@ export const RECOMMENDATION_MAX_ITEMS = 6;
 /** Clusters read from the radar per session; the server never holds more. */
 export const RADAR_MAX_CLUSTERS = 40;
 const RADAR_MAX_MEMBERS = 12;
+/** Minds members read one by one, so a story reads at most this many. */
+const RADAR_MAX_MINDS_READS = 4;
+/** A discovery page holds its own deadline: a retried 5xx from one provider only makes the whole page wait. */
+const NO_RETRY = { retry: false };
 const RECOMMENDATION_KINDS = ['groups', 'people', 'tags'];
 const nonEmpty = (value) => typeof value === 'string' && value.trim().length > 0 && value.length <= 512;
 function recommendationItem(kind, candidate) {
@@ -119,6 +123,7 @@ export class DiscoveryFeedSession {
     category;
     learning;
     recommend;
+    members;
     streams;
     pending = null;
     seen = new Set();
@@ -128,12 +133,17 @@ export class DiscoveryFeedSession {
     clusters = null;
     radarUsed = new Set();
     radar;
-    constructor(posts, protocols, networks, category, source, learning, recommend, radar) {
+    /** Page 0's radar read, started before its stream reads rather than after the slowest of them. */
+    radarLoading = null;
+    /** Member reads per story, started as soon as the story is known and shared by whichever page shows it. */
+    memberReads = new Map();
+    constructor(posts, protocols, networks, category, source, learning, recommend, radar, members) {
         this.posts = posts;
         this.protocols = protocols;
         this.category = category;
         this.learning = learning;
         this.recommend = recommend;
+        this.members = members;
         // The radar clusters across every source, so a feed narrowed to one network carries none.
         if (!source || source === 'all')
             this.radar = radar;
@@ -174,7 +184,7 @@ export class DiscoveryFeedSession {
                 stream.done = true;
                 return { items: [], layout: ordinary, partial: false };
             }
-            const { data } = await this.protocols.getPublicTrendFeed({ ...params, protocol: stream.protocol, topic: topic.topic, cursor: topic.cursor });
+            const { data } = await this.protocols.getPublicTrendFeed({ ...params, protocol: stream.protocol, topic: topic.topic, cursor: topic.cursor }, NO_RETRY);
             validatePosts(data);
             if (data.trend.protocol !== stream.protocol || data.trend.nativeId !== topic.topic)
                 throw new Error('Invalid discovery topic');
@@ -185,7 +195,7 @@ export class DiscoveryFeedSession {
             stream.done = !stream.topics.length;
             return { items: data.items.map(post => ({ key: key(post.protocol, post.nativeId), kind: 'social', post })), layout: data.discovery ?? ordinary, partial: data.categoryFilter?.status === 'partial' };
         }
-        const { data } = await this.protocols.getPublicTrends({ ...params, protocol: stream.protocol, cursor: stream.cursor, includePreviews: true });
+        const { data } = await 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') {
@@ -204,6 +214,13 @@ export class DiscoveryFeedSession {
         return { items: data.items.map(post => ({ key: key(post.protocol, post.nativeId), kind: 'social', post })), layout: data.discovery ?? ordinary, partial: data.categoryFilter?.status === 'partial' };
     }
     async readPage() {
+        // The radar is one small snapshot read: start it with the page, not after the slowest provider,
+        // and start the lead story's member reads the moment the snapshot names it.
+        if (this.page === 0 && this.radar && !this.radarLoading) {
+            this.radarLoading = this.loadRadar();
+            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);
         const native = active.find(stream => stream.protocol === 'minds');
         const remote = active.filter(stream => stream.protocol !== 'minds');
@@ -255,8 +272,12 @@ export class DiscoveryFeedSession {
         let clusterItems = [];
         if (cluster) {
             const members = new Set(cluster.memberKeys);
+            const onPage = remaining.filter(row => members.has(row.item.key)).map(row => row.item);
+            const carried = new Set(onPage.map(item => item.key));
+            // Members this page did not carry come from the story's own reads; one an earlier page showed stays shown there.
+            const read = (await this.memberPosts(cluster)).filter(item => !carried.has(item.key) && !this.seen.has(item.key));
             // Under the story, posts keep the server's member order: the lead media member first, then by member score.
-            clusterItems = remaining.filter(row => members.has(row.item.key)).map(row => row.item).sort((a, b) => cluster.memberKeys.indexOf(a.key) - cluster.memberKeys.indexOf(b.key));
+            clusterItems = [...onPage, ...read].sort((a, b) => cluster.memberKeys.indexOf(a.key) - cluster.memberKeys.indexOf(b.key));
             remaining = remaining.filter(row => !members.has(row.item.key));
             for (const memberKey of cluster.memberKeys)
                 this.seen.add(memberKey);
@@ -310,11 +331,10 @@ export class DiscoveryFeedSession {
         if (!this.radar)
             return null;
         if (page === 0)
-            this.clusters = await this.loadRadar();
+            this.clusters = await (this.radarLoading ?? this.loadRadar());
         if (!this.clusters?.length || (page !== 0 && page % 2 !== 0))
             return null;
-        const unused = this.clusters.filter(candidate => !this.radarUsed.has(candidate.id));
-        const cluster = page === 0 ? unused.find(candidate => candidate.kind === 'breaking') ?? unused[0] : unused.find(candidate => candidate.kind !== 'breaking');
+        const cluster = this.pickCluster(this.clusters, page);
         if (!cluster)
             return null;
         this.radarUsed.add(cluster.id);
@@ -323,6 +343,45 @@ export class DiscoveryFeedSession {
             return null;
         return cluster;
     }
+    /** Page 0: the top breaking cluster, else the top cluster. Later pages: the next unused story or viral cluster. */
+    pickCluster(clusters, page) {
+        const unused = clusters.filter(candidate => !this.radarUsed.has(candidate.id));
+        return page === 0 ? unused.find(candidate => candidate.kind === 'breaking') ?? unused[0] : unused.find(candidate => candidate.kind !== 'breaking');
+    }
+    /** The story's members as feed items, read once per story and bounded to three seconds; a failed read is simply none. */
+    memberPosts(cluster) {
+        let pending = this.memberReads.get(cluster.id);
+        if (!pending) {
+            pending = this.readMembers(cluster);
+            this.memberReads.set(cluster.id, pending);
+        }
+        return pending;
+    }
+    async readMembers(cluster) {
+        const wanted = new Set(cluster.memberKeys);
+        const mindsIds = cluster.memberKeys.flatMap(memberKey => { try {
+            const [kind, id] = JSON.parse(memberKey);
+            return kind === 'minds' ? [id] : [];
+        }
+        catch {
+            return [];
+        } })
+            .slice(0, RADAR_MAX_MINDS_READS);
+        const social = this.members?.social && mindsIds.length < cluster.memberKeys.length
+            ? withDeadline(this.members.social({ cluster: cluster.id }).then(({ data }) => {
+                if (!data || data.cluster !== cluster.id || !Array.isArray(data.items))
+                    return [];
+                return data.items.filter(post => post && typeof post.nativeId === 'string' && post.author?.protocol === post.protocol && wanted.has(key(post.protocol, post.nativeId)))
+                    .map(post => ({ key: key(post.protocol, post.nativeId), kind: 'social', post }));
+            }), [])
+            : Promise.resolve([]);
+        const minds = this.members?.minds
+            ? Promise.all(mindsIds.map(id => withDeadline(this.members.minds(id).then(({ data }) => data && data.id === id ? [{ key: key('minds', id), kind: 'minds', post: data }] : []), []))).then(rows => rows.flat())
+            : Promise.resolve([]);
+        const items = [...await social, ...await minds];
+        const unique = new Map(items.map(item => [item.key, item]));
+        return [...unique.values()];
+    }
     async loadRadar() {
         let response;
         let cancel = () => { };
@@ -409,6 +468,12 @@ export class DiscoveryResource {
     }
     createFeed(options) {
         // 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));
+        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) });
     }
 }
+/** A read bounded to three seconds; a late or failed one resolves to `fallback`, never an error. */
+function withDeadline(read, fallback, ms = 3000) {
+    let timer;
+    return Promise.race([read.catch(() => fallback), new Promise(resolve => { timer = setTimeout(() => resolve(fallback), ms); })])
+        .finally(() => clearTimeout(timer));
+}

package/dist/resources/e2ee.d.ts

@@ -30,14 +30,23 @@ export interface E2eeEvent {
     welcome: string | null;
     createdAt: string;
 }
+/** One-time key packages a device still has to hand out. */
+export interface E2eeKeyPackageStatus {
+    /** Unclaimed packages that have not expired. Once this reaches 0 nobody can add the device to a new conversation. */
+    available: number;
+    /** Of `available`, how many expire within 7 days. */
+    expiringSoon: number;
+}
 /**
  * E2EE v2 ciphertext transport. The server relays envelopes and public
  * credentials only; encryption happens in the shared core on each device.
- * Requires the `e2eeV2` network feature flag.
+ * Requires the `e2eeV2` network feature flag and a key acting as the account
+ * owner (agent-scoped keys are refused). The realm is the network id.
  */
 export declare class E2eeResource {
     private client;
     constructor(client: HttpClient);
+    /** Register this device's public identity and its signed approval chain. */
     registerDevice(input: {
         device_name: string;
         realm: string;
@@ -50,12 +59,22 @@ export declare class E2eeResource {
         data: E2eeDevice[];
     }>;
     revokeDevice(deviceId: string): Promise<SingleResponse<E2eeDevice>>;
+    /** Publish one-time key packages for one of your devices; `available` is how many it now has. */
     publishKeyPackages(input: {
         device_id: string;
         packages: string[];
     }): Promise<SingleResponse<{
         published: number;
+        available: number;
     }>>;
+    /**
+     * How many one-time key packages one of your active devices still has to
+     * hand out. Publish more when `available` runs low or most of it is
+     * `expiringSoon`: at 0, nobody can add the device to a new conversation.
+     */
+    keyPackageStatus(params: {
+        device_id: string;
+    }): Promise<SingleResponse<E2eeKeyPackageStatus>>;
     claimKeyPackage(input: {
         device_id: string;
         target_device_id: string;

package/dist/resources/e2ee.js

@@ -1,13 +1,15 @@
 /**
  * E2EE v2 ciphertext transport. The server relays envelopes and public
  * credentials only; encryption happens in the shared core on each device.
- * Requires the `e2eeV2` network feature flag.
+ * Requires the `e2eeV2` network feature flag and a key acting as the account
+ * owner (agent-scoped keys are refused). The realm is the network id.
  */
 export class E2eeResource {
     client;
     constructor(client) {
         this.client = client;
     }
+    /** Register this device's public identity and its signed approval chain. */
     registerDevice(input) {
         return this.client.post('/e2ee/devices', input);
     }
@@ -17,9 +19,18 @@ export class E2eeResource {
     revokeDevice(deviceId) {
         return this.client.post(`/e2ee/devices/${encodeURIComponent(deviceId)}/revoke`);
     }
+    /** 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);
     }
+    /**
+     * How many one-time key packages one of your active devices still has to
+     * hand out. Publish more when `available` runs low or most of it is
+     * `expiringSoon`: at 0, nobody can add the device to a new conversation.
+     */
+    keyPackageStatus(params) {
+        return this.client.get('/e2ee/key-packages/status', params);
+    }
     claimKeyPackage(input) {
         return this.client.post('/e2ee/key-packages/claim', input);
     }

package/dist/resources/protocols.d.ts

@@ -211,6 +211,8 @@ export interface HostedProtocolConnections {
     servers: {
         protocol: 'atproto' | 'activitypub' | 'nostr';
         url: string;
+        /** Handle suffixes the PDS issues (`minds.com` -> `alice.minds.com`); absent means the PDS hostname. */
+        handleDomains?: string[];
     }[];
 }
 export type HostedProtocol = 'atproto' | 'activitypub' | 'nostr';
@@ -300,6 +302,18 @@ export interface SocialSourceControl {
 export type SocialSourceControlChange = Omit<SocialSourceControl, 'id' | 'createdAt'> & {
     enabled: boolean;
 };
+/** One image already uploaded to Minds storage. Only Minds-hosted HTTPS URLs are accepted; JPEG, PNG, WebP or GIF; at most four per post. */
+export interface NativeMediaInput {
+    url: string;
+    /** The member's alt text. When omitted an empty description is sent, never an invented one. */
+    alt?: string;
+    width?: number;
+    height?: number;
+    mimeType?: 'image/jpeg' | 'image/png' | 'image/webp' | 'image/gif';
+}
+export interface NativeMediaItem extends NativeMediaInput {
+    alt: string;
+}
 export interface NativeReplyPrepareInput {
     clientMutationId: string;
     text: string;
@@ -309,6 +323,8 @@ export interface NativeReplyPrepareInput {
         readRef?: string;
     };
     accountIds: string[];
+    /** Minds-hosted images attached to every selected destination. Omit for a text-only reply. */
+    media?: NativeMediaInput[];
     /** Selected different-network accounts to review as standalone posts with a source link. */
     linkedPostAccountIds?: string[];
     /** Fresh review of selected unsent or definitively rejected deliveries. The original selected reviews are atomically fenced; preserve this mutation ID on retry. */
@@ -518,6 +534,11 @@ export interface NativeReplyReceipt {
     providerId: string | null;
     acknowledged: boolean;
     readBack: 'matched' | 'absent' | 'unavailable';
+    /** Present when the delivery carried images: how many, and how many had no alt text. */
+    media?: {
+        count: number;
+        alt_missing: number;
+    };
 }
 export interface NativeReplyRemovalReceipt {
     /** Absence is observed on the owning server; this is not global erasure. */
@@ -581,6 +602,8 @@ export interface NativeReplyBatch {
         text: string;
         wireText: string;
         receipt: NativeReplyReceipt | null;
+        /** The reviewed images exactly as they will be sent. */
+        media?: NativeMediaItem[];
         removal: {
             id: string;
             expiresAt: string;
@@ -589,11 +612,13 @@ export interface NativeReplyBatch {
         } | null;
     }>;
 }
-/** Public text only; accounts are selected explicitly in the shared editor. */
+/** Public text and Minds-hosted images; accounts are selected explicitly in the shared editor. */
 export interface NativePostPrepareInput {
     clientMutationId: string;
     text: string;
     accountIds: string[];
+    /** Minds-hosted images attached to every selected destination. Omit for a text-only post. */
+    media?: NativeMediaInput[];
     /** Native quote on Bluesky only. The server reads the source and permissions using each selected account. */
     quote?: {
         protocol: 'bluesky';
@@ -1026,6 +1051,16 @@ export interface SocialRadarParams {
     category?: string;
     limit?: number;
 }
+/** One radar story's social member posts, in the cluster's member order. Empty once the story leaves the snapshot. */
+export interface SocialRadarPosts {
+    cluster: string;
+    builtAt: string | null;
+    items: SocialPost[];
+}
+/** Read options for callers that hold their own deadline, such as a discovery page. */
+export interface SocialReadOptions {
+    retry?: boolean;
+}
 /** Provider-ranked accounts. `source` says whether this page is the app's hourly index snapshot or a live read. */
 export interface SocialPopularProfiles {
     items: SocialProfile[];
@@ -1147,7 +1182,7 @@ export declare class ProtocolsResource {
         includePreviews?: boolean;
         category?: string;
         discovery?: boolean;
-    }): Promise<SingleResponse<SocialTrends>>;
+    }, options?: SocialReadOptions): Promise<SingleResponse<SocialTrends>>;
     /** Open a topic currently listed by the provider. Use its nativeId as topic and preserve the opaque cursor. */
     getPublicTrendFeed(params: {
         protocol: string;
@@ -1156,9 +1191,13 @@ export declare class ProtocolsResource {
         cursor?: string;
         category?: string;
         discovery?: boolean;
-    }): Promise<SingleResponse<SocialTrendFeed>>;
+    }, options?: SocialReadOptions): Promise<SingleResponse<SocialTrendFeed>>;
     /** The app's topic radar under its own key: the same snapshot the keyless route serves. Never triggers a build. */
-    getPublicRadar(params?: SocialRadarParams): Promise<SingleResponse<SocialRadar>>;
+    getPublicRadar(params?: SocialRadarParams, options?: SocialReadOptions): Promise<SingleResponse<SocialRadar>>;
+    /** One radar story's social member posts, so its card can show the posts it counts. Minds members are read with `posts.get`. */
+    getPublicRadarPosts(params: {
+        cluster: string;
+    }, options?: SocialReadOptions): Promise<SingleResponse<SocialRadarPosts>>;
     /** Provider-ranked public accounts with explicit provenance; served from the app's index when a fresh snapshot exists. */
     getPublicPopularProfiles(params: {
         protocol: string;
@@ -1198,7 +1237,7 @@ export declare class ProtocolsResource {
     }): Promise<SingleResponse<NativeRepostReview>>;
     /** Reconcile the saved action without sending another native write. */
     nativeRepostStatus(id: string): Promise<SingleResponse<NativeRepostReview>>;
-    /** Prepare exact public text for selected connected Bluesky/ActivityPub accounts. */
+    /** Prepare exact public text and reviewed images for selected connected Bluesky/ActivityPub accounts. */
     prepareNativePost(input: NativePostPrepareInput): Promise<SingleResponse<NativePostBatch>>;
     /** Explicitly approve selected deliveries; never auto-retry an uncertain write. */
     submitNativePost(id: string, input: {

package/dist/resources/protocols.js

@@ -35,9 +35,15 @@ function hostedIdentityPath(id) {
     return `/protocols/identities/${encodeURIComponent(id)}`;
 }
 /** Only the two radar 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 } : {}) };
 }
+/** Forward only the media contract fields; nothing else from the app's own media rows. */
+const nativeMediaInput = (media) => media.map(item => ({ url: item.url,
+    ...(item.alt !== undefined ? { alt: item.alt } : {}), ...(item.width !== undefined ? { width: item.width } : {}),
+    ...(item.height !== undefined ? { height: item.height } : {}), ...(item.mimeType !== undefined ? { mimeType: item.mimeType } : {}) }));
 export class ProtocolsResource {
     client;
     subscriptionListeners = new Set();
@@ -126,21 +132,25 @@ export class ProtocolsResource {
         return this.client.get('/protocols/social/conversation', { protocol: params.protocol, post: params.post, readRef: params.readRef });
     }
     /** Current provider-ranked topics or posts, with explicit source and coverage. Does not ingest content. */
-    getPublicTrends(params) {
+    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 } : {}) });
+            ...(params.discovery !== undefined ? { discovery: params.discovery } : {}) }, ...readOptions(options));
     }
     /** Open a topic currently listed by the provider. Use its nativeId as topic and preserve the opaque cursor. */
-    getPublicTrendFeed(params) {
+    getPublicTrendFeed(params, options) {
         return this.client.get('/protocols/social/trend-feed', { protocol: params.protocol, topic: params.topic, limit: params.limit, cursor: params.cursor,
             ...(params.category !== undefined ? { category: params.category } : {}),
-            ...(params.discovery !== undefined ? { discovery: params.discovery } : {}) });
+            ...(params.discovery !== undefined ? { discovery: params.discovery } : {}) }, ...readOptions(options));
     }
     /** The app's topic radar under its own key: the same snapshot the keyless route serves. Never triggers a build. */
-    getPublicRadar(params = {}) {
-        return this.client.get('/protocols/social/radar', radarQuery(params));
+    getPublicRadar(params = {}, options) {
+        return this.client.get('/protocols/social/radar', radarQuery(params), ...readOptions(options));
+    }
+    /** One radar story's social member posts, so its card can show the posts it counts. Minds members are read with `posts.get`. */
+    getPublicRadarPosts(params, options) {
+        return this.client.get('/protocols/social/radar/posts', { cluster: params.cluster }, ...readOptions(options));
     }
     /** Provider-ranked public accounts with explicit provenance; served from the app's index when a fresh snapshot exists. */
     getPublicPopularProfiles(params) {
@@ -212,11 +222,12 @@ export class ProtocolsResource {
         hostedIdentityPath(id);
         return this.client.get(`/protocols/social/reposts/${encodeURIComponent(id)}`);
     }
-    /** Prepare exact public text for selected connected Bluesky/ActivityPub accounts. */
+    /** Prepare exact public text and reviewed images for selected connected Bluesky/ActivityPub accounts. */
     prepareNativePost(input) {
         return this.client.post('/protocols/social/posts/prepare', { clientMutationId: input.clientMutationId,
             text: input.text, accountIds: input.accountIds,
-            ...(input.quote ? { quote: { protocol: input.quote.protocol, nativeId: input.quote.nativeId } } : {}) }, { retry: false });
+            ...(input.quote ? { quote: { protocol: input.quote.protocol, nativeId: input.quote.nativeId } } : {}),
+            ...(input.media !== undefined ? { media: nativeMediaInput(input.media) } : {}) }, { retry: false });
     }
     /** Explicitly approve selected deliveries; never auto-retry an uncertain write. */
     submitNativePost(id, input) {
@@ -248,7 +259,8 @@ export class ProtocolsResource {
             parent: { protocol: input.parent.protocol, nativeId: input.parent.nativeId,
                 ...(input.parent.readRef !== undefined ? { readRef: input.parent.readRef } : {}) }, accountIds: input.accountIds,
             ...(input.linkedPostAccountIds !== undefined ? { linkedPostAccountIds: input.linkedPostAccountIds } : {}),
-            ...(input.recoverFrom !== undefined ? { recoverFrom: { batchId: input.recoverFrom.batchId, deliveryIds: input.recoverFrom.deliveryIds } } : {}) }, { retry: false });
+            ...(input.recoverFrom !== undefined ? { recoverFrom: { batchId: input.recoverFrom.batchId, deliveryIds: input.recoverFrom.deliveryIds } } : {}),
+            ...(input.media !== undefined ? { media: nativeMediaInput(input.media) } : {}) }, { retry: false });
     }
     /** Send only explicitly approved delivery IDs from this preview. Repeated submissions reconcile; they do not replay a write. */
     submitNativeReply(id, input) {

package/llm.md

@@ -478,11 +478,12 @@ Methods: `conversations`, `communityConversation`, `conversation`, `messages`, `
 
 ### r.e2ee — End-to-end encryption transport (flag-gated)
 
-Relays opaque MLS envelopes, public device credentials and one-time key packages for the shared E2EE core; the server never sees keys or plaintext. Requires the `e2eeV2` network feature flag; otherwise every call returns `feature_disabled`.
+Relays opaque MLS envelopes, public device credentials and one-time key packages for the shared E2EE core; the server never sees keys or plaintext. Requires the `e2eeV2` network feature flag (otherwise `feature_disabled`) and a key acting as the account owner (agent-scoped keys get `agent_key_not_allowed`). The realm is the network id. Only a direct conversation between two people with an accepted request can start encryption (`conversation_not_eligible` otherwise); blocks apply (`blocked`); commits must send `expected_commit_seq`.
 
 ```ts
-const { data: device } = await r.e2ee.registerDevice({ device_name: 'phone-1', realm: 'minds', signing_key, credential });
-await r.e2ee.publishKeyPackages({ device_id: device.id, packages: [keyPackageBase64] });
+const { data: device } = await r.e2ee.registerDevice({ device_name: 'phone-1', realm: networkId, signing_key, credential });
+await r.e2ee.publishKeyPackages({ device_id: device.id, packages: [keyPackageBase64] }); // → { published, available }
+const { data: stock } = await r.e2ee.keyPackageStatus({ device_id: device.id }); // { available, expiringSoon }; refill when low
 const { data: claimed } = await r.e2ee.claimKeyPackage({ device_id: device.id, target_device_id: peerDeviceId });
 await r.e2ee.appendEvent(conversationId, { device_id: device.id, envelope }); // idempotent per event_id
 const { data: page } = await r.e2ee.events(conversationId, { device_id: device.id, after_seq: 0 });
@@ -634,7 +635,7 @@ if (subscription.active) {
 - `r.organizationSettings` / `r.organizationSecurity` — Org configuration
 - Native follows: `nativeFollowState({ accountId, protocol, nativeId })`, `prepareNativeFollow({ clientMutationId, accountId, protocol, nativeId, action: "follow" | "unfollow" })`, `submitNativeFollow(id, { approve: true, event? })`, `nativeFollowStatus(id)`. Show the acting identity and native following/requested/unfollowed state separately from the Minds feed subscription. Nostr must sign the complete review event without dropping other contacts; stale lists require a fresh review. Keep mutation IDs and reconcile ambiguous outcomes without replay. Requires current follow scopes and API `NATIVE_SOCIAL_FOLLOW_PROJECTS` plus source controls.
 - Native reposts: `nativeRepostState({ accountId, protocol, nativeId })`, `prepareNativeRepost({ clientMutationId, accountId, protocol, nativeId, action: "repost" | "unrepost" })`, `submitNativeRepost(id, { approve: true, event? })`, `nativeRepostStatus(id)`. Requires `NATIVE_SOCIAL_REPOST_PROJECTS`, account capability and explicit approval; Nostr signs the exact review (kind 6 or own kind 5). Unknown attempts only reconcile. Bluesky connections need the new repost scope; ActivityPub uses write:statuses. Native likes: `nativeLikeState({ accountId, protocol, nativeId })`, `prepareNativeLike({ clientMutationId, accountId, protocol, nativeId, action: "like" | "unlike" })`, `submitNativeLike(id, { approve: true, event? })`, and `nativeLikeStatus(id)`. Display the selected account, source and action before approval. Only Nostr supplies `event`: sign the exact public `signing.event` in the review; never transmit a private key. Preserve mutation IDs on ambiguous responses and refresh unknown results instead of resending. Read capabilities before offering actions; old reply-only connections need reconnecting for likes. Nostr results describe the connected relay, not every public relay. The app-specific `NATIVE_SOCIAL_LIKE_PROJECTS` switch and source controls must be enabled on the API.
-- Delegated social accounts: `r.protocols.nativeSocialAccounts()`, `startNativeSocialConnection({ protocol, identifier })`, `finishNativeSocialConnection({ protocol, state, code?, iss?, error? })`, `disconnectNativeSocialAccount(id)`. Example: `const { data } = await r.protocols.startNativeSocialConnection({ protocol: "bluesky", identifier: "alice.bsky.social" })`; open `data.authorizationUrl`, then complete with the same signed-in app user. Never log callback codes, send passwords, or auto-retry OAuth callbacks. Shared replies (off until schema/API deployment and live verification): `prepareNativeReply({ clientMutationId, text, parent: { protocol, nativeId, readRef? }, accountIds, linkedPostAccountIds?, recoverFrom?: { batchId, deliveryIds } })`, `submitNativeReply(id, { approve: true, deliveryIds })`, `nativeReplyStatus(id)`, `nativeReplyHistory({ limit?, cursor? })`, `prepareNativeReplyRemoval(id, { deliveryIds })`, `removeNativeReply(id, { approve: true, removals })`. Review account, destination, `kind`, source and exact `wireText`; connection is not publication approval. `linkedPostAccountIds` explicitly selects different-network standalone posts with a source link, never matching threaded replies or a same-network denial fallback. Preserve mutation IDs, show per-destination results and reconcile uncertain attempts without reposting. To review selected unsent or definitively rejected deliveries again, use recoverFrom with a new mutation ID, the same source/accounts and freshly reviewed text; preserve that ID on uncertain preparation. Only saved recoverable destinations qualify, current gates still apply, and replacedBy disables old sends atomically. Never restart unknown, accepted or published deliveries. The new preview still needs explicit approval. Saved delegated drafts/results: `const { data: history } = await r.protocols.nativeReplyHistory({ limit: 20 })`; use its opaque cursor for the next page and `nativeReplyStatus(item.id)` for details. This is a private read, not a write or provider refresh, and includes Nostr results marked type=nostr. Use nativeNostrReplyResult(item.id) to check that recorded event on its relay without signing or resending. Discard page state on owner/app changes. See README for examples and the callback, revocation and removal contracts.
+- Delegated social accounts: `r.protocols.nativeSocialAccounts()`, `startNativeSocialConnection({ protocol, identifier })`, `finishNativeSocialConnection({ protocol, state, code?, iss?, error? })`, `disconnectNativeSocialAccount(id)`. Example: `const { data } = await r.protocols.startNativeSocialConnection({ protocol: "bluesky", identifier: "alice.bsky.social" })`; open `data.authorizationUrl`, then complete with the same signed-in app user. Never log callback codes, send passwords, or auto-retry OAuth callbacks. Shared replies (off until schema/API deployment and live verification): `prepareNativeReply({ clientMutationId, text, parent: { protocol, nativeId, readRef? }, accountIds, media?, linkedPostAccountIds?, recoverFrom?: { batchId, deliveryIds } })`, `submitNativeReply(id, { approve: true, deliveryIds })`, `nativeReplyStatus(id)`, `nativeReplyHistory({ limit?, cursor? })`, `prepareNativeReplyRemoval(id, { deliveryIds })`, `removeNativeReply(id, { approve: true, removals })`. Review account, destination, `kind`, source, exact `wireText` and every reviewed `media` item with its alt text; connection is not publication approval. `media` takes the same `NativeMediaInput[]` as `prepareNativePost` and needs the account's `publish_media` capability. `linkedPostAccountIds` explicitly selects different-network standalone posts with a source link, never matching threaded replies or a same-network denial fallback. Preserve mutation IDs, show per-destination results and reconcile uncertain attempts without reposting. To review selected unsent or definitively rejected deliveries again, use recoverFrom with a new mutation ID, the same source/accounts and freshly reviewed text; preserve that ID on uncertain preparation. Only saved recoverable destinations qualify, current gates still apply, and replacedBy disables old sends atomically. Never restart unknown, accepted or published deliveries. The new preview still needs explicit approval. Saved delegated drafts/results: `const { data: history } = await r.protocols.nativeReplyHistory({ limit: 20 })`; use its opaque cursor for the next page and `nativeReplyStatus(item.id)` for details. This is a private read, not a write or provider refresh, and includes Nostr results marked type=nostr. Use nativeNostrReplyResult(item.id) to check that recorded event on its relay without signing or resending. Discard page state on owner/app changes. See README for examples and the callback, revocation and removal contracts.
 - `r.protocols` — Private app safety: `sourceControls` returns current `enabled` plus paged saved choices; `setSourceControl`, `onSourceControlChange` and `reportSource` share app scope. Example: `const choices = new Map(); const stop = r.protocols.onSourceControlChange(change => choices.set(JSON.stringify([change.source, change.control]), change.enabled));` then `await r.protocols.setSourceControl({ source: { protocol: "bluesky", kind: "actor", nativeId: "did:plc:aaaaaaaaaaaaaaaaaaaaaaaa" }, control: "mute", enabled: true, scope: "minds" });` and call `stop(); choices.clear()` on account change/unmount. Notifications follow an exact server confirmation, never an uncertain response. These preferences and reports apply in Minds, not on the remote network. Keyless post links: `const visitor = new Recursiv({ anonymous: true }); const { data: thread } = await visitor.protocols.getSharedConversation(projectId, { protocol: 'nostr', post: publicEventId })`; `sharedNetworks(projectId)` lists public conversation capabilities. Only configured apps; app moderation and rate limits apply, no member state or write authority. Member public reading: `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. Example after selecting a returned source post: `const { data: thread } = await r.protocols.getPublicConversation({ protocol: post.protocol, post: post.nativeId, readRef: post.readRef })`. Render `focus`, oldest-first `ancestors` and direct `replies`; `public_provider_window` never promises every reply, and `limited` marks known omissions. Requires both `users:read` and `posts:read` on the current human app key. Protocol discovery/settings: `const { data: adapters } = await r.protocols.list()` returns bounded `{ id, name, icon, color, maturity, capabilities, limitations }` metadata; `supported` means implemented, not configured, healthy, authorized, or enabled. Methods: `list`, `status`, `listCandidates`, `getCandidate`, `search`, `getSettings`, `refresh`, `updateSettings`.
   - Native Nostr: `const { data: preview } = await r.protocols.prepareNativeNostr(identityId, { action: "publish", content: draft })`; review and sign the exact public event, then `submitNativeNostr(identityId, { intent: preview.intent, event, approve: true })`. Preparation/submission never auto-retry. After uncertainty, use `getNativeNostrPost(identityId, preview.postId ?? preview.eventId)` before a user-selected retry of the identical intent/event: deletion checks the original note's `postId`, publication checks `eventId`. Check `nativeNostrAccount()` enablement first; keys stay with the signer. For replies, after `nativeNostrAccount()` advertises `reply_text_note`, use `prepareNativeNostr(identityId, { action: "reply", content: draft, parentId: post.nativeId })`. Review returned parent/root/participants/relay and exact event, sign with the connected client signer, then `submitNativeNostr(identityId, { intent, event, approve: true })`. Requires users:read, posts:read and posts:write. Kind1 public notes only; reply enablement and shared UI/live proof remain pending. Do not inherit arbitrary notification tags or relay hints. Signing mutations never auto-retry; check `getNativeNostrPost(identityId, eventId)` after uncertainty before a user-selected identical-event retry.
   - Anonymous discovery: `const visitor = new Recursiv({ anonymous: true }); const { data } = await visitor.protocols.getSharedTrends(projectId, { protocol: 'nostr', limit: 20, discovery: true })`. Use `sharedNetworks(projectId)` capabilities; open a returned topic with `getSharedTrendFeed(projectId, { protocol: 'bluesky', topic: trend.nativeId, cursor })`. Configured apps only; no account authority or writes. App moderation and per-IP/app rate limits apply. Categories and Jev layouts reuse cached judgments without initiating paid inference; handle partial categories and finite provider windows.
@@ -822,7 +823,7 @@ publication; history stores no signature, signing key or intent. Keep the acting
 user/app-bound result IDs and discard UI state after an account switch. The last
 read-back observation is separate from retained publication/deletion evidence.
 
-Standalone public text posts: `prepareNativePost({ clientMutationId, text, accountIds })` → review → `submitNativePost(id, { approve: true, deliveryIds })`. Use `nativePostStatus(id)` / `nativePostHistory({limit,cursor})` for private durable outcomes and `prepareNativePostRemoval(id,{deliveryIds})` → `removeNativePost(id,{approve:true,removals:[{deliveryId,removalId}]})` for reviewed own-post removal. Check `publish_text` capability; no media, reply parent or audience override. Preserve mutation IDs, never create a new send to recover uncertainty.
+Standalone public text posts: `prepareNativePost({ clientMutationId, text, accountIds })` → review → `submitNativePost(id, { approve: true, deliveryIds })`. Use `nativePostStatus(id)` / `nativePostHistory({limit,cursor})` for private durable outcomes and `prepareNativePostRemoval(id,{deliveryIds})` → `removeNativePost(id,{approve:true,removals:[{deliveryId,removalId}]})` for reviewed own-post removal. Check `publish_text`; no reply parent or audience override. Attach already-uploaded Minds images with `media: [{ url, alt?, width?, height?, mimeType? }]` (at most four JPEG/PNG/WebP/GIF, Minds-hosted HTTPS URLs only, a Mastodon GIF must be the only attachment) on accounts that also advertise `publish_media` — grants made before image scopes existed keep working for text and must be reconnected first. Always pass the member's own `alt`; an omitted one is sent empty, never invented. The receipt reports `media: { count, alt_missing }`. Preserve mutation IDs, never create a new send to recover uncertainty.
 Bluesky quote: accounts must advertise `quote`; call `prepareNativePost({clientMutationId,text,accountIds,quote:{protocol:'bluesky',nativeId:sourceAtUri}})`, review each returned quote/account/comment, then approve via the same submit method. The server binds the source CID and rechecks permissions before sending. No cross-network quote conversion. Public reads expose one filtered `post.quote` (`available` with `post`, or `unavailable` without source details). Available quotes may include `embeddedReferences`: exact standalone source-reference lines in the unchanged outer `text`. Omit them only when the quoted original is actually visible; retain them for unavailable or locally hidden quotes. Nostr references are decoded and matched by the server, without following relay hints.
 
 Public post search (API/SDK 0.7.35): `const { data: page } = await r.protocols.searchPublicPosts({ protocol: 'nostr', query: 'open social', limit: 10 })`. Bluesky/ActivityPub require a selected `accountId` from `nativeSocialAccounts()` with `post_search`; older Bluesky grants must reconnect with consent. Open their results with `getConnectedSocialConversation({ protocol, accountId: page.readerAccountId, post: item.nativeId, readRef: item.readRef })` and pass the same accountId to `reportSource` for post reports. Nostr uses `getPublicConversation`. Pages report provider/observedAt and bounded coverage; no invented exhaustive or global search. Keep cursors paired with the exact owner, query, account, limit and connection revision. No writes, credentials or new ingestion are part of search.

package/package.json

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