feat: Add workspace folders CRUD endpoints

Add SDK support for the /api/v1/folders REST API endpoints,
enabling consumers to list, get, create, update, and delete
workspace folders.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: scottlovegrove

src/consts/endpoints.ts

@@ -58,6 +58,8 @@ export const ENDPOINT_GET_TOKEN = 'access_token'
 export const ENDPOINT_REVOKE_TOKEN = 'access_tokens/revoke'
 export const ENDPOINT_REVOKE = 'revoke'
 
+export const ENDPOINT_REST_FOLDERS = 'folders'
+
 // Workspace endpoints
 export const ENDPOINT_WORKSPACE_INVITATIONS = 'workspaces/invitations'
 export const ENDPOINT_WORKSPACE_INVITATIONS_ALL = 'workspaces/invitations/all'

src/test-utils/test-defaults.ts

@@ -8,6 +8,7 @@ import {
     Deadline,
     RawComment,
     PersonalProject,
+    Folder,
 } from '../types'
 import { getProjectUrl, getTaskUrl, getSectionUrl } from '../utils/url-helpers'
 
@@ -290,3 +291,12 @@ export const COMMENT_WITH_OPTIONALS_AS_NULL_PROJECT = {
     ...RAW_COMMENT_WITH_OPTIONALS_AS_NULL_PROJECT,
     taskId: undefined,
 }
+
+export const DEFAULT_FOLDER: Folder = {
+    id: '789',
+    name: 'This is a folder',
+    workspaceId: '100',
+    defaultOrder: 3,
+    childOrder: 3,
+    isDeleted: false,
+}

src/todoist-api.folders.test.ts

@@ -0,0 +1,104 @@
+import { TodoistApi } from '.'
+import { DEFAULT_AUTH_TOKEN, DEFAULT_FOLDER } from './test-utils/test-defaults'
+import { getSyncBaseUri, ENDPOINT_REST_FOLDERS } from './consts/endpoints'
+import { server, http, HttpResponse } from './test-utils/msw-setup'
+
+function getTarget() {
+    return new TodoistApi(DEFAULT_AUTH_TOKEN)
+}
+
+describe('TodoistApi folder endpoints', () => {
+    describe('getFolder', () => {
+        test('returns result from rest client', async () => {
+            server.use(
+                http.get(`${getSyncBaseUri()}${ENDPOINT_REST_FOLDERS}/789`, () => {
+                    return HttpResponse.json(DEFAULT_FOLDER, { status: 200 })
+                }),
+            )
+            const api = getTarget()
+
+            const folder = await api.getFolder('789')
+
+            expect(folder).toEqual(DEFAULT_FOLDER)
+        })
+    })
+
+    describe('getFolders', () => {
+        test('returns result from rest client with workspace_id param', async () => {
+            const folders = [DEFAULT_FOLDER]
+            server.use(
+                http.get(`${getSyncBaseUri()}${ENDPOINT_REST_FOLDERS}`, ({ request }) => {
+                    const url = new URL(request.url)
+                    expect(url.searchParams.get('workspace_id')).toBe('100')
+                    return HttpResponse.json(
+                        { results: folders, nextCursor: '123' },
+                        { status: 200 },
+                    )
+                }),
+            )
+            const api = getTarget()
+
+            const { results, nextCursor } = await api.getFolders({ workspaceId: 100 })
+
+            expect(results).toEqual(folders)
+            expect(nextCursor).toBe('123')
+        })
+    })
+
+    describe('addFolder', () => {
+        const DEFAULT_ADD_FOLDER_ARGS = {
+            name: 'This is a folder',
+            workspaceId: 100,
+        }
+
+        test('returns result from rest client', async () => {
+            server.use(
+                http.post(`${getSyncBaseUri()}${ENDPOINT_REST_FOLDERS}`, () => {
+                    return HttpResponse.json(DEFAULT_FOLDER, { status: 200 })
+                }),
+            )
+            const api = getTarget()
+
+            const folder = await api.addFolder(DEFAULT_ADD_FOLDER_ARGS)
+
+            expect(folder).toEqual(DEFAULT_FOLDER)
+        })
+    })
+
+    describe('updateFolder', () => {
+        const DEFAULT_UPDATE_FOLDER_ARGS = { name: 'a new name' }
+
+        test('returns success result from rest client', async () => {
+            const returnedFolder = {
+                ...DEFAULT_FOLDER,
+                ...DEFAULT_UPDATE_FOLDER_ARGS,
+                id: '789',
+            }
+            server.use(
+                http.post(`${getSyncBaseUri()}${ENDPOINT_REST_FOLDERS}/789`, () => {
+                    return HttpResponse.json(returnedFolder, { status: 200 })
+                }),
+            )
+            const api = getTarget()
+
+            const response = await api.updateFolder('789', DEFAULT_UPDATE_FOLDER_ARGS)
+
+            expect(response).toEqual(returnedFolder)
+        })
+    })
+
+    describe('deleteFolder', () => {
+        test('returns success result from rest client', async () => {
+            server.use(
+                http.delete(`${getSyncBaseUri()}${ENDPOINT_REST_FOLDERS}/789`, () => {
+                    return HttpResponse.json(undefined, { status: 204 })
+                }),
+            )
+            const api = getTarget()
+
+            const response = await api.deleteFolder('789')
+
+            expect(response).toEqual(true)
+        })
+    })
+})

