@recursiv/sdk 0.7.31 → 0.7.32

package/README.md

@@ -111,7 +111,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | `r.admin` | User management, stats, content reports (`listReports`, `resolveReport`, `dismissReport`) |
 | `r.dispatcher` | Task queue, claims, signals, outcomes, webhooks |
 | `r.goals` | Org goals with task rollups (group dispatcher tasks) |
-| `r.protocols` | Private Minds safety: `sourceControls` (current enablement and saved choices), `setSourceControl`, `onSourceControlChange`, `reportSource`. Delegated accounts: `nativeSocialAccounts`, `startNativeSocialConnection`, `finishNativeSocialConnection`, `disconnectNativeSocialAccount`. Native likes and unlikes: `nativeLikeState`, `prepareNativeLike`, `submitNativeLike`, `nativeLikeStatus` (connected authority, app enablement and explicit approval; resume pending actions instead of duplicating them). Reviewed replies and optional linked posts: `prepareNativeReply`, `submitNativeReply`, `nativeReplyStatus`, `nativeReplyHistory`, `prepareNativeReplyRemoval`, `removeNativeReply` (require deployed API support and app enablement). Keyless shared post links: `sharedNetworks(projectId)`, `getSharedConversation(projectId, { protocol, post, readRef? })`. Member public reading: `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. `list` returns bounded adapter `maturity`, `limitations`, and exhaustive `supported`/`planned`/`unsupported` implementation capabilities (not provider health or enablement); settings, candidate refresh/status, search, and read-only quarantined candidate review via `listCandidates` / `getCandidate` |
+| `r.protocols` | Private Minds safety: `sourceControls` (current enablement and saved choices), `setSourceControl`, `onSourceControlChange`, `reportSource`. Delegated accounts: `nativeSocialAccounts`, `startNativeSocialConnection`, `finishNativeSocialConnection`, `disconnectNativeSocialAccount`. Native follows: `nativeFollowState`, `prepareNativeFollow`, `submitNativeFollow`, `nativeFollowStatus` (native following or pending approval, distinct from a Minds feed subscription; preserve the complete signed Nostr list). Native likes and unlikes: `nativeLikeState`, `prepareNativeLike`, `submitNativeLike`, `nativeLikeStatus` (connected authority, app enablement and explicit approval; resume pending actions instead of duplicating them). Reviewed replies and optional linked posts: `prepareNativeReply`, `submitNativeReply`, `nativeReplyStatus`, `nativeReplyHistory`, `prepareNativeReplyRemoval`, `removeNativeReply` (require deployed API support and app enablement). Keyless shared post links: `sharedNetworks(projectId)`, `getSharedConversation(projectId, { protocol, post, readRef? })`. Member public reading: `publicNetworks`, `searchPublicProfiles`, `getPublicProfile`, `getPublicAuthorFeed`, `getFollowingFeed`, `getPublicConversation`, `getPublicTrends`, `getPublicTrendFeed`; private app subscriptions: `listSubscriptions`, `subscribeToProfile`, `unsubscribeFromProfile`, `onSubscriptionChange`. `list` returns bounded adapter `maturity`, `limitations`, and exhaustive `supported`/`planned`/`unsupported` implementation capabilities (not provider health or enablement); settings, candidate refresh/status, search, and read-only quarantined candidate review via `listCandidates` / `getCandidate` |
 
 Full reference: see [llm.md](./llm.md) (ships with this package) or the type definitions in `dist/`.
 

package/dist/index.d.ts

@@ -194,7 +194,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, HostedProtocolConnections, HostedProtocol, HostedProtocolIdentity, HostedNostrChallenge, HostedNostrIdentityProof, NativeNostrPrepareInput, NativeNostrPrepared, NativeNostrAccount, NativeNostrPostState, NativeNostrReceipt, NativeSocialProtocol, FederationIdentity, FederationIdentityView, NativeSocialAccount, NativeSocialCallbackInput, NativeReplyPrepareInput, NativeLikeSourceInput, NativeLikePrepareInput, NativeLikeTarget, NativeLikeReceipt, NativeLikeState, NativeLikeReview, 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, HostedProtocolConnections, HostedProtocol, HostedProtocolIdentity, HostedNostrChallenge, HostedNostrIdentityProof, NativeNostrPrepareInput, NativeNostrPrepared, NativeNostrAccount, NativeNostrPostState, NativeNostrReceipt, NativeSocialProtocol, FederationIdentity, FederationIdentityView, NativeSocialAccount, NativeSocialCallbackInput, NativeReplyPrepareInput, NativeFollowSourceInput, NativeFollowPrepareInput, NativeFollowTarget, NativeFollowReceipt, NativeFollowState, NativeFollowReview, NativeLikeSourceInput, NativeLikePrepareInput, NativeLikeTarget, NativeLikeReceipt, NativeLikeState, NativeLikeReview, 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/protocols.d.ts

@@ -317,6 +317,67 @@ export interface NativeReplyPrepareInput {
         deliveryIds: string[];
     };
 }
+export interface NativeFollowSourceInput {
+    accountId: string;
+    protocol: SocialSourceRef['protocol'];
+    nativeId: string;
+}
+export interface NativeFollowPrepareInput extends NativeFollowSourceInput {
+    clientMutationId: string;
+    action: 'follow' | 'unfollow';
+}
+export type NativeFollowTarget = {
+    nativeId: string;
+    sourceUrl: string;
+    handle: string;
+    revision: string;
+    followAllowed: boolean;
+} & ({
+    protocol: 'bluesky';
+} | {
+    protocol: 'activitypub';
+    localId: string;
+} | {
+    protocol: 'nostr';
+});
+export interface NativeFollowReceipt {
+    state: 'following' | 'requested' | 'unfollowed' | 'unknown' | 'rejected';
+    acknowledged: boolean;
+    reference: {
+        nativeId: string;
+        revision: string;
+    } | null;
+}
+export interface NativeFollowState extends NativeFollowReceipt {
+    accountId: string;
+    account: {
+        nativeId: string;
+        handle: string;
+        serverUrl: string;
+    };
+    target: NativeFollowTarget;
+    /** Resume this account's unresolved review after a browser refresh. Never start a duplicate action. */
+    pendingActionId: string | null;
+    /** An earlier connection or another target profile has an unresolved attempt. Read again to reconcile; do not prepare a new write. */
+    pendingActionBlocked: boolean;
+}
+export interface NativeFollowReview {
+    id: string;
+    clientMutationId: string;
+    expiresAt: string;
+    accountId: string;
+    account: NativeFollowState['account'];
+    target: NativeFollowTarget;
+    action: 'follow' | 'unfollow';
+    attemptedAt: string | null;
+    receipt: NativeFollowReceipt | null;
+    checkedAt: string | null;
+    /** Sign this exact event with the displayed account. Never send a private key. */
+    signing?: {
+        event: Omit<HostedNostrIdentityProof, 'sig'>;
+        relay: string;
+    };
+}
 export interface NativeLikeSourceInput {
     accountId: string;
     protocol: SocialSourceRef['protocol'];
@@ -549,7 +610,7 @@ export interface NativeNostrPrepared {
 export interface NativeNostrAccount {
     enabled: boolean;
     identity: HostedProtocolIdentity | null;
-    capabilities: Array<'publish_original_text' | 'request_own_post_deletion' | 'reply_text_note' | 'publish_linked_text' | 'like' | 'unlike'>;
+    capabilities: Array<'publish_original_text' | 'request_own_post_deletion' | 'reply_text_note' | 'publish_linked_text' | 'like' | 'unlike' | 'follow' | 'unfollow'>;
     signing?: 'client';
 }
 export interface NativeNostrPostState {
@@ -818,6 +879,17 @@ export declare class ProtocolsResource {
         limit?: number;
         cursor?: string;
     }): Promise<SingleResponse<SocialPopularProfiles>>;
+    /** Read this connected account's current native following; never infer it from a public count. */
+    nativeFollowState(input: NativeFollowSourceInput): Promise<SingleResponse<NativeFollowState>>;
+    /** Prepare a follow/unfollow for explicit approval. Preserve the mutation ID after a lost response. */
+    prepareNativeFollow(input: NativeFollowPrepareInput): Promise<SingleResponse<NativeFollowReview>>;
+    /** Submit one approved action. Only Nostr supplies a public signed event. Automatic retries are disabled. */
+    submitNativeFollow(id: string, input: {
+        approve: true;
+        event?: HostedNostrIdentityProof;
+    }): Promise<SingleResponse<NativeFollowReview>>;
+    /** Reconcile the saved action without sending another native write. */
+    nativeFollowStatus(id: string): Promise<SingleResponse<NativeFollowReview>>;
     /** Read this connected account's current native like; never infer it from a public count. */
     nativeLikeState(input: NativeLikeSourceInput): Promise<SingleResponse<NativeLikeState>>;
     /** Prepare a like/unlike for explicit approval. Preserve the mutation ID after a lost response. */

package/dist/resources/protocols.js

@@ -110,6 +110,28 @@ export class ProtocolsResource {
     getPublicPopularProfiles(params) {
         return this.client.get('/protocols/social/popular-profiles', { protocol: params.protocol, limit: params.limit, cursor: params.cursor });
     }
+    /** Read this connected account's current native following; never infer it from a public count. */
+    nativeFollowState(input) {
+        return this.client.get('/protocols/social/follows/state', { accountId: input.accountId, protocol: input.protocol, nativeId: input.nativeId });
+    }
+    /** Prepare a follow/unfollow for explicit approval. Preserve the mutation ID after a lost response. */
+    prepareNativeFollow(input) {
+        return this.client.post('/protocols/social/follows/prepare', { clientMutationId: input.clientMutationId, accountId: input.accountId,
+            protocol: input.protocol, nativeId: input.nativeId, action: input.action }, { retry: false });
+    }
+    /** Submit one approved action. Only Nostr supplies a public signed event. Automatic retries are disabled. */
+    submitNativeFollow(id, input) {
+        hostedIdentityPath(id);
+        const event = input.event;
+        return this.client.post(`/protocols/social/follows/${encodeURIComponent(id)}/submit`, { approve: input.approve,
+            ...(event ? { event: { id: event.id, pubkey: event.pubkey, sig: event.sig, kind: event.kind,
+                    created_at: event.created_at, content: event.content, tags: event.tags } } : {}) }, { retry: false });
+    }
+    /** Reconcile the saved action without sending another native write. */
+    nativeFollowStatus(id) {
+        hostedIdentityPath(id);
+        return this.client.get(`/protocols/social/follows/${encodeURIComponent(id)}`);
+    }
     /** Read this connected account's current native like; never infer it from a public count. */
     nativeLikeState(input) {
         return this.client.get('/protocols/social/likes/state', { accountId: input.accountId, protocol: input.protocol, nativeId: input.nativeId });

package/llm.md

@@ -632,6 +632,7 @@ if (subscription.active) {
 - `r.admin` — Admin operations (user management, stats, network settings); content reports: `listReports({ status? })`, `resolveReport(id)`, `dismissReport(id)` (project-bound keys see only their app's reports)
 - `r.inviteCodes` / `r.inviteCodesAdmin` — Invite code management
 - `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 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.
 - `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`.

package/package.json

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