@doist/comms-sdk 0.3.0 → 0.4.1

package/dist/cjs/clients/attachments-client.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AttachmentsClient = void 0;
+const endpoints_1 = require("../consts/endpoints");
+const entities_1 = require("../types/entities");
+const multipart_upload_1 = require("../utils/multipart-upload");
+const uuidv7_1 = require("../utils/uuidv7");
+const base_client_1 = require("./base-client");
+/**
+ * Resolve the `attachment_id`: validate a caller-supplied value (throwing an
+ * {@link UuidV7Error} that names `attachmentId` rather than the generic `id`) or
+ * mint a fresh one. Wraps {@link resolveCreateId} so the error contract matches the
+ * client's actual parameter.
+ */
+function resolveAttachmentId(attachmentId) {
+    if (attachmentId !== undefined && !(0, uuidv7_1.isValidUuidV7Base58)(attachmentId)) {
+        throw new uuidv7_1.UuidV7Error(`invalid attachmentId ${JSON.stringify(attachmentId)} — use generateId() or omit \`attachmentId\` and let the SDK mint one.`);
+    }
+    return (0, uuidv7_1.resolveCreateId)(attachmentId);
+}
+/**
+ * Client for uploading file attachments to Comms.
+ *
+ * Attachments are uploaded independently, then referenced by passing the returned
+ * {@link Attachment} into the `attachments` array of `comments.createComment`,
+ * `conversationMessages.createMessage`, and similar calls.
+ */
+class AttachmentsClient extends base_client_1.BaseClient {
+    /**
+     * Uploads a file and returns the created {@link Attachment}.
+     *
+     * Mirrors the canonical multipart upload: `POST /attachments/upload` with the `file`
+     * binary plus `file_name`, `file_size`, `attachment_id`, and `underlying_type` form
+     * fields.
+     *
+     * @param args - The file to upload and optional metadata.
+     * @returns The created attachment, ready to attach to a comment or message.
+     *
+     * @example
+     * ```typescript
+     * import { readFile } from 'node:fs/promises'
+     *
+     * const attachment = await api.attachments.upload({
+     *   file: await readFile('./diagram.png'),
+     *   fileName: 'diagram.png',
+     * })
+     *
+     * await api.comments.createComment({
+     *   threadId: '7YpL3oZ4kZ9vP7Q1tR2sX3z',
+     *   content: 'See attached',
+     *   attachments: [attachment],
+     * })
+     * ```
+     */
+    async upload(args) {
+        const data = await (0, multipart_upload_1.uploadMultipartFile)({
+            baseUrl: this.getBaseUri(),
+            authToken: this.apiToken,
+            endpoint: `${endpoints_1.ENDPOINT_ATTACHMENTS}/upload`,
+            file: args.file,
+            fileName: args.fileName,
+            contentType: args.contentType,
+            additionalFields: {
+                attachment_id: resolveAttachmentId(args.attachmentId),
+            },
+            customFetch: this.customFetch,
+        });
+        return entities_1.AttachmentSchema.parse(data);
+    }
+}
+exports.AttachmentsClient = AttachmentsClient;

package/dist/cjs/clients/threads-client.js

