@doist/comms-sdk 0.3.0 → 0.4.0

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/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/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/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/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/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/requests.d.ts

@@ -368,4 +368,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.0",
     "description": "A TypeScript wrapper for the Comms REST API.",
     "author": "Doist developers",
     "homepage": "https://doist.github.io/comms-sdk-typescript/",