feat(attachments): add client for uploading file attachments

Add an `attachments` client exposing `api.attachments.upload(...)`, which
uploads a file via `POST /attachments/upload` (multipart/form-data) and
returns a validated `Attachment` ready to pass into the `attachments` array
of `comments.createComment`, `conversationMessages.createMessage`, etc.

The upload accepts a `Blob`/`File` or a `Uint8Array` of raw bytes, and
normalises each to a `Blob` so the request body works unchanged in the
browser and in Node via the global `FormData`. A Node `Buffer` is a
`Uint8Array`, so `await readFile(path)` works directly. The `file` part is
sent alongside the canonical `file_name`, `file_size`, `attachment_id`, and
`underlying_type` fields. The `attachment_id` is minted via the SDK's
base58 uuidv7 `resolveCreateId`, matching every other create call, and is
caller-overridable.

Ported from Doist/twist-sdk-typescript#141.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: scottlovegrove

src/clients/attachments-client.test.ts

@@ -0,0 +1,135 @@
+import { HttpResponse, http } from 'msw'
+import { apiUrl } from '../testUtils/msw-handlers'
+import { server } from '../testUtils/msw-setup'
+import { TEST_API_TOKEN } from '../testUtils/test-defaults'
+import { generateId, isValidUuidV7Base58 } from '../utils/uuidv7'
+import { AttachmentsClient } from './attachments-client'
+
+const UPLOAD_URL = apiUrl('api/v1/attachments/upload')
+
+const mockAttachmentResponse = {
+    attachment_id: 'abc-123',
+    url_type: 'file',
+    file_name: 'diagram.png',
+    file_size: 11,
+    underlying_type: 'image/png',
+    url: 'https://comms.todoist.com/attachments/abc-123/diagram.png',
+    upload_state: 'uploaded',
+}
+
+describe('AttachmentsClient', () => {
+    let client: AttachmentsClient
+
+    beforeEach(() => {
+        client = new AttachmentsClient({ apiToken: TEST_API_TOKEN })
+    })
+
+    describe('upload', () => {
+        it('uploads a Buffer with the canonical multipart fields', async () => {
+            let capturedForm: FormData | undefined
+            let capturedAuth: string | null = null
+            let capturedContentType: string | null = null
+
+            server.use(
+                http.post(UPLOAD_URL, async ({ request }) => {
+                    capturedAuth = request.headers.get('Authorization')
+                    capturedContentType = request.headers.get('Content-Type')
+                    capturedForm = await request.formData()
+                    return HttpResponse.json(mockAttachmentResponse)
+                }),
+            )
+
+            const result = await client.upload({
+                file: Buffer.from('hello world'),
+                fileName: 'diagram.png',
+            })
+
+            expect(capturedAuth).toBe(`Bearer ${TEST_API_TOKEN}`)
+            // multipart boundary content-type, never application/json
+            expect(capturedContentType).toContain('multipart/form-data')
+
+            const file = capturedForm?.get('file')
+            expect(file).toBeInstanceOf(Blob)
+            expect(capturedForm?.get('file_name')).toBe('diagram.png')
+            expect(capturedForm?.get('file_size')).toBe('11')
+            expect(capturedForm?.get('underlying_type')).toBe('image/png')
+            // A valid ID is generated when none is supplied.
+            const attachmentId = capturedForm?.get('attachment_id')
+            expect(isValidUuidV7Base58(attachmentId)).toBe(true)
+
+            // Response is camel-cased and validated.
+            expect(result.attachmentId).toBe('abc-123')
+            expect(result.fileName).toBe('diagram.png')
+            expect(result.url).toBe('https://comms.todoist.com/attachments/abc-123/diagram.png')
+        })
+
+        it('uses a caller-supplied attachmentId', async () => {
+            let capturedForm: FormData | undefined
+            const callerId = generateId()
+
+            server.use(
+                http.post(UPLOAD_URL, async ({ request }) => {
+                    capturedForm = await request.formData()
+                    return HttpResponse.json({
+                        ...mockAttachmentResponse,
+                        attachment_id: callerId,
+                    })
+                }),
+            )
+
+            const result = await client.upload({
+                file: Buffer.from('data'),
+                fileName: 'notes.txt',
+                attachmentId: callerId,
+            })
+
+            expect(capturedForm?.get('attachment_id')).toBe(callerId)
+            expect(result.attachmentId).toBe(callerId)
+        })
+
+        it('uploads a Blob and infers the file name and type', async () => {
+            let capturedForm: FormData | undefined
+
+            server.use(
+                http.post(UPLOAD_URL, async ({ request }) => {
+                    capturedForm = await request.formData()
+                    return HttpResponse.json(mockAttachmentResponse)
+                }),
+            )
+
+            const blob = new File([new Uint8Array([1, 2, 3, 4])], 'photo.jpg', {
+                type: 'image/jpeg',
+            })
+
+            await client.upload({ file: blob })
+
+            expect(capturedForm?.get('file_name')).toBe('photo.jpg')
+            expect(capturedForm?.get('file_size')).toBe('4')
+            expect(capturedForm?.get('underlying_type')).toBe('image/jpeg')
+        })
+
+        it('uploads a Uint8Array', async () => {
+            let capturedForm: FormData | undefined
+
+            server.use(
+                http.post(UPLOAD_URL, async ({ request }) => {
+                    capturedForm = await request.formData()
+                    return HttpResponse.json(mockAttachmentResponse)
+                }),
+            )
+
+            await client.upload({ file: new Uint8Array([1, 2, 3]), fileName: 'bytes.bin' })
+
+            expect(capturedForm?.get('file')).toBeInstanceOf(Blob)
+            expect(capturedForm?.get('file_name')).toBe('bytes.bin')
+            expect(capturedForm?.get('file_size')).toBe('3')
+            expect(capturedForm?.get('underlying_type')).toBe('application/octet-stream')
+        })
+
+        it('throws when uploading raw bytes without a fileName', async () => {
+            await expect(client.upload({ file: Buffer.from('x') })).rejects.toThrow(
+                'fileName is required when uploading raw bytes',
+            )
+        })
+    })
+})

