@doist/todoist-ai 4.13.4 → 4.14.0

package/dist/tools/__tests__/find-activity.test.js

@@ -0,0 +1,229 @@
+import { jest } from '@jest/globals';
+import { extractTextContent } from '../../utils/test-helpers.js';
+import { ToolNames } from '../../utils/tool-names.js';
+import { findActivity } from '../find-activity.js';
+// Mock the Todoist API
+const mockTodoistApi = {
+    getActivityLogs: jest.fn(),
+};
+const { FIND_ACTIVITY } = ToolNames;
+/**
+ * Helper to create a mock activity event
+ */
+function createMockActivityEvent(overrides = {}) {
+    return {
+        id: 'event-123',
+        objectType: 'task',
+        objectId: 'task-456',
+        eventType: 'added',
+        eventDate: '2024-10-23T10:30:00Z',
+        parentProjectId: 'project-789',
+        parentItemId: null,
+        initiatorId: 'user-001',
+        extraData: null,
+        ...overrides,
+    };
+}
+describe(`${FIND_ACTIVITY} tool`, () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+    describe('basic functionality', () => {
+        it('should retrieve activity events with default parameters', async () => {
+            const mockEvents = [
+                createMockActivityEvent({
+                    id: 'event-1',
+                    eventType: 'added',
+                    eventDate: '2024-10-23T10:00:00Z',
+                }),
+                createMockActivityEvent({
+                    id: 'event-2',
+                    eventType: 'completed',
+                    eventDate: '2024-10-23T11:00:00Z',
+                }),
+            ];
+            mockTodoistApi.getActivityLogs.mockResolvedValue({
+                results: mockEvents,
+                nextCursor: null,
+            });
+            const result = await findActivity.execute({ limit: 20 }, mockTodoistApi);
+            expect(mockTodoistApi.getActivityLogs).toHaveBeenCalledWith({
+                limit: 20,
+                cursor: null,
+            });
+            expect(extractTextContent(result)).toMatchSnapshot();
+        });
+        it('should handle empty results', async () => {
+            mockTodoistApi.getActivityLogs.mockResolvedValue({
+                results: [],
+                nextCursor: null,
+            });
+            const result = await findActivity.execute({ limit: 20 }, mockTodoistApi);
+            expect(extractTextContent(result)).toMatchSnapshot();
+        });
+        it('should handle pagination with cursor', async () => {
+            const mockEvents = Array.from({ length: 20 }, (_, i) => createMockActivityEvent({
+                id: `event-${i}`,
+                objectId: `task-${i}`,
+            }));
+            mockTodoistApi.getActivityLogs.mockResolvedValue({
+                results: mockEvents,
+                nextCursor: 'next-page-cursor',
+            });
+            const result = await findActivity.execute({ limit: 20, cursor: 'current-cursor' }, mockTodoistApi);
+            expect(mockTodoistApi.getActivityLogs).toHaveBeenCalledWith({
+                limit: 20,
+                cursor: 'current-cursor',
+            });
+            expect(extractTextContent(result)).toContain('Pass cursor');
+            expect(extractTextContent(result)).toContain('next-page-cursor');
+        });
+    });
+    describe('filtering', () => {
+        it.each([
+            ['task', 'added'],
+            ['project', 'updated'],
+            ['comment', 'deleted'],
+        ])('should filter by object type: %s', async (objectType, eventType) => {
+            const mockEvents = [
+                createMockActivityEvent({
+                    objectType: objectType,
+                    eventType: eventType,
+                }),
+            ];
+            mockTodoistApi.getActivityLogs.mockResolvedValue({
+                results: mockEvents,
+                nextCursor: null,
+            });
+            const result = await findActivity.execute({ objectType: objectType, limit: 20 }, mockTodoistApi);
+            expect(mockTodoistApi.getActivityLogs).toHaveBeenCalledWith({
+                objectType,
+                limit: 20,
+                cursor: null,
+            });
+            expect(extractTextContent(result)).toContain(objectType);
+        });
+        it.each([
+            ['added', 'task-1'],
+            ['completed', 'task-2'],
+            ['updated', 'task-3'],
+            ['deleted', 'task-4'],
+        ])('should filter by event type: %s', async (eventType, objectId) => {
+            const mockEvents = [
+                createMockActivityEvent({
+                    eventType: eventType,
+                    objectId,
+                }),
+            ];
+            mockTodoistApi.getActivityLogs.mockResolvedValue({
+                results: mockEvents,
+                nextCursor: null,
+            });
+            const result = await findActivity.execute({
+                eventType: eventType,
+                limit: 20,
+            }, mockTodoistApi);
+            expect(mockTodoistApi.getActivityLogs).toHaveBeenCalledWith({
+                eventType,
+                limit: 20,
+                cursor: null,
+            });
+            expect(extractTextContent(result)).toContain(eventType);
+        });
+        it.each([
+            ['objectId', 'task-123', { objectId: 'task-123' }],
+            ['projectId', 'project-abc', { parentProjectId: 'project-abc' }],
+            ['taskId', 'parent-task-789', { parentItemId: 'parent-task-789' }],
+            ['initiatorId', 'user-alice', { initiatorId: 'user-alice' }],
+        ])('should filter by %s', async (filterName, filterId, expectedApiCall) => {
+            const mockEvents = [createMockActivityEvent()];
+            mockTodoistApi.getActivityLogs.mockResolvedValue({
+                results: mockEvents,
+                nextCursor: null,
+            });
+            const args = { limit: 20 };
+            args[filterName] = filterId;
+            await findActivity.execute(args, mockTodoistApi);
+            expect(mockTodoistApi.getActivityLogs).toHaveBeenCalledWith({
+                ...expectedApiCall,
+                limit: 20,
+                cursor: null,
+            });
+        });
+        it('should support multiple filters simultaneously', async () => {
+            const mockEvents = [
+                createMockActivityEvent({
+                    objectType: 'task',
+                    eventType: 'completed',
+                    parentProjectId: 'project-work',
+                    initiatorId: 'user-bob',
+                }),
+            ];
+            mockTodoistApi.getActivityLogs.mockResolvedValue({
+                results: mockEvents,
+                nextCursor: null,
+            });
+            const result = await findActivity.execute({
+                objectType: 'task',
+                eventType: 'completed',
+                projectId: 'project-work',
+                initiatorId: 'user-bob',
+                limit: 50,
+            }, mockTodoistApi);
+            expect(mockTodoistApi.getActivityLogs).toHaveBeenCalledWith({
+                objectType: 'task',
+                eventType: 'completed',
+                parentProjectId: 'project-work',
+                initiatorId: 'user-bob',
+                limit: 50,
+                cursor: null,
+            });
+            expect(extractTextContent(result)).toMatchSnapshot();
+        });
+    });
+    describe('content extraction', () => {
+        it('should extract task content from extraData', async () => {
+            const mockEvents = [
+                createMockActivityEvent({
+                    eventType: 'added',
+                    extraData: { content: 'Buy groceries' },
+                }),
+            ];
+            mockTodoistApi.getActivityLogs.mockResolvedValue({
+                results: mockEvents,
+                nextCursor: null,
+            });
+            const result = await findActivity.execute({ limit: 20 }, mockTodoistApi);
+            expect(extractTextContent(result)).toContain('Buy groceries');
+        });
+        it('should handle system-generated events with no initiator', async () => {
+            const mockEvents = [
+                createMockActivityEvent({
+                    initiatorId: null,
+                    eventType: 'completed',
+                }),
+            ];
+            mockTodoistApi.getActivityLogs.mockResolvedValue({
+                results: mockEvents,
+                nextCursor: null,
+            });
+            const result = await findActivity.execute({ limit: 20 }, mockTodoistApi);
+            expect(extractTextContent(result)).toContain('system');
+        });
+        it('should truncate long content', async () => {
+            const longContent = 'A'.repeat(100);
+            const mockEvents = [
+                createMockActivityEvent({
+                    extraData: { content: longContent },
+                }),
+            ];
+            mockTodoistApi.getActivityLogs.mockResolvedValue({
+                results: mockEvents,
+                nextCursor: null,
+            });
+            const result = await findActivity.execute({ limit: 20 }, mockTodoistApi);
+            expect(extractTextContent(result)).toContain('...');
+            expect(extractTextContent(result)).not.toContain(longContent);
+        });
+    });
+});

