@recursiv/sdk 0.7.69 → 0.7.70

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`, `retryChatStream`, `grantProjectAccess`, `conversations` |
-| `r.e2ee` | `status`, `registerDevice`, `devices`, `revokeDevice` (`{ cascade }` to also revoke devices approved through it; 409 `has_dependents` otherwise), `requestResetCode` and `resetAccount` (reset encrypted chat with an emailed code where `status().accountReset`), `publishKeyPackages`, `keyPackageStatus`, `claimKeyPackage`, `appendEvent`, `events`, `acknowledge`, `conversations`; device linking by scan: `createLink`, `link`, `scannedLink`, `approveLink`, `completeLink`, `linkProgress`, `cancelLink` (flag-gated E2EE v2 transport; its doorbell is `r.realtime.onE2eeEvent`, which carries a small message's stored ciphertext to the owner's own sockets; link and device changes arrive on `r.realtime.onE2eeLink` and `onE2eeDevices`) |
+| `r.e2ee` | `status`, `registerDevice`, `devices`, `revokeDevice` (`{ cascade }` to also revoke devices approved through it; 409 `has_dependents` otherwise), `requestResetCode` and `resetAccount` (reset encrypted chat with an emailed code where `status().accountReset`), `publishKeyPackages`, `keyPackageStatus`, `claimKeyPackage`, `appendEvent`, `events`, `acknowledge`, `conversations`, `requestStart` and `cancelStartRequest` (ask the other person to encrypt a chat when they have no device yet: a message with `metadata.kind` `e2ee_start_request`; the live ones are `ConversationDetail.encryption_requests`); device linking by scan: `createLink`, `link`, `scannedLink`, `approveLink`, `completeLink`, `linkProgress`, `cancelLink` (flag-gated E2EE v2 transport; its doorbell is `r.realtime.onE2eeEvent`, which carries a small message's stored ciphertext to the owner's own sockets; link and device changes arrive on `r.realtime.onE2eeLink` and `onE2eeDevices`) |
 | `r.brain` | `sendMessage` |
 | `r.commands` | `execute`, `gatePrompt` |
 | `r.projectBrain` | `tasks`, `decisions`, `milestones`, `completeTask`, `usage` |

package/dist/index.d.ts

@@ -158,7 +158,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 { E2eeAccountReset, E2eeDevice, E2eeDevicesRealtimeEvent, E2eeEnvelope, E2eeEvent, E2eeHasDependentsDetails, E2eeKeyPackageStatus, E2eeLink, E2eeLinkCancelledBy, E2eeLinkProgress, E2eeLinkRealtimeEvent, E2eeLinkState, E2eeObjectDownload, E2eeObjectUpload, E2eeRealtimeEvent, E2eeResetCodeSent, E2eeResetErrorCode, E2eeRevokeResponse, E2eeStatus, E2eeStatusReason, } from './resources/e2ee.js';
+export type { E2eeAccountReset, E2eeDevice, E2eeDevicesRealtimeEvent, E2eeEnvelope, E2eeEvent, E2eeHasDependentsDetails, E2eeKeyPackageStatus, E2eeLink, E2eeLinkCancelledBy, E2eeLinkProgress, E2eeLinkRealtimeEvent, E2eeLinkState, E2eeObjectDownload, E2eeObjectUpload, E2eeRealtimeEvent, E2eeResetCodeSent, E2eeResetErrorCode, E2eeRevokeResponse, E2eeStartRequest, E2eeStatus, E2eeStatusReason, } 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/realtime.d.ts

@@ -14,6 +14,8 @@ export interface ChatMessageEvent {
         isAi?: boolean;
     };
     createdAt: string;
+    /** The message's metadata as stored; `kind: 'e2ee_start_request'` is an encryption request (MessageMetadata). */
+    metadata?: Record<string, unknown>;
 }
 export interface ChatMessageEditEvent {
     id: string;
@@ -163,11 +165,18 @@ export declare class RealtimeClient {
     onAgentThinking(callback: (event: AgentThinkingEvent) => void): (() => void) | undefined;
     /**
      * A private group's people changed (0.7.59): `{ conversationId, change, userIds, actorId }`,
-     * change `added`, `removed`, `left` or `invites_cancelled`. Sent to everyone in the group
-     * and to the people it is about. Read the conversation again; in an encrypted group, check its keys.
+     * change `added`, `accepted`, `removed`, `left` or `invites_cancelled`, sent to everyone in the group
+     * and to the people it is about; or `device` (a member's device can be added to the encrypted group
+     * now), sent to the group's admin only, on a connection that may read encrypted chat for the group.
+     * Read the conversation again; in an encrypted group, check its keys.
      */
     onChatMembers(callback: (event: ChatMembersEvent) => void): () => void;
-    /** A private group was renamed (0.7.59): `{ conversationId, change: 'renamed', name, actorId }`. */
+    /**
+     * A conversation changed: a private group was renamed (0.7.59,
+     * `{ conversationId, change: 'renamed', name, actorId }`), or someone
+     * withdrew their request to encrypt a one-on-one chat
+     * (`encryption_request_withdrawn`, with `actorId`). Read it again.
+     */
     onChatConversation(callback: (event: ChatConversationEvent) => void): () => void;
     /**
      * The E2EE doorbell after each append to an encrypted conversation this

package/dist/realtime.js

@@ -429,13 +429,20 @@ export class RealtimeClient {
     }
     /**
      * A private group's people changed (0.7.59): `{ conversationId, change, userIds, actorId }`,
-     * change `added`, `removed`, `left` or `invites_cancelled`. Sent to everyone in the group
-     * and to the people it is about. Read the conversation again; in an encrypted group, check its keys.
+     * change `added`, `accepted`, `removed`, `left` or `invites_cancelled`, sent to everyone in the group
+     * and to the people it is about; or `device` (a member's device can be added to the encrypted group
+     * now), sent to the group's admin only, on a connection that may read encrypted chat for the group.
+     * Read the conversation again; in an encrypted group, check its keys.
      */
     onChatMembers(callback) {
         return this.on('chat:members', callback);
     }
-    /** A private group was renamed (0.7.59): `{ conversationId, change: 'renamed', name, actorId }`. */
+    /**
+     * A conversation changed: a private group was renamed (0.7.59,
+     * `{ conversationId, change: 'renamed', name, actorId }`), or someone
+     * withdrew their request to encrypt a one-on-one chat
+     * (`encryption_request_withdrawn`, with `actorId`). Read it again.
+     */
     onChatConversation(callback) {
         return this.on('chat:conversation', callback);
     }

package/dist/resources/chat.d.ts

@@ -93,7 +93,10 @@ export declare class ChatResource {
      * only stops listening for live events.
      */
     leave(conversationId: string): Promise<SingleResponse<LeaveConversationResult>>;
-    /** Accept a message request (`request_status: 'pending'`). Idempotent; also reverses a decline. */
+    /**
+     * Accept a message request (`request_status: 'pending'`). Idempotent; also reverses a decline. In a
+     * private group, everyone in it gets the realtime `chat:members` event (`accepted`); a repeat sends none.
+     */
     acceptRequest(conversationId: string): Promise<SingleResponse<ConversationRequestResult>>;
     /**
      * Decline a message request. The conversation leaves the caller's lists and

package/dist/resources/chat.js

@@ -108,7 +108,10 @@ export class ChatResource {
     leave(conversationId) {
         return this.client.post(`/chat/conversations/${conversationId}/leave`);
     }
-    /** Accept a message request (`request_status: 'pending'`). Idempotent; also reverses a decline. */
+    /**
+     * Accept a message request (`request_status: 'pending'`). Idempotent; also reverses a decline. In a
+     * private group, everyone in it gets the realtime `chat:members` event (`accepted`); a repeat sends none.
+     */
     acceptRequest(conversationId) {
         return this.client.post(`/chat/conversations/${conversationId}/accept`);
     }

package/dist/resources/e2ee.d.ts

@@ -232,6 +232,16 @@ export interface E2eeHasDependentsDetails {
     dependents: string[];
     root: boolean;
 }
+/**
+ * A live "Encrypt this chat" request (`e2ee.requestStart`): the message that
+ * carries it in the chat, and when it was made, by the relay's clock.
+ */
+export interface E2eeStartRequest {
+    message_id: string;
+    requested_at: string;
+    /** False when this request was live already, so nothing was sent. Absent from older relays. */
+    created?: boolean;
+}
 /** `revokeDevice`'s answer: the device, and every device the call revoked (the target first). */
 export interface E2eeRevokeResponse extends SingleResponse<E2eeDevice> {
     /** Absent on relays before 0.7.58. Empty when the device was already revoked and nothing else was. */
@@ -467,6 +477,37 @@ export declare class E2eeResource {
         device_id?: string;
         reason?: 'cancelled' | 'declined';
     }): Promise<SingleResponse<E2eeLink>>;
+    /**
+     * "Encrypt this chat" when the other person has no encrypted-chat device
+     * yet. The relay writes the request into the chat as a message from this
+     * account, with `metadata: { kind: 'e2ee_start_request', v: 1 }` (see
+     * `Message.metadata`), so it reaches the other person as a message does:
+     * their open chat, chat list and unread count, and one push, "<name> wants
+     * to encrypt your chat" (at most one a day per chat). Their device then
+     * starts the encryption as usual, with this account's devices. So this
+     * account needs an active device first (`no_root`, 409, otherwise).
+     *
+     * Answers this account's live request, `{ message_id, requested_at,
+     * created }`; asking again changes nothing and sends nothing (`created`
+     * false). The other person's app finds live requests in
+     * `chat.conversation()`'s `encryption_requests`. Refused where encryption
+     * cannot start: `conversation_not_eligible` (409), `blocked` (403),
+     * `forbidden` (403: not a member this key reaches); `conflict` (409) when
+     * the chat is already encrypted; `request_limit` (409, with
+     * `details.retryAfterSeconds`) after three requests in a day in this chat.
+     * Relays without it answer 404.
+     */
+    requestStart(conversationId: string): Promise<SingleResponse<E2eeStartRequest>>;
+    /**
+     * Withdraw this account's request to encrypt the chat: `{ cancelled }`,
+     * false when none of its requests was live (answered by a start, or
+     * withdrawn already). The request leaves the chat's history; open chats get
+     * `chat_message_delete`, and both people's sockets `chat:conversation`
+     * `encryption_request_withdrawn`. Relays without it answer 404.
+     */
+    cancelStartRequest(conversationId: string): Promise<SingleResponse<{
+        cancelled: boolean;
+    }>>;
     /**
      * The ids of the encrypted conversations this account belongs to, in this
      * key's scope, ordered by id: pass `next` as `after` for the next page

package/dist/resources/e2ee.js

@@ -178,6 +178,39 @@ export class E2eeResource {
     cancelLink(id, input) {
         return this.client.post(`/e2ee/links/${encodeURIComponent(id)}/cancel`, input ?? {});
     }
+    /**
+     * "Encrypt this chat" when the other person has no encrypted-chat device
+     * yet. The relay writes the request into the chat as a message from this
+     * account, with `metadata: { kind: 'e2ee_start_request', v: 1 }` (see
+     * `Message.metadata`), so it reaches the other person as a message does:
+     * their open chat, chat list and unread count, and one push, "<name> wants
+     * to encrypt your chat" (at most one a day per chat). Their device then
+     * starts the encryption as usual, with this account's devices. So this
+     * account needs an active device first (`no_root`, 409, otherwise).
+     *
+     * Answers this account's live request, `{ message_id, requested_at,
+     * created }`; asking again changes nothing and sends nothing (`created`
+     * false). The other person's app finds live requests in
+     * `chat.conversation()`'s `encryption_requests`. Refused where encryption
+     * cannot start: `conversation_not_eligible` (409), `blocked` (403),
+     * `forbidden` (403: not a member this key reaches); `conflict` (409) when
+     * the chat is already encrypted; `request_limit` (409, with
+     * `details.retryAfterSeconds`) after three requests in a day in this chat.
+     * Relays without it answer 404.
+     */
+    requestStart(conversationId) {
+        return this.client.put(`/e2ee/conversations/${encodeURIComponent(conversationId)}/start-request`, {});
+    }
+    /**
+     * Withdraw this account's request to encrypt the chat: `{ cancelled }`,
+     * false when none of its requests was live (answered by a start, or
+     * withdrawn already). The request leaves the chat's history; open chats get
+     * `chat_message_delete`, and both people's sockets `chat:conversation`
+     * `encryption_request_withdrawn`. Relays without it answer 404.
+     */
+    cancelStartRequest(conversationId) {
+        return this.client.delete(`/e2ee/conversations/${encodeURIComponent(conversationId)}/start-request`);
+    }
     /**
      * The ids of the encrypted conversations this account belongs to, in this
      * key's scope, ordered by id: pass `next` as `after` for the next page

package/dist/types.d.ts

@@ -760,6 +760,25 @@ export interface ConversationDetail {
      * older APIs.
      */
     last_activity_at?: string;
+    /**
+     * The live "Encrypt this chat" requests (`e2ee.requestStart`) that can
+     * still be answered, oldest first, at most one per person, however far
+     * back in the history their messages are. Served by `conversation()` on a
+     * plaintext one-on-one chat only: `[]` when there is none (or the chat is
+     * not accepted by both, or a block stands). A request is listed only while
+     * both people are inside the encryption pilot and its sender has an active
+     * device. Absent on other chats and from older APIs.
+     */
+    encryption_requests?: ConversationEncryptionRequest[];
+}
+/** One entry of `ConversationDetail.encryption_requests`. */
+export interface ConversationEncryptionRequest {
+    /** Who asked. The other person answers by starting encryption as usual, from their own device. */
+    sender_id: string;
+    /** The request's message (`metadata.kind` `e2ee_start_request`). */
+    message_id: string;
+    /** When it was asked, by the relay's clock. */
+    requested_at: string;
 }
 export type ChatMemberRole = 'admin' | 'member';
 /**
@@ -807,21 +826,39 @@ export interface UpdateGroupResult {
  * the conversation again (and, in an encrypted group, check its keys).
  * `actorId` is the admin for `added` and `removed`, and the leaver for `left`
  * and `invites_cancelled` (the invites an encrypted group's admin sent, which
- * went with them).
+ * went with them). `accepted`: the person in `userIds` (and `actorId`)
+ * accepted their invite; everyone in the group is told. `device`: one of that
+ * person's devices can be added to the encrypted group now (it has key
+ * packages after it had none); only the group's admin is told, since only the
+ * admin's device adds someone it invited, and only on a connection that may
+ * read encrypted chat for the group (a session, or a key for the group's app;
+ * never an agent's key). Read `change` defensively: an older API never sends
+ * the last two, and a newer one may add more.
  */
 export interface ChatMembersEvent {
     conversationId: string;
-    change: 'added' | 'removed' | 'left' | 'invites_cancelled';
+    change: 'added' | 'accepted' | 'removed' | 'left' | 'invites_cancelled' | 'device';
     userIds: string[];
     actorId: string;
 }
-/** Realtime `chat:conversation`: a private group was renamed by its admin. */
-export interface ChatConversationEvent {
+/**
+ * Realtime `chat:conversation`. Ids only, except a group's new name:
+ * - `renamed`: a private group was renamed by its admin (`name`).
+ * - `encryption_request_withdrawn`: `actorId` withdrew their request to
+ *   encrypt this one-on-one chat (`e2ee.cancelStartRequest`); it left the
+ *   history. Read the conversation and its messages again.
+ * Treat any other `change` as "read the conversation again".
+ */
+export type ChatConversationEvent = {
     conversationId: string;
     change: 'renamed';
     name: string;
     actorId: string;
-}
+} | {
+    conversationId: string;
+    change: 'encryption_request_withdrawn';
+    actorId: string;
+};
 export interface MessageReaction {
     type: string;
     user_id: string;
@@ -834,6 +871,20 @@ export interface MessageMedia {
     mime_type: string | null;
     file_name: string | null;
 }
+/**
+ * What a message the relay wrote on someone's behalf is, by `kind`. Only such
+ * messages carry it.
+ * - `e2ee_start_request` (`v` 1): the sender asked to turn on end-to-end
+ *   encryption for this one-on-one chat (`e2ee.requestStart`). Show it as
+ *   that request, not as its `content`, which is a fallback for apps that do
+ *   not know the kind. It is live while it is in the history and the chat is
+ *   not encrypted; a withdrawn one leaves the history. The person who did not
+ *   ask answers it by starting encryption as usual, from their own device.
+ */
+export interface MessageMetadata {
+    kind: 'e2ee_start_request';
+    v: number;
+}
 export interface Message {
     id: string;
     content: string;
@@ -842,6 +893,8 @@ export interface Message {
     media: MessageMedia[];
     reactions: MessageReaction[];
     created_at: string;
+    /** Absent on a person's own message, and from older APIs: see MessageMetadata. */
+    metadata?: MessageMetadata;
 }
 export interface SendMessageInput {
     conversation_id: string;
@@ -861,6 +914,8 @@ export interface ChatMessageEvent {
         isAi?: boolean;
     };
     createdAt: string;
+    /** The message's metadata as stored; `kind: 'e2ee_start_request'` is an encryption request (MessageMetadata). */
+    metadata?: Record<string, unknown>;
 }
 export interface ChatMessageEditEvent {
     id: string;

package/llm.md

@@ -522,6 +522,9 @@ await r.e2ee.appendEvent(conversationId, { device_id: device.id, envelope }); //
 await r.e2ee.appendEvent(conversationId, { device_id: device.id, envelope: reaction, silent: true }); // no push, no move up the chat list; every member's doorbell still rings
 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 });
+// The other person has no device yet: ask them (0.7.70). The relay writes it into the chat as a message with metadata { kind: 'e2ee_start_request', v: 1 }; their start answers it.
+await r.e2ee.requestStart(conversationId); // → { message_id, requested_at, created }; cancelStartRequest(conversationId) withdraws it
+// The live requests, however far back: (await r.chat.conversation(conversationId)).data.encryption_requests → [{ sender_id, message_id, requested_at }]
 // Doorbell after every append: { conversationId, seq, event? }. `event` (a small application message, as events() returns it) comes only to a socket of the owner's session or an owner key, never an agent-scoped key.
 // The policy is required: policyForConversationType(conversation.type) from @recursiv/e2ee ('direct' or 'group').
 r.realtime.onE2eeEvent(({ conversationId, event }) => (event ? controller.applyPushed(conversationId, event, policy) : controller.sync(conversationId, undefined, policy)));

package/package.json

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