@@ -95,6 +95,7 @@ class ThreadsClient extends base_client_1.BaseClient {
      * @param args.content - The thread content.
      * @param args.recipients - Optional array of user IDs to notify.
      * @param args.groups - Optional array of custom group IDs to notify.
+     * @param args.attachments - Optional array of {@link Attachment}s (from `attachments.upload`).
      * @returns The created thread object.
      *
      * @example

package/dist/cjs/comms-api.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CommsApi = void 0;
+const attachments_client_1 = require("./clients/attachments-client");
 const channels_client_1 = require("./clients/channels-client");
 const comments_client_1 = require("./clients/comments-client");
 const conversation_messages_client_1 = require("./clients/conversation-messages-client");
@@ -51,6 +52,7 @@ class CommsApi {
         this.inbox = new inbox_client_1.InboxClient(clientConfig);
         this.reactions = new reactions_client_1.ReactionsClient(clientConfig);
         this.search = new search_client_1.SearchClient(clientConfig);
+        this.attachments = new attachments_client_1.AttachmentsClient(clientConfig);
     }
     /**
      * Drains the SDK's process-global connection pool. CLIs and scripts

package/dist/cjs/consts/endpoints.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ENDPOINT_CONVERSATION_MESSAGES = exports.ENDPOINT_SEARCH = exports.ENDPOINT_REACTIONS = exports.ENDPOINT_INBOX = exports.ENDPOINT_NOTIFICATIONS = exports.ENDPOINT_COMMENTS = exports.ENDPOINT_CONVERSATIONS = exports.ENDPOINT_GROUPS = exports.ENDPOINT_THREADS = exports.ENDPOINT_CHANNELS = exports.ENDPOINT_WORKSPACES = exports.ENDPOINT_USERS = void 0;
+exports.ENDPOINT_ATTACHMENTS = exports.ENDPOINT_CONVERSATION_MESSAGES = exports.ENDPOINT_SEARCH = exports.ENDPOINT_REACTIONS = exports.ENDPOINT_INBOX = exports.ENDPOINT_NOTIFICATIONS = exports.ENDPOINT_COMMENTS = exports.ENDPOINT_CONVERSATIONS = exports.ENDPOINT_GROUPS = exports.ENDPOINT_THREADS = exports.ENDPOINT_CHANNELS = exports.ENDPOINT_WORKSPACES = exports.ENDPOINT_USERS = void 0;
 exports.getCommsBaseUri = getCommsBaseUri;
 const api_version_1 = require("../types/api-version");
 const BASE_URI = 'https://comms.todoist.com';
@@ -30,3 +30,4 @@ exports.ENDPOINT_INBOX = 'inbox';
 exports.ENDPOINT_REACTIONS = 'reactions';
 exports.ENDPOINT_SEARCH = 'search';
 exports.ENDPOINT_CONVERSATION_MESSAGES = 'conversation_messages';
+exports.ENDPOINT_ATTACHMENTS = 'attachments';

package/dist/cjs/index.js

@@ -14,8 +14,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.closeDefaultDispatcher = exports.CommsApi = exports.WorkspacesClient = exports.WorkspaceUsersClient = exports.UsersClient = exports.ThreadsClient = exports.SearchClient = exports.ReactionsClient = exports.InboxClient = exports.GroupsClient = exports.ConversationsClient = exports.ConversationMessagesClient = exports.CommentsClient = exports.ChannelsClient = void 0;
+exports.closeDefaultDispatcher = exports.CommsApi = exports.WorkspacesClient = exports.WorkspaceUsersClient = exports.UsersClient = exports.ThreadsClient = exports.SearchClient = exports.ReactionsClient = exports.InboxClient = exports.GroupsClient = exports.ConversationsClient = exports.ConversationMessagesClient = exports.CommentsClient = exports.ChannelsClient = exports.AttachmentsClient = void 0;
 __exportStar(require("./authentication"), exports);
+var attachments_client_1 = require("./clients/attachments-client");
+Object.defineProperty(exports, "AttachmentsClient", { enumerable: true, get: function () { return attachments_client_1.AttachmentsClient; } });
 var channels_client_1 = require("./clients/channels-client");
 Object.defineProperty(exports, "ChannelsClient", { enumerable: true, get: function () { return channels_client_1.ChannelsClient; } });
 var comments_client_1 = require("./clients/comments-client");

package/dist/cjs/types/entities.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SearchResultSchema = exports.SEARCH_RESULT_TYPES = exports.UnreadConversationSchema = exports.UnreadThreadSchema = exports.InboxThreadSchema = exports.ConversationMessageSchema = exports.ConversationMessageObjectSchema = exports.WorkspaceUserSchema = exports.CommentSchema = exports.CommentObjectSchema = exports.ConversationSchema = exports.ConversationObjectSchema = exports.GroupSchema = exports.ThreadSchema = exports.ThreadObjectSchema = exports.ChannelSchema = exports.ChannelObjectSchema = exports.WorkspaceSchema = exports.UserSchema = exports.BaseUserSchema = exports.AttachmentSchema = exports.StatusOkSchema = exports.SystemMessageSchema = void 0;
+exports.SearchResultSchema = exports.SEARCH_RESULT_TYPES = exports.UnreadConversationSchema = exports.UnreadThreadSchema = exports.InboxThreadSchema = exports.ConversationMessageSchema = exports.ConversationMessageObjectSchema = exports.WorkspaceUserSchema = exports.CommentSchema = exports.CommentObjectSchema = exports.ConversationSchema = exports.ConversationObjectSchema = exports.GroupSchema = exports.ThreadSchema = exports.ThreadObjectSchema = exports.ChannelSchema = exports.ChannelObjectSchema = exports.WorkspaceSchema = exports.UserSchema = exports.BaseUserSchema = exports.RequestAttachmentSchema = exports.AttachmentSchema = exports.StatusOkSchema = exports.SystemMessageSchema = void 0;
 exports.createChannelSchema = createChannelSchema;
 exports.createThreadSchema = createThreadSchema;
 exports.createConversationSchema = createConversationSchema;
@@ -33,8 +33,7 @@ exports.StatusOkSchema = zod_1.z.object({ status: zod_1.z.literal('ok') });
 // the attachment kind (file vs image vs link preview vs unfurled GIF).
 // Loose: unknown keys from the backend pass through rather than being
 // stripped, so newly-added or off-spec fields stay accessible to callers.
-exports.AttachmentSchema = zod_1.z
-    .object({
+const attachmentShape = {
     attachmentId: zod_1.z.string(),
     urlType: zod_1.z.string(),
     title: zod_1.z.string().nullable().optional(),
@@ -51,8 +50,12 @@ exports.AttachmentSchema = zod_1.z
     video: zod_1.z.string().nullable().optional(),
     videoType: zod_1.z.string().nullable().optional(),
     videoAutoPlay: zod_1.z.boolean().nullable().optional(),
-})
-    .loose();
+};
+exports.AttachmentSchema = zod_1.z.object(attachmentShape).loose();
+// Request-side attachment schema. Unlike the loose response `AttachmentSchema`,
+// this strips unknown keys so caller typos / off-spec fields are dropped instead
+// of being forwarded on the wire. Use this for `*Args` request schemas.
+exports.RequestAttachmentSchema = zod_1.z.object(attachmentShape);
 // Fields shared by `User` and `WorkspaceUser`. Profile fields
 // (`fullName`, `imageId`, avatar URLs) are sourced from Todoist-ID.
 exports.BaseUserSchema = zod_1.z.object({

package/dist/cjs/types/requests.js

@@ -42,6 +42,7 @@ exports.CreateThreadArgsSchema = zod_1.z.object({
     id: zod_1.z.string().optional(),
     recipients: zod_1.z.array(zod_1.z.number()).nullable().optional(),
     groups: zod_1.z.array(zod_1.z.string()).nullable().optional(),
+    attachments: zod_1.z.array(entities_1.RequestAttachmentSchema).nullable().optional(),
 });
 exports.UpdateThreadArgsSchema = zod_1.z.object({
     id: zod_1.z.string(),
@@ -52,7 +53,7 @@ exports.CreateCommentArgsSchema = zod_1.z.object({
     threadId: zod_1.z.string(),
     content: zod_1.z.string(),
     id: zod_1.z.string().optional(),
-    attachments: zod_1.z.array(entities_1.AttachmentSchema).nullable().optional(),
+    attachments: zod_1.z.array(entities_1.RequestAttachmentSchema).nullable().optional(),
     actions: zod_1.z.unknown().nullable().optional(),
     recipients: zod_1.z.array(zod_1.z.number()).nullable().optional(),
     groups: zod_1.z.array(zod_1.z.string()).nullable().optional(),
@@ -76,7 +77,7 @@ exports.CreateMessageArgsSchema = zod_1.z
     threadId: zod_1.z.string().nullable().optional(),
     content: zod_1.z.string(),
     id: zod_1.z.string().optional(),
-    attachments: zod_1.z.array(entities_1.AttachmentSchema).nullable().optional(),
+    attachments: zod_1.z.array(entities_1.RequestAttachmentSchema).nullable().optional(),
 })
     .refine((data) => {
     return ((data.conversationId && !data.threadId) || (!data.conversationId && data.threadId));

package/dist/cjs/utils/multipart-upload.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getContentTypeFromFileName = getContentTypeFromFileName;
+exports.uploadMultipartFile = uploadMultipartFile;
+const fetch_with_retry_1 = require("../transport/fetch-with-retry");
+/**
+ * Determine a content-type from a filename extension. Falls back to
+ * `application/octet-stream` for unknown extensions.
+ */
+function getContentTypeFromFileName(fileName) {
+    const extension = fileName.toLowerCase().split('.').pop();
+    return extension ? (MIME_BY_EXTENSION[extension] ?? DEFAULT_MIME_TYPE) : DEFAULT_MIME_TYPE;
+}
+const DEFAULT_MIME_TYPE = 'application/octet-stream';
+/**
+ * Extension → MIME map covering the formats commonly attached to messages.
+ * Anything not listed falls back to {@link DEFAULT_MIME_TYPE}; callers can
+ * always override via the `contentType` argument.
+ */
+const MIME_BY_EXTENSION = {
+    // Images
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    svg: 'image/svg+xml',
+    bmp: 'image/bmp',
+    ico: 'image/x-icon',
+    tif: 'image/tiff',
+    tiff: 'image/tiff',
+    heic: 'image/heic',
+    heif: 'image/heif',
+    avif: 'image/avif',
+    // Documents / text
+    pdf: 'application/pdf',
+    txt: 'text/plain',
+    md: 'text/markdown',
+    csv: 'text/csv',
+    json: 'application/json',
+    xml: 'application/xml',
+    html: 'text/html',
+    htm: 'text/html',
+    rtf: 'application/rtf',
+    doc: 'application/msword',
+    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    xls: 'application/vnd.ms-excel',
+    xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    ppt: 'application/vnd.ms-powerpoint',
+    pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    // Archives
+    zip: 'application/zip',
+    gz: 'application/gzip',
+    tar: 'application/x-tar',
+    '7z': 'application/x-7z-compressed',
+    rar: 'application/vnd.rar',
+    // Audio
+    mp3: 'audio/mpeg',
+    wav: 'audio/wav',
+    ogg: 'audio/ogg',
+    m4a: 'audio/mp4',
+    flac: 'audio/flac',
+    aac: 'audio/aac',
+    // Video
+    mp4: 'video/mp4',
+    m4v: 'video/mp4',
+    mov: 'video/quicktime',
+    avi: 'video/x-msvideo',
+    webm: 'video/webm',
+    mkv: 'video/x-matroska',
+};
+/**
+ * Normalise a supported {@link UploadFile} into a `Blob` plus a resolved file name and
+ * content type, so uploads use the cross-platform global `FormData`/`Blob` body that
+ * `undici` and browsers both accept natively.
+ */
+function toBlob(file, fileName, contentType) {
+    if (file instanceof Blob) {
+        // Duck-type the name rather than `instanceof File`: `File` isn't a global in
+        // Node 18, so a `node:buffer` `File` (which carries a real `name`) would
+        // otherwise fall back to `'upload'` and lose its inferred file name.
+        const blobName = file.name;
+        const name = fileName || (typeof blobName === 'string' ? blobName : undefined) || 'upload';
+        const type = contentType || file.type || getContentTypeFromFileName(name);
+        // Re-wrap only when stamping a type the Blob doesn't already carry.
+        const blob = file.type === type ? file : new Blob([file], { type });
+        return { blob, fileName: name, contentType: type };
+    }
+    if (file instanceof Uint8Array) {
+        if (!fileName) {
+            throw new Error('fileName is required when uploading raw bytes');
+        }
+        const type = contentType || getContentTypeFromFileName(fileName);
+        // `Blob` accepts any `ArrayBufferView`; the cast satisfies the stricter lib
+        // `BlobPart` type (which pins the backing buffer to `ArrayBuffer`).
+        return { blob: new Blob([file], { type }), fileName, contentType: type };
+    }
+    throw new Error('Unsupported file type for upload: expected a Blob or Uint8Array');
+}
+/**
+ * Upload a file using `multipart/form-data`.
+ *
+ * Builds the request body with the global `FormData`/`Blob` so it works unchanged in the
+ * browser and in Node.js (via `undici`). The `file` part is sent alongside `file_name`,
+ * `file_size`, and `underlying_type` fields (the canonical Comms upload shape); any
+ * `additionalFields` are merged in and override the derived values. Authentication uses
+ * `Authorization: Bearer`, matching every other Comms SDK client, and `Content-Type` is
+ * intentionally left unset so the runtime adds the correct multipart boundary.
+ *
+ * The response is JSON-parsed and camel-cased by {@link fetchWithRetry}; callers validate
+ * the returned shape with the appropriate schema.
+ */
+async function uploadMultipartFile(args) {
+    const { baseUrl, authToken, endpoint, file, fileName, contentType, additionalFields, maxRetries = 0, requestId, customFetch, } = args;
+    const { blob, fileName: resolvedFileName, contentType: resolvedType, } = toBlob(file, fileName, contentType);
+    const fields = {
+        file_name: resolvedFileName,
+        file_size: blob.size,
+        underlying_type: resolvedType,
+        ...additionalFields,
+    };
+    const form = new FormData();
+    form.append('file', blob, resolvedFileName);
+    for (const [key, value] of Object.entries(fields)) {
+        if (value !== undefined && value !== null) {
+            form.append(key, String(value));
+        }
+    }
+    const headers = {
+        Authorization: `Bearer ${authToken}`,
+    };
+    if (requestId) {
+        headers['X-Request-Id'] = requestId;
+    }
+    const url = new URL(endpoint, baseUrl).toString();
+    const response = await (0, fetch_with_retry_1.fetchWithRetry)(url, {
+        method: 'POST',
+        headers,
+        body: form,
+        // Don't set Content-Type — the runtime adds the multipart boundary.
+        timeout: 30000,
+    }, maxRetries, customFetch);
+    return response.data;
+}

package/dist/esm/clients/attachments-client.js

@@ -0,0 +1,67 @@
+import { ENDPOINT_ATTACHMENTS } from '../consts/endpoints.js';
+import { AttachmentSchema } from '../types/entities.js';
+import { uploadMultipartFile } from '../utils/multipart-upload.js';
+import { isValidUuidV7Base58, resolveCreateId, UuidV7Error } from '../utils/uuidv7.js';
+import { BaseClient } from './base-client.js';
+/**
+ * Resolve the `attachment_id`: validate a caller-supplied value (throwing an
+ * {@link UuidV7Error} that names `attachmentId` rather than the generic `id`) or
+ * mint a fresh one. Wraps {@link resolveCreateId} so the error contract matches the
+ * client's actual parameter.
+ */
+function resolveAttachmentId(attachmentId) {
+    if (attachmentId !== undefined && !isValidUuidV7Base58(attachmentId)) {
+        throw new UuidV7Error(`invalid attachmentId ${JSON.stringify(attachmentId)} — use generateId() or omit \`attachmentId\` and let the SDK mint one.`);
+    }
+    return resolveCreateId(attachmentId);
+}
+/**
+ * Client for uploading file attachments to Comms.
+ *
+ * Attachments are uploaded independently, then referenced by passing the returned
+ * {@link Attachment} into the `attachments` array of `comments.createComment`,
+ * `conversationMessages.createMessage`, and similar calls.
+ */
+export class AttachmentsClient extends BaseClient {
+    /**
+     * Uploads a file and returns the created {@link Attachment}.
+     *
+     * Mirrors the canonical multipart upload: `POST /attachments/upload` with the `file`
+     * binary plus `file_name`, `file_size`, `attachment_id`, and `underlying_type` form
+     * fields.
+     *
+     * @param args - The file to upload and optional metadata.
+     * @returns The created attachment, ready to attach to a comment or message.
+     *
+     * @example
+     * ```typescript
+     * import { readFile } from 'node:fs/promises'
+     *
+     * const attachment = await api.attachments.upload({
+     *   file: await readFile('./diagram.png'),
+     *   fileName: 'diagram.png',
+     * })
+     *
+     * await api.comments.createComment({
+     *   threadId: '7YpL3oZ4kZ9vP7Q1tR2sX3z',
+     *   content: 'See attached',
+     *   attachments: [attachment],
+     * })
+     * ```
+     */
+    async upload(args) {
+        const data = await uploadMultipartFile({
+            baseUrl: this.getBaseUri(),
+            authToken: this.apiToken,
+            endpoint: `${ENDPOINT_ATTACHMENTS}/upload`,
+            file: args.file,
+            fileName: args.fileName,
+            contentType: args.contentType,
+            additionalFields: {
+                attachment_id: resolveAttachmentId(args.attachmentId),
+            },
+            customFetch: this.customFetch,
+        });
+        return AttachmentSchema.parse(data);
+    }
+}

package/dist/esm/clients/threads-client.js

@@ -92,6 +92,7 @@ export class ThreadsClient extends BaseClient {
      * @param args.content - The thread content.
      * @param args.recipients - Optional array of user IDs to notify.
      * @param args.groups - Optional array of custom group IDs to notify.
+     * @param args.attachments - Optional array of {@link Attachment}s (from `attachments.upload`).
      * @returns The created thread object.
      *
      * @example

package/dist/esm/comms-api.js

@@ -1,3 +1,4 @@
+import { AttachmentsClient } from './clients/attachments-client.js';
 import { ChannelsClient } from './clients/channels-client.js';
 import { CommentsClient } from './clients/comments-client.js';
 import { ConversationMessagesClient } from './clients/conversation-messages-client.js';
@@ -48,6 +49,7 @@ export class CommsApi {
         this.inbox = new InboxClient(clientConfig);
         this.reactions = new ReactionsClient(clientConfig);
         this.search = new SearchClient(clientConfig);
+        this.attachments = new AttachmentsClient(clientConfig);
     }
     /**
      * Drains the SDK's process-global connection pool. CLIs and scripts

package/dist/esm/consts/endpoints.js

@@ -26,3 +26,4 @@ export const ENDPOINT_INBOX = 'inbox';
 export const ENDPOINT_REACTIONS = 'reactions';
 export const ENDPOINT_SEARCH = 'search';
 export const ENDPOINT_CONVERSATION_MESSAGES = 'conversation_messages';
+export const ENDPOINT_ATTACHMENTS = 'attachments';

package/dist/esm/index.js

@@ -1,4 +1,5 @@
 export * from './authentication.js';
+export { AttachmentsClient } from './clients/attachments-client.js';
 export { ChannelsClient } from './clients/channels-client.js';
 export { CommentsClient } from './clients/comments-client.js';
 export { ConversationMessagesClient } from './clients/conversation-messages-client.js';

package/dist/esm/types/entities.js

@@ -23,8 +23,7 @@ export const StatusOkSchema = z.object({ status: z.literal('ok') });
 // the attachment kind (file vs image vs link preview vs unfurled GIF).
 // Loose: unknown keys from the backend pass through rather than being
 // stripped, so newly-added or off-spec fields stay accessible to callers.
-export const AttachmentSchema = z
-    .object({
+const attachmentShape = {
     attachmentId: z.string(),
     urlType: z.string(),
     title: z.string().nullable().optional(),
@@ -41,8 +40,12 @@ export const AttachmentSchema = z
     video: z.string().nullable().optional(),
     videoType: z.string().nullable().optional(),
     videoAutoPlay: z.boolean().nullable().optional(),
-})
-    .loose();
+};
+export const AttachmentSchema = z.object(attachmentShape).loose();
+// Request-side attachment schema. Unlike the loose response `AttachmentSchema`,
+// this strips unknown keys so caller typos / off-spec fields are dropped instead
+// of being forwarded on the wire. Use this for `*Args` request schemas.
+export const RequestAttachmentSchema = z.object(attachmentShape);
 // Fields shared by `User` and `WorkspaceUser`. Profile fields
 // (`fullName`, `imageId`, avatar URLs) are sourced from Todoist-ID.
 export const BaseUserSchema = z.object({

package/dist/esm/types/requests.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { AttachmentSchema } from './entities.js';
+import { RequestAttachmentSchema } from './entities.js';
 import { NOTIFY_AUDIENCES } from './enums.js';
 /**
  * Create-side requests require an `id` on the wire. The SDK clients accept
@@ -39,6 +39,7 @@ export const CreateThreadArgsSchema = z.object({
     id: z.string().optional(),
     recipients: z.array(z.number()).nullable().optional(),
     groups: z.array(z.string()).nullable().optional(),
+    attachments: z.array(RequestAttachmentSchema).nullable().optional(),
 });
 export const UpdateThreadArgsSchema = z.object({
     id: z.string(),
@@ -49,7 +50,7 @@ export const CreateCommentArgsSchema = z.object({
     threadId: z.string(),
     content: z.string(),
     id: z.string().optional(),
-    attachments: z.array(AttachmentSchema).nullable().optional(),
+    attachments: z.array(RequestAttachmentSchema).nullable().optional(),
     actions: z.unknown().nullable().optional(),
     recipients: z.array(z.number()).nullable().optional(),
     groups: z.array(z.string()).nullable().optional(),
@@ -73,7 +74,7 @@ export const CreateMessageArgsSchema = z
     threadId: z.string().nullable().optional(),
     content: z.string(),
     id: z.string().optional(),
-    attachments: z.array(AttachmentSchema).nullable().optional(),
+    attachments: z.array(RequestAttachmentSchema).nullable().optional(),
 })
     .refine((data) => {
     return ((data.conversationId && !data.threadId) || (!data.conversationId && data.threadId));

package/dist/esm/utils/multipart-upload.js

@@ -0,0 +1,140 @@
+import { fetchWithRetry } from '../transport/fetch-with-retry.js';
+/**
+ * Determine a content-type from a filename extension. Falls back to
+ * `application/octet-stream` for unknown extensions.
+ */
+export function getContentTypeFromFileName(fileName) {
+    const extension = fileName.toLowerCase().split('.').pop();
+    return extension ? (MIME_BY_EXTENSION[extension] ?? DEFAULT_MIME_TYPE) : DEFAULT_MIME_TYPE;
+}
+const DEFAULT_MIME_TYPE = 'application/octet-stream';
+/**
+ * Extension → MIME map covering the formats commonly attached to messages.
+ * Anything not listed falls back to {@link DEFAULT_MIME_TYPE}; callers can
+ * always override via the `contentType` argument.
+ */
+const MIME_BY_EXTENSION = {
+    // Images
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    svg: 'image/svg+xml',
+    bmp: 'image/bmp',
+    ico: 'image/x-icon',
+    tif: 'image/tiff',
+    tiff: 'image/tiff',
+    heic: 'image/heic',
+    heif: 'image/heif',
+    avif: 'image/avif',
+    // Documents / text
+    pdf: 'application/pdf',
+    txt: 'text/plain',
+    md: 'text/markdown',
+    csv: 'text/csv',
+    json: 'application/json',
+    xml: 'application/xml',
+    html: 'text/html',
+    htm: 'text/html',
+    rtf: 'application/rtf',
+    doc: 'application/msword',
+    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    xls: 'application/vnd.ms-excel',
+    xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    ppt: 'application/vnd.ms-powerpoint',
+    pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    // Archives
+    zip: 'application/zip',
+    gz: 'application/gzip',
+    tar: 'application/x-tar',
+    '7z': 'application/x-7z-compressed',
+    rar: 'application/vnd.rar',
+    // Audio
+    mp3: 'audio/mpeg',
+    wav: 'audio/wav',
+    ogg: 'audio/ogg',
+    m4a: 'audio/mp4',
+    flac: 'audio/flac',
+    aac: 'audio/aac',
+    // Video
+    mp4: 'video/mp4',
+    m4v: 'video/mp4',
+    mov: 'video/quicktime',
+    avi: 'video/x-msvideo',
+    webm: 'video/webm',
+    mkv: 'video/x-matroska',
+};
+/**
+ * Normalise a supported {@link UploadFile} into a `Blob` plus a resolved file name and
+ * content type, so uploads use the cross-platform global `FormData`/`Blob` body that
+ * `undici` and browsers both accept natively.
+ */
+function toBlob(file, fileName, contentType) {
+    if (file instanceof Blob) {
+        // Duck-type the name rather than `instanceof File`: `File` isn't a global in
+        // Node 18, so a `node:buffer` `File` (which carries a real `name`) would
+        // otherwise fall back to `'upload'` and lose its inferred file name.
+        const blobName = file.name;
+        const name = fileName || (typeof blobName === 'string' ? blobName : undefined) || 'upload';
+        const type = contentType || file.type || getContentTypeFromFileName(name);
+        // Re-wrap only when stamping a type the Blob doesn't already carry.
+        const blob = file.type === type ? file : new Blob([file], { type });
+        return { blob, fileName: name, contentType: type };
+    }
+    if (file instanceof Uint8Array) {
+        if (!fileName) {
+            throw new Error('fileName is required when uploading raw bytes');
+        }
+        const type = contentType || getContentTypeFromFileName(fileName);
+        // `Blob` accepts any `ArrayBufferView`; the cast satisfies the stricter lib
+        // `BlobPart` type (which pins the backing buffer to `ArrayBuffer`).
+        return { blob: new Blob([file], { type }), fileName, contentType: type };
+    }
+    throw new Error('Unsupported file type for upload: expected a Blob or Uint8Array');
+}
+/**
+ * Upload a file using `multipart/form-data`.
+ *
+ * Builds the request body with the global `FormData`/`Blob` so it works unchanged in the
+ * browser and in Node.js (via `undici`). The `file` part is sent alongside `file_name`,
+ * `file_size`, and `underlying_type` fields (the canonical Comms upload shape); any
+ * `additionalFields` are merged in and override the derived values. Authentication uses
+ * `Authorization: Bearer`, matching every other Comms SDK client, and `Content-Type` is
+ * intentionally left unset so the runtime adds the correct multipart boundary.
+ *
+ * The response is JSON-parsed and camel-cased by {@link fetchWithRetry}; callers validate
+ * the returned shape with the appropriate schema.
+ */
+export async function uploadMultipartFile(args) {
+    const { baseUrl, authToken, endpoint, file, fileName, contentType, additionalFields, maxRetries = 0, requestId, customFetch, } = args;
+    const { blob, fileName: resolvedFileName, contentType: resolvedType, } = toBlob(file, fileName, contentType);
+    const fields = {
+        file_name: resolvedFileName,
+        file_size: blob.size,
+        underlying_type: resolvedType,
+        ...additionalFields,
+    };
+    const form = new FormData();
+    form.append('file', blob, resolvedFileName);
+    for (const [key, value] of Object.entries(fields)) {
+        if (value !== undefined && value !== null) {
+            form.append(key, String(value));
+        }
+    }
+    const headers = {
+        Authorization: `Bearer ${authToken}`,
+    };
+    if (requestId) {
+        headers['X-Request-Id'] = requestId;
+    }
+    const url = new URL(endpoint, baseUrl).toString();
+    const response = await fetchWithRetry(url, {
+        method: 'POST',
+        headers,
+        body: form,
+        // Don't set Content-Type — the runtime adds the multipart boundary.
+        timeout: 30000,
+    }, maxRetries, customFetch);
+    return response.data;
+}

package/dist/types/clients/attachments-client.d.ts

@@ -0,0 +1,39 @@
+import { type Attachment } from '../types/entities.js';
+import type { UploadAttachmentArgs } from '../types/requests.js';
+import { BaseClient } from './base-client.js';
+/**
+ * Client for uploading file attachments to Comms.
+ *
+ * Attachments are uploaded independently, then referenced by passing the returned
+ * {@link Attachment} into the `attachments` array of `comments.createComment`,
+ * `conversationMessages.createMessage`, and similar calls.
+ */
+export declare class AttachmentsClient extends BaseClient {
+    /**
+     * Uploads a file and returns the created {@link Attachment}.
+     *
+     * Mirrors the canonical multipart upload: `POST /attachments/upload` with the `file`
+     * binary plus `file_name`, `file_size`, `attachment_id`, and `underlying_type` form
+     * fields.
+     *
+     * @param args - The file to upload and optional metadata.
+     * @returns The created attachment, ready to attach to a comment or message.
+     *
+     * @example
+     * ```typescript
+     * import { readFile } from 'node:fs/promises'
+     *
+     * const attachment = await api.attachments.upload({
+     *   file: await readFile('./diagram.png'),
+     *   fileName: 'diagram.png',
+     * })
+     *
+     * await api.comments.createComment({
+     *   threadId: '7YpL3oZ4kZ9vP7Q1tR2sX3z',
+     *   content: 'See attached',
+     *   attachments: [attachment],
+     * })
+     * ```
+     */
+    upload(args: UploadAttachmentArgs): Promise<Attachment>;
+}

package/dist/types/clients/threads-client.d.ts

@@ -336,6 +336,7 @@ export declare class ThreadsClient extends BaseClient {
      * @param args.content - The thread content.
      * @param args.recipients - Optional array of user IDs to notify.
      * @param args.groups - Optional array of custom group IDs to notify.
+     * @param args.attachments - Optional array of {@link Attachment}s (from `attachments.upload`).
      * @returns The created thread object.
      *
      * @example

package/dist/types/comms-api.d.ts

@@ -1,3 +1,4 @@
+import { AttachmentsClient } from './clients/attachments-client.js';
 import { ChannelsClient } from './clients/channels-client.js';
 import { CommentsClient } from './clients/comments-client.js';
 import { ConversationMessagesClient } from './clients/conversation-messages-client.js';
@@ -44,6 +45,7 @@ export declare class CommsApi {
     inbox: InboxClient;
     reactions: ReactionsClient;
     search: SearchClient;
+    attachments: AttachmentsClient;
     /**
      * Creates a new Comms API client.
      *

package/dist/types/consts/endpoints.d.ts

@@ -22,3 +22,4 @@ export declare const ENDPOINT_INBOX = "inbox";
 export declare const ENDPOINT_REACTIONS = "reactions";
 export declare const ENDPOINT_SEARCH = "search";
 export declare const ENDPOINT_CONVERSATION_MESSAGES = "conversation_messages";
+export declare const ENDPOINT_ATTACHMENTS = "attachments";

package/dist/types/index.d.ts

@@ -1,4 +1,5 @@
 export * from './authentication.js';
+export { AttachmentsClient } from './clients/attachments-client.js';
 export { ChannelsClient } from './clients/channels-client.js';
 export { CommentsClient } from './clients/comments-client.js';
 export { ConversationMessagesClient } from './clients/conversation-messages-client.js';

package/dist/types/types/entities.d.ts

@@ -30,6 +30,25 @@ export declare const AttachmentSchema: z.ZodObject<{
     videoAutoPlay: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
 }, z.core.$loose>;
 export type Attachment = z.infer<typeof AttachmentSchema>;
+export declare const RequestAttachmentSchema: z.ZodObject<{
+    attachmentId: z.ZodString;
+    urlType: z.ZodString;
+    title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    fileName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    fileSize: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    underlyingType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    image: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    imageWidth: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    imageHeight: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    duration: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    uploadState: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    video: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    videoType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    videoAutoPlay: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+}, z.core.$strip>;
+export type RequestAttachment = z.infer<typeof RequestAttachmentSchema>;
 export declare const BaseUserSchema: z.ZodObject<{
     id: z.ZodNumber;
     fullName: z.ZodString;

package/dist/types/types/requests.d.ts

@@ -40,6 +40,24 @@ export declare const CreateThreadArgsSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     recipients: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodNumber>>>;
     groups: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    attachments: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        attachmentId: z.ZodString;
+        urlType: z.ZodString;
+        title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        fileName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        fileSize: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        underlyingType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        image: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        imageWidth: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        imageHeight: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        duration: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        uploadState: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        video: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        videoType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        videoAutoPlay: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    }, z.core.$strip>>>>;
 }, z.core.$strip>;
 export type CreateThreadArgs = z.infer<typeof CreateThreadArgsSchema>;
 export declare const UpdateThreadArgsSchema: z.ZodObject<{
@@ -69,7 +87,7 @@ export declare const CreateCommentArgsSchema: z.ZodObject<{
         video: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         videoType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         videoAutoPlay: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
-    }, z.core.$loose>>>>;
+    }, z.core.$strip>>>>;
     actions: z.ZodOptional<z.ZodNullable<z.ZodUnknown>>;
     recipients: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodNumber>>>;
     groups: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
@@ -115,7 +133,7 @@ export declare const CreateMessageArgsSchema: z.ZodObject<{
         video: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         videoType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         videoAutoPlay: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
-    }, z.core.$loose>>>>;
+    }, z.core.$strip>>>>;
 }, z.core.$strip>;
 export type CreateMessageArgs = z.infer<typeof CreateMessageArgsSchema>;
 export declare const GetChannelsArgsSchema: z.ZodObject<{
@@ -368,4 +386,26 @@ export type GetUserLocalTimeArgs = {
     workspaceId: number;
     userId: number;
 };
+type UploadAttachmentCommonArgs = {
+    /** MIME type. Defaults to the `Blob`'s type or one inferred from the file extension. */
+    contentType?: string;
+    /** Attachment ID to use. A random ID is generated when omitted. */
+    attachmentId?: string;
+};
+/**
+ * Arguments for `attachments.upload`. A discriminated union on `file` enforces, at
+ * compile time, that raw `Uint8Array` bytes are accompanied by a `fileName` (there is
+ * no name to infer), while a `Blob`/`File` may omit it.
+ */
+export type UploadAttachmentArgs = UploadAttachmentCommonArgs & ({
+    /** The file to upload — a `Blob`/`File` (browser, or any runtime with a global `Blob`). */
+    file: Blob;
+    /** File name. Inferred from the `File.name` when omitted. */
+    fileName?: string;
+} | {
+    /** Raw bytes to upload. A Node `Buffer` is a `Uint8Array`, so `await readFile(path)` works directly. */
+    file: Uint8Array;
+    /** File name. Required for raw bytes — there is no name to infer. */
+    fileName: string;
+});
 export {};

package/dist/types/utils/index.d.ts

@@ -1,3 +1,4 @@
 export * from './case-conversion.js';
+export type { UploadFile } from './multipart-upload.js';
 export * from './url-helpers.js';
 export * from './uuidv7.js';

package/dist/types/utils/multipart-upload.d.ts

@@ -0,0 +1,58 @@
+import type { CustomFetch } from '../types/http.js';
+/**
+ * File content accepted by the upload helpers.
+ *
+ * - `Blob`/`File` — browser, or any runtime with a global `Blob` (Node 18+).
+ * - `Uint8Array` — raw bytes (requires `fileName`). A Node `Buffer` is a `Uint8Array`,
+ *   so reading a file with `fs` and passing the result works without conversion.
+ *
+ * Both are universal types, so the published `.d.ts` stays free of Node-only globals
+ * (`Buffer`, `NodeJS.*`) and the helper pulls in no Node built-ins — keeping the browser
+ * bundle clean.
+ */
+export type UploadFile = Blob | Uint8Array;
+type UploadMultipartFileArgs = {
+    /** Base API URI with trailing slash, e.g. `https://comms.todoist.com/api/v1/`. */
+    baseUrl: string;
+    /** API token used for `Authorization: Bearer`. */
+    authToken: string;
+    /** Relative endpoint path, e.g. `attachments/upload`. */
+    endpoint: string;
+    /** File content to upload. */
+    file: UploadFile;
+    /** File name. Required for raw `Uint8Array` bytes; inferred from a `File`. */
+    fileName?: string;
+    /** MIME type. Defaults to the `Blob`'s type or one inferred from the file extension. */
+    contentType?: string;
+    /** Extra multipart fields to send alongside the file metadata fields. */
+    additionalFields?: Record<string, string | number | boolean | undefined | null>;
+    /**
+     * Network-error retry count. Defaults to `0` — unlike JSON requests, a retry here
+     * resends the entire file body, so large uploads aren't retried automatically.
+     */
+    maxRetries?: number;
+    /** Optional request ID for tracing. */
+    requestId?: string;
+    /** Optional custom fetch implementation. */
+    customFetch?: CustomFetch;
+};
+/**
+ * Determine a content-type from a filename extension. Falls back to
+ * `application/octet-stream` for unknown extensions.
+ */
+export declare function getContentTypeFromFileName(fileName: string): string;
+/**
+ * Upload a file using `multipart/form-data`.
+ *
+ * Builds the request body with the global `FormData`/`Blob` so it works unchanged in the
+ * browser and in Node.js (via `undici`). The `file` part is sent alongside `file_name`,
+ * `file_size`, and `underlying_type` fields (the canonical Comms upload shape); any
+ * `additionalFields` are merged in and override the derived values. Authentication uses
+ * `Authorization: Bearer`, matching every other Comms SDK client, and `Content-Type` is
+ * intentionally left unset so the runtime adds the correct multipart boundary.
+ *
+ * The response is JSON-parsed and camel-cased by {@link fetchWithRetry}; callers validate
+ * the returned shape with the appropriate schema.
+ */
+export declare function uploadMultipartFile<T>(args: UploadMultipartFileArgs): Promise<T>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@doist/comms-sdk",
-    "version": "0.3.0",
+    "version": "0.4.1",
     "description": "A TypeScript wrapper for the Comms REST API.",
     "author": "Doist developers",
     "homepage": "https://doist.github.io/comms-sdk-typescript/",