package/dist/tools/add-comments.d.ts

@@ -9,19 +9,19 @@ declare const addComments: {
             content: z.ZodString;
         }, "strip", z.ZodTypeAny, {
             content: string;
-            taskId?: string | undefined;
             projectId?: string | undefined;
+            taskId?: string | undefined;
         }, {
             content: string;
-            taskId?: string | undefined;
             projectId?: string | undefined;
+            taskId?: string | undefined;
         }>, "many">;
     };
     execute(args: {
         comments: {
             content: string;
-            taskId?: string | undefined;
             projectId?: string | undefined;
+            taskId?: string | undefined;
         }[];
     }, client: import("@doist/todoist-api-typescript").TodoistApi): Promise<{
         content: {

package/dist/tools/add-projects.d.ts

@@ -10,22 +10,22 @@ declare const addProjects: {
             viewStyle: z.ZodOptional<z.ZodEnum<["list", "board", "calendar"]>>;
         }, "strip", z.ZodTypeAny, {
             name: string;
+            parentId?: string | undefined;
             isFavorite?: boolean | undefined;
             viewStyle?: "list" | "board" | "calendar" | undefined;
-            parentId?: string | undefined;
         }, {
             name: string;
+            parentId?: string | undefined;
             isFavorite?: boolean | undefined;
             viewStyle?: "list" | "board" | "calendar" | undefined;
-            parentId?: string | undefined;
         }>, "many">;
     };
     execute({ projects }: {
         projects: {
             name: string;
+            parentId?: string | undefined;
             isFavorite?: boolean | undefined;
             viewStyle?: "list" | "board" | "calendar" | undefined;
-            parentId?: string | undefined;
         }[];
     }, client: import("@doist/todoist-api-typescript").TodoistApi): Promise<{
         content: {

package/dist/tools/add-sections.d.ts

@@ -7,17 +7,17 @@ declare const addSections: {
             name: z.ZodString;
             projectId: z.ZodString;
         }, "strip", z.ZodTypeAny, {
-            name: string;
             projectId: string;
-        }, {
             name: string;
+        }, {
             projectId: string;
+            name: string;
         }>, "many">;
     };
     execute({ sections }: {
         sections: {
-            name: string;
             projectId: string;
+            name: string;
         }[];
     }, client: import("@doist/todoist-api-typescript").TodoistApi): Promise<{
         content: {

package/dist/tools/add-tasks.d.ts

@@ -17,24 +17,24 @@ declare const addTasks: {
             responsibleUser: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
             content: string;
-            description?: string | undefined;
-            parentId?: string | undefined;
             projectId?: string | undefined;
             sectionId?: string | undefined;
+            parentId?: string | undefined;
             labels?: string[] | undefined;
             duration?: string | undefined;
             priority?: "p1" | "p2" | "p3" | "p4" | undefined;
+            description?: string | undefined;
             dueString?: string | undefined;
             responsibleUser?: string | undefined;
         }, {
             content: string;
-            description?: string | undefined;
-            parentId?: string | undefined;
             projectId?: string | undefined;
             sectionId?: string | undefined;
+            parentId?: string | undefined;
             labels?: string[] | undefined;
             duration?: string | undefined;
             priority?: "p1" | "p2" | "p3" | "p4" | undefined;
+            description?: string | undefined;
             dueString?: string | undefined;
             responsibleUser?: string | undefined;
         }>, "many">;
@@ -42,13 +42,13 @@ declare const addTasks: {
     execute({ tasks }: {
         tasks: {
             content: string;
-            description?: string | undefined;
-            parentId?: string | undefined;
             projectId?: string | undefined;
             sectionId?: string | undefined;
+            parentId?: string | undefined;
             labels?: string[] | undefined;
             duration?: string | undefined;
             priority?: "p1" | "p2" | "p3" | "p4" | undefined;
+            description?: string | undefined;
             dueString?: string | undefined;
             responsibleUser?: string | undefined;
         }[];

package/dist/tools/delete-object.d.ts

@@ -8,7 +8,7 @@ declare const deleteObject: {
     };
     execute(args: {
         id: string;
-        type: "task" | "comment" | "project" | "section";
+        type: "task" | "project" | "comment" | "section";
     }, client: import("@doist/todoist-api-typescript").TodoistApi): Promise<{
         content: {
             type: "text";
@@ -16,7 +16,7 @@ declare const deleteObject: {
         }[];
         structuredContent: {
             deletedEntity: {
-                type: "task" | "comment" | "project" | "section";
+                type: "task" | "project" | "comment" | "section";
                 id: string;
             };
             success: boolean;

package/dist/tools/find-activity.d.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+declare const findActivity: {
+    name: "find-activity";
+    description: string;
+    parameters: {
+        objectType: z.ZodOptional<z.ZodEnum<["task", "project", "comment"]>>;
+        objectId: z.ZodOptional<z.ZodString>;
+        eventType: z.ZodOptional<z.ZodEnum<["added", "updated", "deleted", "completed", "uncompleted", "archived", "unarchived", "shared", "left"]>>;
+        projectId: z.ZodOptional<z.ZodString>;
+        taskId: z.ZodOptional<z.ZodString>;
+        initiatorId: z.ZodOptional<z.ZodString>;
+        limit: z.ZodDefault<z.ZodNumber>;
+        cursor: z.ZodOptional<z.ZodString>;
+    };
+    execute(args: {
+        limit: number;
+        projectId?: string | undefined;
+        objectType?: "task" | "project" | "comment" | undefined;
+        objectId?: string | undefined;
+        eventType?: "added" | "updated" | "deleted" | "completed" | "uncompleted" | "archived" | "unarchived" | "shared" | "left" | undefined;
+        initiatorId?: string | undefined;
+        cursor?: string | undefined;
+        taskId?: string | undefined;
+    }, client: import("@doist/todoist-api-typescript").TodoistApi): Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        structuredContent: {
+            events: {
+                id: string | null;
+                objectType: string;
+                objectId: string;
+                eventType: string;
+                eventDate: string;
+                parentProjectId: string | null;
+                parentItemId: string | null;
+                initiatorId: string | null;
+                extraData: Record<string, any> | null;
+            }[];
+            nextCursor: string | null;
+            totalCount: number;
+            hasMore: boolean;
+            appliedFilters: {
+                limit: number;
+                projectId?: string | undefined;
+                objectType?: "task" | "project" | "comment" | undefined;
+                objectId?: string | undefined;
+                eventType?: "added" | "updated" | "deleted" | "completed" | "uncompleted" | "archived" | "unarchived" | "shared" | "left" | undefined;
+                initiatorId?: string | undefined;
+                cursor?: string | undefined;
+                taskId?: string | undefined;
+            };
+        };
+    } | {
+        content: ({
+            type: "text";
+            text: string;
+            mimeType?: undefined;
+        } | {
+            type: "text";
+            mimeType: string;
+            text: string;
+        })[];
+        structuredContent?: undefined;
+    }>;
+};
+export { findActivity };
+//# sourceMappingURL=find-activity.d.ts.map

package/dist/tools/find-activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-activity.d.ts","sourceRoot":"","sources":["../../src/tools/find-activity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAwDvB,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6CwB,CAAA;AA+J1C,OAAO,EAAE,YAAY,EAAE,CAAA"}

package/dist/tools/find-activity.js

@@ -0,0 +1,221 @@
+import { z } from 'zod';
+import { getToolOutput } from '../mcp-helpers.js';
+import { mapActivityEvent } from '../tool-helpers.js';
+import { ApiLimits } from '../utils/constants.js';
+import { summarizeList } from '../utils/response-builders.js';
+import { ToolNames } from '../utils/tool-names.js';
+const { FIND_TASKS, USER_INFO } = ToolNames;
+const ArgsSchema = {
+    objectType: z
+        .enum(['task', 'project', 'comment'])
+        .optional()
+        .describe('Type of object to filter by.'),
+    objectId: z
+        .string()
+        .optional()
+        .describe('Filter by specific object ID (task, project, or comment).'),
+    eventType: z
+        .enum([
+        'added',
+        'updated',
+        'deleted',
+        'completed',
+        'uncompleted',
+        'archived',
+        'unarchived',
+        'shared',
+        'left',
+    ])
+        .optional()
+        .describe('Type of event to filter by.'),
+    projectId: z.string().optional().describe('Filter events by parent project ID.'),
+    taskId: z.string().optional().describe('Filter events by parent task ID (for subtask events).'),
+    initiatorId: z.string().optional().describe('Filter by the user ID who initiated the event.'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(ApiLimits.ACTIVITY_MAX)
+        .default(ApiLimits.ACTIVITY_DEFAULT)
+        .describe('Maximum number of activity events to return.'),
+    cursor: z
+        .string()
+        .optional()
+        .describe('Pagination cursor for retrieving the next page of results.'),
+};
+const findActivity = {
+    name: ToolNames.FIND_ACTIVITY,
+    description: 'Retrieve recent activity logs to monitor and audit changes in Todoist. Shows events from all users by default (use initiatorId to filter by specific user). Track task completions, updates, deletions, project changes, and more with flexible filtering. Note: Date-based filtering is not supported by the Todoist API.',
+    parameters: ArgsSchema,
+    async execute(args, client) {
+        const { objectType, objectId, eventType, projectId, taskId, initiatorId, limit, cursor } = args;
+        // Build API arguments
+        const apiArgs = {
+            limit,
+            cursor: cursor ?? null,
+        };
+        // Add optional filters
+        if (objectType)
+            apiArgs.objectType = objectType;
+        if (objectId)
+            apiArgs.objectId = objectId;
+        if (eventType)
+            apiArgs.eventType = eventType;
+        if (projectId)
+            apiArgs.parentProjectId = projectId;
+        if (taskId)
+            apiArgs.parentItemId = taskId;
+        if (initiatorId)
+            apiArgs.initiatorId = initiatorId;
+        // Fetch activity logs from API
+        const { results, nextCursor } = await client.getActivityLogs(apiArgs);
+        const events = results.map(mapActivityEvent);
+        // Generate text content
+        const textContent = generateTextContent({
+            events,
+            args,
+            nextCursor,
+        });
+        return getToolOutput({
+            textContent,
+            structuredContent: {
+                events,
+                nextCursor,
+                totalCount: events.length,
+                hasMore: Boolean(nextCursor),
+                appliedFilters: args,
+            },
+        });
+    },
+};
+function generateTextContent({ events, args, nextCursor, }) {
+    // Generate subject description
+    let subject = 'Activity events';
+    // Build subject based on filters
+    const subjectParts = [];
+    if (args.eventType) {
+        subjectParts.push(`${args.eventType}`);
+    }
+    if (args.objectType) {
+        const objectLabel = args.objectType === 'task' ? 'tasks' : `${args.objectType}s`;
+        subjectParts.push(objectLabel);
+    }
+    if (subjectParts.length > 0) {
+        subject = `Activity: ${subjectParts.join(' ')}`;
+    }
+    // Generate filter hints
+    const filterHints = [];
+    if (args.objectId) {
+        filterHints.push(`object ID: ${args.objectId}`);
+    }
+    if (args.projectId) {
+        filterHints.push(`project: ${args.projectId}`);
+    }
+    if (args.taskId) {
+        filterHints.push(`task: ${args.taskId}`);
+    }
+    if (args.initiatorId) {
+        filterHints.push(`initiator: ${args.initiatorId}`);
+    }
+    // Generate helpful suggestions for empty results
+    const zeroReasonHints = [];
+    if (events.length === 0) {
+        zeroReasonHints.push('No activity events match the specified filters');
+        zeroReasonHints.push('Note: Activity logs only show recent events');
+        if (args.eventType) {
+            zeroReasonHints.push(`Try removing the eventType filter (${args.eventType})`);
+        }
+        if (args.objectType) {
+            zeroReasonHints.push(`Try removing the objectType filter (${args.objectType})`);
+        }
+        if (args.objectId || args.projectId || args.taskId) {
+            zeroReasonHints.push('Verify the object ID is correct');
+        }
+    }
+    // Generate contextual next steps
+    const nextSteps = [];
+    if (events.length > 0) {
+        // Suggest related tools based on what was found
+        const hasTaskEvents = events.some((e) => e.objectType === 'task' || e.objectType === 'item');
+        const hasCompletions = events.some((e) => e.eventType === 'completed');
+        if (hasTaskEvents) {
+            nextSteps.push(`Use ${FIND_TASKS} to view current task details`);
+        }
+        if (hasCompletions) {
+            nextSteps.push('Review completed tasks to track productivity');
+        }
+        if (args.initiatorId) {
+            nextSteps.push(`Use ${USER_INFO} to get details about the user`);
+        }
+        // Suggest narrowing down if too many results
+        if (events.length >= args.limit && !nextCursor) {
+            nextSteps.push('Add more specific filters to narrow down results');
+        }
+    }
+    return summarizeList({
+        subject,
+        count: events.length,
+        limit: args.limit,
+        nextCursor: nextCursor ?? undefined,
+        filterHints,
+        previewLines: previewActivityEvents(events, Math.min(events.length, args.limit)),
+        zeroReasonHints,
+        nextSteps,
+    });
+}
+/**
+ * Formats activity events into readable preview lines
+ */
+function previewActivityEvents(events, limit = 10) {
+    const previewEvents = events.slice(0, limit);
+    const lines = previewEvents.map(formatActivityEventPreview).join('\n');
+    // If we're showing fewer events than the total, add an indicator
+    if (events.length > limit) {
+        const remaining = events.length - limit;
+        return `${lines}\n    ... and ${remaining} more event${remaining === 1 ? '' : 's'}`;
+    }
+    return lines;
+}
+/**
+ * Formats a single activity event into a readable preview line
+ */
+function formatActivityEventPreview(event) {
+    const date = formatEventDate(event.eventDate);
+    const eventLabel = `${event.eventType} ${event.objectType}`;
+    // Extract useful content from extraData if available
+    let contentInfo = '';
+    if (event.extraData) {
+        const content = event.extraData.content || event.extraData.name || event.extraData.last_content;
+        if (content && typeof content === 'string') {
+            // Truncate long content
+            const truncated = content.length > 50 ? `${content.substring(0, 47)}...` : content;
+            contentInfo = ` • "${truncated}"`;
+        }
+    }
+    const objectId = event.objectId ? ` • id=${event.objectId}` : '';
+    const initiator = event.initiatorId ? ` • by=${event.initiatorId}` : ' • system';
+    const projectInfo = event.parentProjectId ? ` • project=${event.parentProjectId}` : '';
+    return `    [${date}] ${eventLabel}${contentInfo}${objectId}${initiator}${projectInfo}`;
+}
+/**
+ * Formats an ISO date string to a more readable format
+ */
+function formatEventDate(isoDate) {
+    try {
+        const date = new Date(isoDate);
+        // Format as: Oct 23, 14:30 (in UTC for deterministic snapshots)
+        const month = date.toLocaleDateString('en-US', { month: 'short', timeZone: 'UTC' });
+        const day = date.toLocaleDateString('en-US', { day: 'numeric', timeZone: 'UTC' });
+        const time = date.toLocaleTimeString('en-US', {
+            hour: '2-digit',
+            minute: '2-digit',
+            hour12: false,
+            timeZone: 'UTC',
+        });
+        return `${month} ${day}, ${time}`;
+    }
+    catch {
+        return isoDate;
+    }
+}
+export { findActivity };

package/dist/tools/find-comments.d.ts

@@ -10,10 +10,10 @@ declare const findComments: {
         limit: z.ZodOptional<z.ZodNumber>;
     };
     execute(args: {
-        limit?: number | undefined;
-        taskId?: string | undefined;
         projectId?: string | undefined;
+        limit?: number | undefined;
         cursor?: string | undefined;
+        taskId?: string | undefined;
         commentId?: string | undefined;
     }, client: import("@doist/todoist-api-typescript").TodoistApi): Promise<{
         content: {