feat: Add moveTask method for single task moves (#354)

Co-authored-by: Claude <[email protected]>

Author: scottlovegrove

src/TodoistApi.moveTask.test.ts

@@ -0,0 +1,121 @@
+import { TodoistApi } from '.'
+import { DEFAULT_AUTH_TOKEN, DEFAULT_REQUEST_ID, DEFAULT_TASK } from './testUtils/testDefaults'
+import { getSyncBaseUri, ENDPOINT_REST_TASKS, ENDPOINT_REST_TASK_MOVE } from './consts/endpoints'
+import { setupRestClientMock } from './testUtils/mocks'
+import { getTaskUrl } from './utils/urlHelpers'
+
+function getTarget(baseUrl = 'https://api.todoist.com') {
+    return new TodoistApi(DEFAULT_AUTH_TOKEN, baseUrl)
+}
+
+describe('TodoistApi moveTask', () => {
+    const TASK_ID = '123'
+    const PROJECT_ID = '999'
+    const SECTION_ID = '888'
+    const PARENT_ID = '777'
+
+    describe.each([
+        {
+            description: 'project',
+            args: { projectId: PROJECT_ID },
+            expectedApiArgs: { project_id: PROJECT_ID },
+            expectedTaskProps: { projectId: PROJECT_ID },
+        },
+        {
+            description: 'section',
+            args: { sectionId: SECTION_ID },
+            expectedApiArgs: { section_id: SECTION_ID },
+            expectedTaskProps: { sectionId: SECTION_ID },
+        },
+        {
+            description: 'parent',
+            args: { parentId: PARENT_ID },
+            expectedApiArgs: { parent_id: PARENT_ID },
+            expectedTaskProps: { parentId: PARENT_ID },
+        },
+    ])('moving task to $description', ({ args, expectedApiArgs, expectedTaskProps }) => {
+        test('calls post on restClient with expected parameters', async () => {
+            const movedTask = {
+                ...DEFAULT_TASK,
+                id: TASK_ID,
+                ...expectedTaskProps,
+                url: getTaskUrl(TASK_ID, DEFAULT_TASK.content),
+            }
+            const requestMock = setupRestClientMock(movedTask)
+            const api = getTarget()
+
+            await api.moveTask(TASK_ID, args, DEFAULT_REQUEST_ID)
+
+            expect(requestMock).toHaveBeenCalledTimes(1)
+            expect(requestMock).toHaveBeenCalledWith(
+                'POST',
+                getSyncBaseUri(),
+                `${ENDPOINT_REST_TASKS}/${TASK_ID}/${ENDPOINT_REST_TASK_MOVE}`,
+                DEFAULT_AUTH_TOKEN,
+                expectedApiArgs,
+                DEFAULT_REQUEST_ID,
+            )
+        })
+
+        test('returns moved task', async () => {
+            const movedTask = {
+                ...DEFAULT_TASK,
+                id: TASK_ID,
+                ...expectedTaskProps,
+                url: getTaskUrl(TASK_ID, DEFAULT_TASK.content),
+            }
+            setupRestClientMock(movedTask)
+            const api = getTarget()
+
+            const result = await api.moveTask(TASK_ID, args)
+
+            expect(result).toEqual(movedTask)
+        })
+    })
+
+    test('calls post on restClient with expected parameters against staging', async () => {
+        const movedTask = {
+            ...DEFAULT_TASK,
+            id: TASK_ID,
+            projectId: PROJECT_ID,
+            url: getTaskUrl(TASK_ID, DEFAULT_TASK.content),
+        }
+        const requestMock = setupRestClientMock(movedTask)
+        const api = getTarget('https://staging.todoist.com')
+
+        await api.moveTask(TASK_ID, { projectId: PROJECT_ID }, DEFAULT_REQUEST_ID)
+
+        expect(requestMock).toHaveBeenCalledTimes(1)
+        expect(requestMock).toHaveBeenCalledWith(
+            'POST',
+            getSyncBaseUri('https://staging.todoist.com'),
+            `${ENDPOINT_REST_TASKS}/${TASK_ID}/${ENDPOINT_REST_TASK_MOVE}`,
+            DEFAULT_AUTH_TOKEN,
+            { project_id: PROJECT_ID },
+            DEFAULT_REQUEST_ID,
+        )
+    })
+
+    test('works without requestId', async () => {
+        const movedTask = {
+            ...DEFAULT_TASK,
+            id: TASK_ID,
+            projectId: PROJECT_ID,
+            url: getTaskUrl(TASK_ID, DEFAULT_TASK.content),
+        }
+        const requestMock = setupRestClientMock(movedTask)
+        const api = getTarget()
+
+        await api.moveTask(TASK_ID, { projectId: PROJECT_ID })
+
+        expect(requestMock).toHaveBeenCalledTimes(1)
+        expect(requestMock).toHaveBeenCalledWith(
+            'POST',
+            getSyncBaseUri(),
+            `${ENDPOINT_REST_TASKS}/${TASK_ID}/${ENDPOINT_REST_TASK_MOVE}`,
+            DEFAULT_AUTH_TOKEN,
+            { project_id: PROJECT_ID },
+            undefined,
+        )
+    })
+})

src/TodoistApi.ts

@@ -60,6 +60,7 @@ import {
     ENDPOINT_SYNC_QUICK_ADD,
     ENDPOINT_REST_TASK_CLOSE,
     ENDPOINT_REST_TASK_REOPEN,
+    ENDPOINT_REST_TASK_MOVE,
     ENDPOINT_REST_LABELS,
     ENDPOINT_REST_PROJECT_COLLABORATORS,
     ENDPOINT_REST_SECTIONS,
@@ -369,6 +370,7 @@ export class TodoistApi {
      * @param args - The paramets that should contain only one of projectId, sectionId, or parentId
      * @param requestId - Optional custom identifier for the request.
      * @returns - A promise that resolves to an array of the updated tasks.
+     * @deprecated Use `moveTask` for single task operations. This method uses the Sync API and may be removed in a future version.
      */
     async moveTasks(ids: string[], args: MoveTaskArgs, requestId?: string): Promise<Task[]> {
         if (ids.length > MAX_COMMAND_COUNT) {
@@ -420,6 +422,32 @@ export class TodoistApi {
         return validateTaskArray(syncTasks)
     }
 
+    /**
+     * Moves a task by its ID to either a different parent/section/project.
+     *
+     * @param id - The unique identifier of the task to be moved.
+     * @param args - The parameters that should contain exactly one of projectId, sectionId, or parentId
+     * @param requestId - Optional custom identifier for the request.
+     * @returns A promise that resolves to the updated task.
+     */
+    async moveTask(id: string, args: MoveTaskArgs, requestId?: string): Promise<Task> {
+        z.string().parse(id)
+        const response = await request<Task>(
+            'POST',
+            this.syncApiBase,
+            generatePath(ENDPOINT_REST_TASKS, id, ENDPOINT_REST_TASK_MOVE),
+            this.authToken,
+            {
+                ...(args.projectId && { project_id: args.projectId }),
+                ...(args.sectionId && { section_id: args.sectionId }),
+                ...(args.parentId && { parent_id: args.parentId }),
+            },
+            requestId,
+        )
+
+        return validateTask(response.data)
+    }
+
     /**
      * Closes (completes) a task by its ID.
      *

src/consts/endpoints.ts

@@ -32,6 +32,7 @@ export const ENDPOINT_REST_LABELS_SHARED_REMOVE = ENDPOINT_REST_LABELS_SHARED +
 export const ENDPOINT_REST_COMMENTS = 'comments'
 export const ENDPOINT_REST_TASK_CLOSE = 'close'
 export const ENDPOINT_REST_TASK_REOPEN = 'reopen'
+export const ENDPOINT_REST_TASK_MOVE = 'move'
 export const ENDPOINT_REST_PROJECTS = 'projects'
 export const ENDPOINT_REST_PROJECTS_ARCHIVED = ENDPOINT_REST_PROJECTS + '/archived'
 export const ENDPOINT_REST_PROJECT_COLLABORATORS = 'collaborators'