@recursiv/sdk 0.7.81 → 0.7.82

package/README.md

@@ -98,7 +98,7 @@ for await (const chunk of r.agents.chatStream(agent.id, { message: 'Hello!' }))
 | `r.bookmarks` | `save`, `unsave`, `posts`, `list`, `keys`, `merge` — the member's saved posts, open-network posts and articles, synced across devices; `collections`: `list`, `create`, `update`, `remove`, `add`, `removeItem`, `items`, `posts` — private named collections of saves (0.7.68, where `network.getConfig()` advertises `capabilities.bookmark_collections`) |
 | `r.feeds` | `top` (what the member is most likely to engage with, rotated by what they saw, with open-network lanes and the lead story), `stories` (the story tail), `publicTop` (a visitor's top, keyless and edge-cacheable) |
 | `r.communities` | `create`, `join`, `search`, `members` |
-| `r.chat` | `send`, `dm`, `createGroup` (`encrypted: true` for an end-to-end encrypted group, 0.7.59), `messages` (cursor paging), `acceptRequest`, `declineRequest`, `leave`, `deleteConversation`; a private group's admin: `addMembers`, `removeMember`, `updateGroup` (0.7.59) |
+| `r.chat` | `send`, `dm`, `createGroup` (`encrypted: true` for an end-to-end encrypted group, 0.7.59), `messages` (cursor paging), `acceptRequest`, `declineRequest`, `leave`, `deleteConversation`; a private group's admin: `addMembers`, `removeMember`, `updateGroup` (0.7.59); photos and voice notes: `uploadAttachment`, `signAttachments` (private chat storage, 0.7.82) |
 | `r.tags` | `create`, `list` |
 | `r.signals` | `batch` (up to 100 engagement signals, such as views, dwell and hides, for the member's own ranking; `keepalive` for a page-leave flush), `record` (one signal) (0.7.71) |
 | `r.curator` | `today` (World Today; a world story can carry `story_key` and `discussion`, its count across networks), `storyPosts` / `memberStoryPosts` (one page of a story's posts, keyless or under the member's key), `storyPostPages` (walk every page), `forYou`, `run`, `refreshIfStale`, `seedDeck` |

package/dist/index.d.ts

@@ -165,7 +165,8 @@ export { POSTS_BATCH_MAX, PostsResource } from './resources/posts.js';
 export type { CategoryOrder, CategoryOrderMeta, CategoryOrderReason, PostBatch, PostBatchItem } from './resources/posts.js';
 export { UsersResource } from './resources/users.js';
 export { CommunitiesResource } from './resources/communities.js';
-export { ChatResource } from './resources/chat.js';
+export { ChatResource, CHAT_ATTACHMENT_REF_PREFIX, chatAttachmentKeysIn, chatAttachmentRefsIn } from './resources/chat.js';
+export type { ChatAttachmentRef, ChatAttachmentUploadInput, ChatAttachmentUploadUrl, ChatAttachmentUploadUrlInput, SignedChatAttachment, } 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, E2eeStartRequest, E2eeStatus, E2eeStatusReason, } from './resources/e2ee.js';
 export { ProjectsResource } from './resources/projects.js';
@@ -207,7 +208,7 @@ export type { AppSubscriptionBoostCredit, AppSubscriptionCheckoutResult, AppSubs
 export type { CuratorSource, CuratorPrompt, CuratorRunInput, CuratorRunResult, CuratorTodayEdition, CuratorTodayExcerpt, CuratorTodayLeadImage, CuratorTodayParams, CuratorTodayRadar, CuratorTodayReaction, CuratorTodayResponse, CuratorTodaySource, CuratorTodayStory, CuratorTodayDiscussion, CuratorStoryDiscussion, CuratorStoryLaneOutcome, CuratorStoryMindsPost, CuratorStoryPostItem, CuratorStoryPostPagesOptions, CuratorStoryPostsPage, CuratorStoryPostsParams, CuratorStoryReader, CuratorStorySocialPost, CuratorStoryVolumeLanes, CuratorStoryVolumeMeta, StoryPostNetwork, StoryPostPool, StoryPostSort, ForYouMeta, ForYouParams, ForYouSurface, ForYouWorldBlock, ForYouWorldBlockType, ForYouWorldCategoryShortcut, ForYouWorldItem, ForYouWorldMeta, ForYouWorldParams, ForYouWorldPart, ForYouWorldResponse, ForYouWorldStory, ForYouWorldStoryTarget, ForYouWorldViral, } from './resources/curator.js';
 export { STORY_POOL_MAX_POSTS, STORY_POST_NETWORKS, STORY_POSTS_PAGE_MAX } from './resources/curator.js';
 export { ReportsResource } from './resources/reports.js';
-export type { ReportTargetType, ReportStatus, CreateReportInput, ReportRecord, ResolveReportInput, } from './resources/reports.js';
+export type { ReportTargetType, ReportStatus, CreateReportInput, ReportRecord, ResolveReportInput, ReportedMessageAttachment, ReportedMessageAttachments, } from './resources/reports.js';
 export { JudgmentsResource, isJudgmentSharedWordsError } from './resources/judgments.js';
 export type { JudgmentSubjectKind, JudgmentSource, JudgmentOverrideMethod, PostLabelsStatus, PostLabelsQuery, PostLabelsSubject, PostLabelsCategory, PostLabelsPolitics, PostJudgmentRecord, PostJudgment, PostSafetyAttribution, PostLabelsCategoryView, PostLabelsSummaryView, PostLabelsFullView, PostLabels, DisputeJudgmentInput, JudgmentDispute, ReviewJudgmentInput, JudgmentReviewUpheld, JudgmentReviewAwaitingReviewer, JudgmentReviewOverridden, JudgmentReview, JudgmentSharedWordsDetails, JudgmentSharedWordsError, } from './resources/judgments.js';
 export { ModerationResource } from './resources/moderation.js';

package/dist/index.js

@@ -236,7 +236,7 @@ export { AuthResource } from './resources/auth.js';
 export { POSTS_BATCH_MAX, PostsResource } from './resources/posts.js';
 export { UsersResource } from './resources/users.js';
 export { CommunitiesResource } from './resources/communities.js';
-export { ChatResource } from './resources/chat.js';
+export { ChatResource, CHAT_ATTACHMENT_REF_PREFIX, chatAttachmentKeysIn, chatAttachmentRefsIn } from './resources/chat.js';
 export { E2eeResource } from './resources/e2ee.js';
 export { ProjectsResource } from './resources/projects.js';
 export { AgentsResource, SUPPORTED_MODELS, AGENT_DIRECTORY_SORTS, AGENT_DIRECTORY_MAX_LIMIT } from './resources/agents.js';

package/dist/resources/chat.d.ts

@@ -116,7 +116,11 @@ export declare class ChatResource {
             type: string;
         };
     }>>;
-    /** Edit a message (only the sender can edit) */
+    /**
+     * Edit a message's words (only the sender can edit). Keep each `chat-attachment:` reference it carries as it is: the
+     * server refuses an edit that drops, adds or swaps one (400 `attachment_refs_changed`, 0.7.82). To take an attachment
+     * back, delete the message.
+     */
     editMessage(messageId: string, input: {
         content: string;
     }): Promise<SingleResponse<Message>>;
@@ -130,4 +134,72 @@ export declare class ChatResource {
     unreadCount(conversationId: string): Promise<SingleResponse<{
         unread_count: number;
     }>>;
+    /**
+     * A PUT URL for one photo or voice note to send in a plaintext chat (0.7.82). With the server's private chat
+     * storage on, `private` is true, the URL writes into a private bucket and `ref` is `chat-attachment:<key>`, the text
+     * to send; with it off, `ref` is the upload's public URL. An end-to-end encrypted chat answers 409
+     * `conversation_encrypted`: its attachments go through `r.e2ee`. Most callers want `uploadAttachment`.
+     */
+    attachmentUploadUrl(conversationId: string, input: ChatAttachmentUploadUrlInput): Promise<SingleResponse<ChatAttachmentUploadUrl>>;
+    /**
+     * Upload one photo or voice note for a plaintext chat end to end and resolve the text to send for it (0.7.82): read
+     * the bytes, get the URL, PUT them with the matching Content-Type, and reject a failed transfer. Send `ref` as the
+     * message (or within it): a private reference renders through `signAttachments`, a public URL as before.
+     */
+    uploadAttachment(conversationId: string, input: ChatAttachmentUploadInput): Promise<ChatAttachmentUploadUrl>;
+    /**
+     * Short-lived URLs for a conversation's private attachments (0.7.82), at most 50 keys a call (the keys in its
+     * messages' `chat-attachment:` references; `chatAttachmentKeysIn` finds them). The server signs a key only for a
+     * member of the conversation, and only while a message its sender wrote there still carries it; any other key
+     * comes back with `url: null`. A URL works for about five minutes and is served `private, no-store`: ask again
+     * rather than keeping it.
+     */
+    signAttachments(conversationId: string, keys: string[]): Promise<SingleResponse<{
+        attachments: SignedChatAttachment[];
+    }>>;
+}
+export interface ChatAttachmentUploadUrlInput {
+    /** image/jpeg, image/png, image/webp, image/gif, audio/mpeg, audio/mp4, audio/wav, audio/ogg or audio/webm. */
+    content_type: string;
+    /** The exact byte count the PUT will send (signed into the URL; at most 50 MB). */
+    content_length: number;
+}
+export interface ChatAttachmentUploadUrl {
+    /** True when the attachment goes to the server's private chat storage. */
+    private: boolean;
+    /** PUT the bytes here with the same Content-Type. */
+    upload_url: string;
+    key: string;
+    /** The text to send for this attachment: `chat-attachment:<key>` when private, else the public URL. */
+    ref: string;
+}
+export interface ChatAttachmentUploadInput {
+    /** Caller-held bytes, such as a browser File or React Native Blob. */
+    blob?: Blob;
+    /** A local URI that the SDK should read into a Blob first. */
+    uri?: string;
+    /** Defaults to blob.type. */
+    contentType?: string;
+    /** Optional transport override for React Native adapters and focused tests. */
+    fetchImpl?: typeof fetch;
+}
+export interface SignedChatAttachment {
+    key: string;
+    /** A GET URL valid until `expires_at`, or null when this caller may not open the key. */
+    url: string | null;
+    expires_at: string | null;
+}
+/** The text a message carries before a private chat attachment's key. */
+export declare const CHAT_ATTACHMENT_REF_PREFIX = "chat-attachment:";
+/** One private attachment a message's text refers to. */
+export interface ChatAttachmentRef {
+    /** The whole reference as it appears in the text (`chat-attachment:<key>`). */
+    ref: string;
+    /** The key to pass to `signAttachments`. */
+    key: string;
+    kind: 'image' | 'audio';
 }
+/** The private attachments a message's text refers to, in order, each once (0.7.82). */
+export declare function chatAttachmentRefsIn(content: string | null | undefined): ChatAttachmentRef[];
+/** The private attachment keys a message's text refers to, for `signAttachments` (0.7.82). */
+export declare function chatAttachmentKeysIn(content: string | null | undefined): string[];

package/dist/resources/chat.js

@@ -1,3 +1,4 @@
+import { RecursivError } from '../errors.js';
 export class ChatResource {
     client;
     constructor(client) {
@@ -127,7 +128,11 @@ export class ChatResource {
     reactToMessage(messageId, input) {
         return this.client.post(`/chat/messages/${messageId}/react`, input);
     }
-    /** Edit a message (only the sender can edit) */
+    /**
+     * Edit a message's words (only the sender can edit). Keep each `chat-attachment:` reference it carries as it is: the
+     * server refuses an edit that drops, adds or swaps one (400 `attachment_refs_changed`, 0.7.82). To take an attachment
+     * back, delete the message.
+     */
     editMessage(messageId, input) {
         return this.client.put(`/chat/messages/${messageId}`, input);
     }
@@ -143,4 +148,81 @@ export class ChatResource {
     unreadCount(conversationId) {
         return this.client.get('/chat/unread-count', { conversation_id: conversationId });
     }
+    /**
+     * A PUT URL for one photo or voice note to send in a plaintext chat (0.7.82). With the server's private chat
+     * storage on, `private` is true, the URL writes into a private bucket and `ref` is `chat-attachment:<key>`, the text
+     * to send; with it off, `ref` is the upload's public URL. An end-to-end encrypted chat answers 409
+     * `conversation_encrypted`: its attachments go through `r.e2ee`. Most callers want `uploadAttachment`.
+     */
+    attachmentUploadUrl(conversationId, input) {
+        return this.client.post(`/chat/conversations/${conversationId}/attachments/upload-url`, input);
+    }
+    /**
+     * Upload one photo or voice note for a plaintext chat end to end and resolve the text to send for it (0.7.82): read
+     * the bytes, get the URL, PUT them with the matching Content-Type, and reject a failed transfer. Send `ref` as the
+     * message (or within it): a private reference renders through `signAttachments`, a public URL as before.
+     */
+    async uploadAttachment(conversationId, input) {
+        const hasBlob = input.blob !== undefined;
+        const hasUri = typeof input.uri === 'string' && input.uri.length > 0;
+        if (hasBlob === hasUri)
+            throw attachmentError(0, 'Provide exactly one of blob or uri.', 'invalid_upload_source');
+        const doFetch = input.fetchImpl ?? fetch;
+        let blob = input.blob;
+        if (!blob && input.uri) {
+            const source = await doFetch(input.uri);
+            if (!source.ok)
+                throw attachmentError(source.status, `Could not read upload source (HTTP ${source.status}).`, 'upload_source_failed');
+            blob = await source.blob();
+        }
+        if (!blob)
+            throw attachmentError(0, 'Upload source did not produce any bytes.', 'empty_upload_source');
+        const contentType = input.contentType?.trim() || blob.type?.trim();
+        if (!contentType)
+            throw attachmentError(0, 'A content type is required for chat attachments.', 'missing_content_type');
+        const minted = await this.attachmentUploadUrl(conversationId, { content_type: contentType, content_length: blob.size });
+        if (!minted?.data?.upload_url || !minted.data.ref) {
+            throw attachmentError(0, 'The API did not return a chat attachment upload URL.', 'missing_upload_url');
+        }
+        const response = await doFetch(minted.data.upload_url, { method: 'PUT', body: blob, headers: { 'Content-Type': contentType } });
+        if (!response.ok)
+            throw attachmentError(response.status, `Chat attachment upload failed (HTTP ${response.status}).`, 'chat_attachment_upload_failed');
+        return minted.data;
+    }
+    /**
+     * Short-lived URLs for a conversation's private attachments (0.7.82), at most 50 keys a call (the keys in its
+     * messages' `chat-attachment:` references; `chatAttachmentKeysIn` finds them). The server signs a key only for a
+     * member of the conversation, and only while a message its sender wrote there still carries it; any other key
+     * comes back with `url: null`. A URL works for about five minutes and is served `private, no-store`: ask again
+     * rather than keeping it.
+     */
+    signAttachments(conversationId, keys) {
+        return this.client.post(`/chat/conversations/${conversationId}/attachments/sign`, { keys });
+    }
+}
+function attachmentError(status, message, code) {
+    return new RecursivError(status, { type: 'upload_error', message, code });
+}
+/** The text a message carries before a private chat attachment's key. */
+export const CHAT_ATTACHMENT_REF_PREFIX = 'chat-attachment:';
+const CHAT_ATTACHMENT_REF_RE = /chat-attachment:(chat\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.([a-z0-9]{2,5}))/g;
+/** The extensions the server mints a private attachment key with (and jpeg), as it parses one; anything else is text. */
+const IMAGE_EXTENSIONS = new Set(['jpg', 'jpeg', 'png', 'webp', 'gif']);
+const AUDIO_EXTENSIONS = new Set(['mp3', 'm4a', 'wav', 'ogg', 'weba']);
+/** The private attachments a message's text refers to, in order, each once (0.7.82). */
+export function chatAttachmentRefsIn(content) {
+    if (!content?.includes(CHAT_ATTACHMENT_REF_PREFIX))
+        return [];
+    const found = new Map();
+    for (const match of content.matchAll(CHAT_ATTACHMENT_REF_RE)) {
+        const extension = match[2];
+        const kind = AUDIO_EXTENSIONS.has(extension) ? 'audio' : IMAGE_EXTENSIONS.has(extension) ? 'image' : null;
+        if (kind && !found.has(match[1]))
+            found.set(match[1], { ref: match[0], key: match[1], kind });
+    }
+    return [...found.values()];
+}
+/** The private attachment keys a message's text refers to, for `signAttachments` (0.7.82). */
+export function chatAttachmentKeysIn(content) {
+    return chatAttachmentRefsIn(content).map((attachment) => attachment.key);
 }

package/dist/resources/network.d.ts

@@ -11,10 +11,16 @@ interface NetworkConfig {
      * `bookmark_collections` (0.7.68; absent on older servers): this server serves bookmark collections
      * (`bookmarks.collections`). Show collections only when it is true, and still treat a 503
      * `lists_unavailable` as off.
+     *
+     * `child_safety_report_category` (absent on older servers): this server files the child-safety report category's
+     * sub-types (`child_safety:minor_in_danger`, `:sexualised_minor`, `:grooming_enticement`, `:trafficking`) as
+     * urgent: top severity, an immediate staff alert, decided by a person. Offer them only when it is true; otherwise
+     * report child sexual abuse material as `csam`, which every server files as urgent.
      */
     capabilities: {
         ws_token: boolean;
         bookmark_collections?: boolean;
+        child_safety_report_category?: boolean;
     };
     auth_methods: string;
     default_template_name: string | null;

package/dist/resources/reports.d.ts

@@ -57,4 +57,28 @@ export declare class ReportsResource {
     dismiss(reportId: string): Promise<SingleResponse<{
         success: true;
     }>>;
+    /**
+     * Short-lived URLs for the private chat photos and voice notes a reported message carries (0.7.82), for the staff
+     * person reviewing the report. A live admin's own key only: an AI account or an agent key gets 403
+     * `human_required`. Only the reported message's own attachments are signed; each URL works for about five minutes
+     * and is served `private, no-store`, so ask again rather than keeping it. A report of anything but a message is
+     * 400 `not_a_message_report`. Only a recipient's report opens anything: a report you filed yourself is 403
+     * `own_report`, and one not filed by a person in that chat (other than the message's sender) is 403
+     * `reporter_not_a_recipient`.
+     */
+    signAttachments(reportId: string): Promise<SingleResponse<ReportedMessageAttachments>>;
+}
+export interface ReportedMessageAttachment {
+    key: string;
+    kind: 'image' | 'audio';
+    content_type: string;
+    /** A GET URL valid until `expires_at`. */
+    url: string;
+    expires_at: string;
+}
+export interface ReportedMessageAttachments {
+    report_id: string;
+    message_id: string;
+    conversation_id: string;
+    attachments: ReportedMessageAttachment[];
 }

package/dist/resources/reports.js

@@ -27,4 +27,16 @@ export class ReportsResource {
     dismiss(reportId) {
         return this.client.post(`/reports/${encodeURIComponent(reportId)}/dismiss`);
     }
+    /**
+     * Short-lived URLs for the private chat photos and voice notes a reported message carries (0.7.82), for the staff
+     * person reviewing the report. A live admin's own key only: an AI account or an agent key gets 403
+     * `human_required`. Only the reported message's own attachments are signed; each URL works for about five minutes
+     * and is served `private, no-store`, so ask again rather than keeping it. A report of anything but a message is
+     * 400 `not_a_message_report`. Only a recipient's report opens anything: a report you filed yourself is 403
+     * `own_report`, and one not filed by a person in that chat (other than the message's sender) is 403
+     * `reporter_not_a_recipient`.
+     */
+    signAttachments(reportId) {
+        return this.client.post(`/reports/${encodeURIComponent(reportId)}/attachments/sign`);
+    }
 }

package/llm.md

@@ -504,7 +504,9 @@ const { data: group } = await r.chat.createGroup({ name: 'Team', member_ids: ['u
 const { data: msgs } = await r.chat.messages(dm.id, { limit: 50 })
 ```
 
-Methods: `conversations`, `communityConversation`, `conversation`, `messages`, `send`, `dm`, `createGroup`, `addMembers`, `removeMember`, `updateGroup`, `deleteConversation`, `leave`, `acceptRequest`, `declineRequest`, `reactToMessage`, `editMessage`, `deleteMessage`, `markAsRead`, `unreadCount`
+Methods: `conversations`, `communityConversation`, `conversation`, `messages`, `send`, `dm`, `createGroup`, `addMembers`, `removeMember`, `updateGroup`, `deleteConversation`, `leave`, `acceptRequest`, `declineRequest`, `reactToMessage`, `editMessage`, `deleteMessage`, `markAsRead`, `unreadCount`, `attachmentUploadUrl`, `uploadAttachment`, `signAttachments`
+
+Chat photos and voice notes (0.7.82): `const { ref } = await r.chat.uploadAttachment(dm.id, { blob })`, then send `ref`. With the server's private chat storage on, `ref` is `chat-attachment:<key>`: render it with `(await r.chat.signAttachments(dm.id, chatAttachmentKeysIn(message.content))).data.attachments` (URLs live about five minutes, `private, no-store`; `url: null` for a key the caller may not open). `editMessage` changes a message's words only: an edit that drops, adds or swaps a `chat-attachment:` reference gets 400 `attachment_refs_changed` (delete the message instead). Otherwise `ref` is a public URL, as before. A group's chat tied to a community always gets a public URL. Staff reviewing a member's report of a message open its private attachments with `r.reports.signAttachments(reportId)` (a live admin's own key; an AI account or agent key gets 403 `human_required`; only a report filed by a person in that chat, other than the sender and the caller, opens anything: 403 `own_report` or `reporter_not_a_recipient` otherwise).
 
 Scroll back with `messages(id, { cursor: page.meta.next_cursor })`, not a growing `offset`. Conversations carry `can_delete` / `can_leave`; check them before offering Delete or Leave.
 

package/package.json

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