src/todoist-api.ts

@@ -13,6 +13,7 @@ import {
     WorkspacePlanDetails,
     JoinWorkspaceResult,
     Workspace,
+    Folder,
 } from './types/entities'
 import {
     AddCommentArgs,
@@ -72,6 +73,10 @@ import {
     WorkspaceLogoResponse,
     MoveProjectToWorkspaceArgs,
     MoveProjectToPersonalArgs,
+    GetFoldersArgs,
+    GetFoldersResponse,
+    AddFolderArgs,
+    UpdateFolderArgs,
 } from './types/requests'
 import { CustomFetch } from './types/http'
 import { request, isSuccess } from './rest-client'
@@ -118,6 +123,7 @@ import {
     ENDPOINT_WORKSPACE_USERS,
     getWorkspaceActiveProjectsEndpoint,
     getWorkspaceArchivedProjectsEndpoint,
+    ENDPOINT_REST_FOLDERS,
 } from './consts/endpoints'
 import {
     validateAttachment,
@@ -141,6 +147,8 @@ import {
     validateWorkspacePlanDetails,
     validateJoinWorkspaceResult,
     validateWorkspaceArray,
+    validateFolder,
+    validateFolderArray,
 } from './utils/validators'
 import { formatDateToYYYYMMDD } from './utils/url-helpers'
 import { uploadMultipartFile } from './utils/multipart-upload'
@@ -1506,6 +1514,115 @@ export class TodoistApi {
         return isSuccess(response)
     }
 
+    /* Folder methods */
+
+    /**
+     * Retrieves a paginated list of folders.
+     *
+     * @param args - Optional filter parameters such as workspace ID.
+     * @returns A promise that resolves to a paginated response of folders.
+     */
+    async getFolders(args?: GetFoldersArgs): Promise<GetFoldersResponse> {
+        const {
+            data: { results, nextCursor },
+        } = await request<GetFoldersResponse>({
+            httpMethod: 'GET',
+            baseUri: this.syncApiBase,
+            relativePath: ENDPOINT_REST_FOLDERS,
+            apiToken: this.authToken,
+            customFetch: this.customFetch,
+            payload: args,
+        })
+
+        return {
+            results: validateFolderArray(results),
+            nextCursor,
+        }
+    }
+
+    /**
+     * Retrieves a single folder by its ID.
+     *
+     * @param id - The unique identifier of the folder.
+     * @returns A promise that resolves to the requested folder.
+     */
+    async getFolder(id: string): Promise<Folder> {
+        z.string().parse(id)
+        const response = await request<Folder>({
+            httpMethod: 'GET',
+            baseUri: this.syncApiBase,
+            relativePath: generatePath(ENDPOINT_REST_FOLDERS, id),
+            apiToken: this.authToken,
+            customFetch: this.customFetch,
+        })
+
+        return validateFolder(response.data)
+    }
+
+    /**
+     * Creates a new folder.
+     *
+     * @param args - Folder creation parameters including name and workspace ID.
+     * @param requestId - Optional custom identifier for the request.
+     * @returns A promise that resolves to the created folder.
+     */
+    async addFolder(args: AddFolderArgs, requestId?: string): Promise<Folder> {
+        const response = await request<Folder>({
+            httpMethod: 'POST',
+            baseUri: this.syncApiBase,
+            relativePath: ENDPOINT_REST_FOLDERS,
+            apiToken: this.authToken,
+            customFetch: this.customFetch,
+            payload: args,
+            requestId: requestId,
+        })
+
+        return validateFolder(response.data)
+    }
+
+    /**
+     * Updates an existing folder by its ID.
+     *
+     * @param id - The unique identifier of the folder to update.
+     * @param args - Update parameters such as name or default order.
+     * @param requestId - Optional custom identifier for the request.
+     * @returns A promise that resolves to the updated folder.
+     */
+    async updateFolder(id: string, args: UpdateFolderArgs, requestId?: string): Promise<Folder> {
+        z.string().parse(id)
+        const response = await request<Folder>({
+            httpMethod: 'POST',
+            baseUri: this.syncApiBase,
+            relativePath: generatePath(ENDPOINT_REST_FOLDERS, id),
+            apiToken: this.authToken,
+            customFetch: this.customFetch,
+            payload: args,
+            requestId: requestId,
+        })
+
+        return validateFolder(response.data)
+    }
+
+    /**
+     * Deletes a folder by its ID.
+     *
+     * @param id - The unique identifier of the folder to delete.
+     * @param requestId - Optional custom identifier for the request.
+     * @returns A promise that resolves to `true` if successful.
+     */
+    async deleteFolder(id: string, requestId?: string): Promise<boolean> {
+        z.string().parse(id)
+        const response = await request({
+            httpMethod: 'DELETE',
+            baseUri: this.syncApiBase,
+            relativePath: generatePath(ENDPOINT_REST_FOLDERS, id),
+            apiToken: this.authToken,
+            customFetch: this.customFetch,
+            requestId: requestId,
+        })
+        return isSuccess(response)
+    }
+
     /* Workspace methods */
 
     /**

src/types/entities.ts

@@ -644,3 +644,14 @@ export const WorkspaceSchema = z.object({
 })
 
 export type Workspace = z.infer<typeof WorkspaceSchema>
+
+export const FolderSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    workspaceId: z.string(),
+    defaultOrder: z.number().int(),
+    childOrder: z.number().int(),
+    isDeleted: z.boolean(),
+})
+
+export type Folder = z.infer<typeof FolderSchema>

src/types/requests.ts

@@ -5,6 +5,7 @@ import type {
     ActivityObjectType,
     Comment,
     Duration,
+    Folder,
     Label,
     PersonalProject,
     ProjectViewStyle,
@@ -769,3 +770,28 @@ export type AllWorkspaceInvitationsResponse = import('./entities').WorkspaceInvi
  * Response type for workspace logo upload.
  */
 export type WorkspaceLogoResponse = Record<string, unknown> | null
+
+// Folder-related types
+
+export type GetFoldersArgs = {
+    workspaceId?: number | null
+    cursor?: string | null
+    limit?: number
+}
+
+export type GetFoldersResponse = {
+    results: Folder[]
+    nextCursor: string | null
+}
+
+export type AddFolderArgs = {
+    name: string
+    workspaceId: number
+    defaultOrder?: number | null
+    childOrder?: number | null
+}
+
+export type UpdateFolderArgs = {
+    name?: string | null
+    defaultOrder?: number | null
+}

src/utils/validators.ts

@@ -6,13 +6,15 @@ import {
     UserSchema,
     CurrentUserSchema,
     TaskSchema,
+    FolderSchema,
     type Attachment,
     type Task,
     type Section,
     type Label,
     type Comment,
     type User,
     type CurrentUser,
+    type Folder,
     type ProductivityStats,
     PersonalProjectSchema,
     WorkspaceProjectSchema,
@@ -165,3 +167,11 @@ export function validateWorkspace(input: unknown): Workspace {
 export function validateWorkspaceArray(input: unknown[]): Workspace[] {
     return input.map(validateWorkspace)
 }
+
+export function validateFolder(input: unknown): Folder {
+    return FolderSchema.parse(input)
+}
+
+export function validateFolderArray(input: unknown[]): Folder[] {
+    return input.map(validateFolder)
+}