@recursiv/sdk 0.7.29 → 0.7.30

package/README.md

@@ -75,6 +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.brain` | `sendMessage` |
 | `r.commands` | `execute`, `gatePrompt` |
 | `r.projectBrain` | `tasks`, `decisions`, `milestones`, `completeTask`, `usage` |
@@ -110,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`. Reviewed replies and optional linked posts: `prepareNativeReply`, `submitNativeReply`, `nativeReplyStatus`, `nativeReplyHistory`, `prepareNativeReplyRemoval`, `removeNativeReply` (require deployed API support and app enablement). 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`. 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/`.
 
@@ -570,3 +571,21 @@ Keep the cursor opaque and discard it when the app or signed-in user changes.
 History order is fixed by creation time, so later delivery updates do not move
 older entries across page boundaries. Reopen each result for its current saved
 state and obtain a fresh review before a new write.
+
+### Public protocol post links
+
+Visitors can read a public conversation in an explicitly configured app without signing in:
+
+```ts
+const visitor = new Recursiv({ anonymous: true });
+const { data: networks } = await visitor.protocols.sharedNetworks(projectId);
+const { data: conversation } = await visitor.protocols.getSharedConversation(projectId, {
+  protocol: 'nostr', post: publicEventId,
+});
+```
+
+These reads apply app moderation, provider public-visibility/deletion checks and bounded
+per-IP/app budgets. They return no subscriptions, personal safety preferences, account
+connections or signing authority. Missing configuration or unavailable safety checks fail
+closed. Signed-in members continue using `getPublicConversation` to apply personal
+blocks/mutes as well. All reply and account endpoints still require authentication.

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { PostsResource } from './resources/posts.js';
 import { UsersResource } from './resources/users.js';
 import { CommunitiesResource } from './resources/communities.js';
 import { ChatResource } from './resources/chat.js';
+import { E2eeResource } from './resources/e2ee.js';
 import { ProjectsResource } from './resources/projects.js';
 import { AgentsResource } from './resources/agents.js';
 import { EvidenceResource } from './resources/evidence.js';