src/clients/attachments-client.ts

@@ -0,0 +1,58 @@
+import { ENDPOINT_ATTACHMENTS } from '../consts/endpoints'
+import { type Attachment, AttachmentSchema } from '../types/entities'
+import type { UploadAttachmentArgs } from '../types/requests'
+import { uploadMultipartFile } from '../utils/multipart-upload'
+import { resolveCreateId } from '../utils/uuidv7'
+import { BaseClient } from './base-client'
+
+/**
+ * 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: UploadAttachmentArgs): Promise<Attachment> {
+        const data = await uploadMultipartFile<unknown>({
+            baseUrl: this.getBaseUri(),
+            authToken: this.apiToken,
+            endpoint: `${ENDPOINT_ATTACHMENTS}/upload`,
+            file: args.file,
+            fileName: args.fileName,
+            contentType: args.contentType,
+            additionalFields: {
+                attachment_id: resolveCreateId(args.attachmentId),
+            },
+            customFetch: this.customFetch,
+        })
+
+        return AttachmentSchema.parse(data)
+    }
+}

src/comms-api.test.ts

@@ -17,6 +17,7 @@ describe('CommsApi', () => {
         expect(api.inbox).toBeDefined()
         expect(api.reactions).toBeDefined()
         expect(api.search).toBeDefined()
+        expect(api.attachments).toBeDefined()
     })
 
     it('accepts a custom base URL', () => {

src/comms-api.ts

@@ -1,3 +1,4 @@
+import { AttachmentsClient } from './clients/attachments-client'
 import { ChannelsClient } from './clients/channels-client'
 import { CommentsClient } from './clients/comments-client'
 import { ConversationMessagesClient } from './clients/conversation-messages-client'
@@ -47,6 +48,7 @@ export class CommsApi {
     public inbox: InboxClient
     public reactions: ReactionsClient
     public search: SearchClient
+    public attachments: AttachmentsClient
 
     /**
      * Creates a new Comms API client.
@@ -74,6 +76,7 @@ export class CommsApi {
         this.inbox = new InboxClient(clientConfig)
         this.reactions = new ReactionsClient(clientConfig)
         this.search = new SearchClient(clientConfig)
+        this.attachments = new AttachmentsClient(clientConfig)
     }
 
     /**

src/consts/endpoints.ts

@@ -33,3 +33,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'

src/index.ts

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

src/types/requests.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import type { UploadFile } from '../utils/multipart-upload'
 import { type Attachment, AttachmentSchema } from './entities'
 import { NOTIFY_AUDIENCES } from './enums'
 
@@ -422,3 +423,21 @@ export type GetUserLocalTimeArgs = {
     workspaceId: number
     userId: number
 }
+
+// Attachments
+export type UploadAttachmentArgs = {
+    /**
+     * The file to upload. Accepts a `Blob`/`File` (browser) or a `Uint8Array` of raw
+     * bytes. A Node `Buffer` is a `Uint8Array`, so `await readFile(path)` works directly.
+     */
+    file: UploadFile
+    /**
+     * File name. Required when `file` is a `Uint8Array`; inferred from the `File.name`
+     * otherwise.
+     */
+    fileName?: string
+    /** 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
+}