@recursiv/sdk 0.7.57 → 0.7.59

package/dist/resources/e2ee.d.ts

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

package/dist/resources/e2ee.js

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

package/dist/resources/email.d.ts

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

package/dist/resources/email.js

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

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

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

package/dist/resources/env-vars.js

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

package/dist/resources/moderation.d.ts

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

package/dist/resources/moderation.js

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

package/dist/resources/posts.d.ts

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

package/dist/resources/posts.js

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