@@ -64,6 +65,8 @@ export declare class Recursiv {
     readonly users: UsersResource;
     readonly communities: CommunitiesResource;
     readonly chat: ChatResource;
+    /** E2EE v2 ciphertext transport (flag-gated). */
+    readonly e2ee: E2eeResource;
     readonly projects: ProjectsResource;
     readonly agents: AgentsResource;
     readonly evidence: EvidenceResource;
@@ -136,6 +139,8 @@ export { PostsResource } from './resources/posts.js';
 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 { ProjectsResource } from './resources/projects.js';
 export { AgentsResource, SUPPORTED_MODELS } from './resources/agents.js';
 export { EvidenceResource } from './resources/evidence.js';

package/dist/index.js

@@ -4,6 +4,7 @@ import { PostsResource } from './resources/posts.js';
 import { UsersResource } from './resources/users.js';
 import { CommunitiesResource } from './resources/communities.js';
 import { ChatResource } from './resources/chat.js';
+import { E2eeResource } from './resources/e2ee.js';
 import { ProjectsResource } from './resources/projects.js';
 import { AgentsResource } from './resources/agents.js';
 import { EvidenceResource } from './resources/evidence.js';
@@ -65,6 +66,8 @@ export class Recursiv {
     users;
     communities;
     chat;
+    /** E2EE v2 ciphertext transport (flag-gated). */
+    e2ee;
     projects;
     agents;
     evidence;
@@ -125,6 +128,7 @@ export class Recursiv {
         this.users = new UsersResource(client);
         this.communities = new CommunitiesResource(client);
         this.chat = new ChatResource(client);
+        this.e2ee = new E2eeResource(client);
         this.projects = new ProjectsResource(client);
         this.agents = new AgentsResource(client);
         this.evidence = new EvidenceResource(client);
@@ -200,6 +204,7 @@ export { PostsResource } from './resources/posts.js';
 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 { ProjectsResource } from './resources/projects.js';
 export { AgentsResource, SUPPORTED_MODELS } from './resources/agents.js';
 export { EvidenceResource } from './resources/evidence.js';

package/dist/resources/e2ee.d.ts

@@ -0,0 +1,93 @@
+import type { HttpClient } from '../client.js';
+import type { SingleResponse } from '../types.js';
+/** Public device record from the E2EE v2 directory. Never contains private keys. */
+export interface E2eeDevice {
+    id: string;
+    userId: string;
+    deviceName: string;
+    realm: string;
+    signingKey: string;
+    credential: unknown;
+    isRoot: boolean;
+    status: 'active' | 'revoked' | string;
+    revokedAt: string | null;
+}
+/** Opaque `recursiv-mls-v2-draft1` envelope with base64 MLS bytes. */
+export interface E2eeEnvelope {
+    profile: 'recursiv-mls-v2-draft1';
+    realm: string;
+    conversation: string;
+    event_id: string;
+    sender_device: string;
+    kind: 'application' | 'commit';
+    mls: string;
+}
+export interface E2eeEvent {
+    seq: number;
+    kind: string;
+    envelope: E2eeEnvelope;
+    /** Present only for the device the Welcome was issued to. */
+    welcome: string | null;
+    createdAt: string;
+}
+/**
+ * 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.
+ */
+export declare class E2eeResource {
+    private client;
+    constructor(client: HttpClient);
+    registerDevice(input: {
+        device_name: string;
+        realm: string;
+        signing_key: string;
+        credential: Record<string, unknown>;
+    }): Promise<SingleResponse<E2eeDevice>>;
+    devices(params?: {
+        user_id?: string;
+    }): Promise<{
+        data: E2eeDevice[];
+    }>;
+    revokeDevice(deviceId: string): Promise<SingleResponse<E2eeDevice>>;
+    publishKeyPackages(input: {
+        device_id: string;
+        packages: string[];
+    }): Promise<SingleResponse<{
+        published: number;
+    }>>;
+    claimKeyPackage(input: {
+        device_id: string;
+        target_device_id: string;
+    }): Promise<SingleResponse<{
+        keyPackageId: string;
+        bytes: string;
+        device: E2eeDevice;
+    }>>;
+    appendEvent(conversationId: string, input: {
+        device_id: string;
+        envelope: E2eeEnvelope;
+        welcome?: string;
+        welcome_for_device_id?: string;
+        expected_commit_seq?: number;
+    }): Promise<SingleResponse<{
+        seq: number;
+        duplicate: boolean;
+        commitSeq: number;
+    }>>;
+    events(conversationId: string, params: {
+        device_id: string;
+        after_seq?: number;
+        limit?: number;
+    }): Promise<SingleResponse<{
+        headSeq: number;
+        commitSeq: number;
+        events: E2eeEvent[];
+    }>>;
+    acknowledge(conversationId: string, input: {
+        device_id: string;
+        seq: number;
+    }): Promise<SingleResponse<{
+        ackedSeq: number;
+    }>>;
+}

package/dist/resources/e2ee.js

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ */
+export class E2eeResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    registerDevice(input) {
+        return this.client.post('/e2ee/devices', input);
+    }
+    devices(params) {
+        return this.client.get('/e2ee/devices', params);
+    }
+    revokeDevice(deviceId) {
+        return this.client.post(`/e2ee/devices/${encodeURIComponent(deviceId)}/revoke`);
+    }
+    publishKeyPackages(input) {
+        return this.client.post('/e2ee/key-packages', input);
+    }
+    claimKeyPackage(input) {
+        return this.client.post('/e2ee/key-packages/claim', input);
+    }
+    appendEvent(conversationId, input) {
+        // Retries are safe: the server is idempotent on (conversation, device, event id).
+        return this.client.post(`/e2ee/conversations/${encodeURIComponent(conversationId)}/events`, input, { retry: true });
+    }
+    events(conversationId, params) {
+        return this.client.get(`/e2ee/conversations/${encodeURIComponent(conversationId)}/events`, params);
+    }
+    acknowledge(conversationId, input) {
+        return this.client.post(`/e2ee/conversations/${encodeURIComponent(conversationId)}/ack`, input);
+    }
+}

package/dist/resources/protocols.d.ts

@@ -703,6 +703,14 @@ export declare class ProtocolsResource {
     private subscriptionChanged;
     /** Confirmed safety choices from this authenticated SDK instance. Unsubscribe when its account or view changes. */
     onSourceControlChange(listener: (change: SocialSourceControlChange) => void): () => void;
+    /** Public-only conversation catalog for a configured app. Works with an anonymous client. */
+    sharedNetworks(projectId: string): Promise<SingleResponse<SocialNetwork[]>>;
+    /** Keyless public post read with app moderation; no account state or connected write authority. */
+    getSharedConversation(projectId: string, params: {
+        protocol: string;
+        post: string;
+        readRef?: string;
+    }): Promise<SingleResponse<SocialConversation>>;
     publicNetworks(): Promise<SingleResponse<SocialNetwork[]>>;
     /** Query the live public network. It does not import users or posts. */
     searchPublicProfiles(params: SearchPublicProfilesParams): Promise<SingleResponse<SocialProfilePage>>;

package/dist/resources/protocols.js

@@ -60,6 +60,16 @@ export class ProtocolsResource {
         this.sourceControlListeners.add(listener);
         return () => { this.sourceControlListeners.delete(listener); };
     }
+    /** Public-only conversation catalog for a configured app. Works with an anonymous client. */
+    sharedNetworks(projectId) {
+        return this.client.get(`/protocols/public/${encodeURIComponent(projectId)}/networks`);
+    }
+    /** Keyless public post read with app moderation; no account state or connected write authority. */
+    getSharedConversation(projectId, params) {
+        return this.client.get(`/protocols/public/${encodeURIComponent(projectId)}/conversation`, {
+            protocol: params.protocol, post: params.post, readRef: params.readRef,
+        });
+    }
     publicNetworks() {
         return this.client.get('/protocols/social/networks');
     }

package/llm.md

@@ -476,6 +476,19 @@ const { data: msgs } = await r.chat.messages(dm.id, { limit: 50 })
 
 Methods: `conversations`, `communityConversation`, `conversation`, `messages`, `send`, `dm`, `createGroup`, `deleteConversation`, `reactToMessage`, `editMessage`, `deleteMessage`, `markAsRead`, `unreadCount`
 
+### 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`.
+
+```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: 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 });
+await r.e2ee.acknowledge(conversationId, { device_id: device.id, seq: page.headSeq });
+```
+
 ### r.realtime — WebSocket Chat Client
 
 Provides persistent real-time streaming and chat presence, useful for building frontends (e.g. React Native, Web).
@@ -620,7 +633,7 @@ if (subscription.active) {
 - `r.inviteCodes` / `r.inviteCodesAdmin` — Invite code management
 - `r.organizationSettings` / `r.organizationSecurity` — Org configuration
 - 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. 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`.
+- `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.
   - Public trends: require `public_trends` from `publicNetworks()`, then `getPublicTrends({ protocol, limit?, cursor? })`; render `kind: topics` as source topics and `kind: posts` as source posts. With `trend_feed`, open only a returned current topic using `getPublicTrendFeed({ protocol, topic: trend.nativeId, limit?, cursor? })`. Show provider, observedAt and provider_ranked_window coverage; null rankingWindow is unknown, not a daily/global ranking. Preserve source order, canonical IDs and readRef, and opaque cursors. Topic catalogs do not paginate; Mastodon trends stop at 200 source positions. Both methods require users:read plus posts:read on the current human app key; Nostr trends are unsupported. Propagate errors; trend_unavailable means refresh the topic list. No ingestion or native writes.
   - `listCandidates({ protocol?, limit?, cursor? })` and `getCandidate(id)` are read-only quarantine review, not published-post search. Both require `admin` scope, a project-bound key, a live admin role, and existing project-admin access. The key supplies app/network scope; neither method accepts another project or network. They never invoke refresh, change settings, or publish.

package/package.json

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