@doist/todoist-ai 4.16.0 → 4.17.0

package/dist/tools/find-tasks-by-date.js

@@ -1,198 +0,0 @@
-import { addDays, formatISO } from 'date-fns';
-import { z } from 'zod';
-import { appendToQuery, buildResponsibleUserQueryFilter, RESPONSIBLE_USER_FILTERING, resolveResponsibleUser, } from '../filter-helpers.js';
-import { getToolOutput } from '../mcp-helpers.js';
-import { getTasksByFilter } from '../tool-helpers.js';
-import { ApiLimits } from '../utils/constants.js';
-import { generateLabelsFilter, LabelsSchema } from '../utils/labels.js';
-import { generateTaskNextSteps, getDateString, previewTasks, summarizeList, } from '../utils/response-builders.js';
-import { ToolNames } from '../utils/tool-names.js';
-const ArgsSchema = {
-    startDate: z
-        .string()
-        .regex(/^(\d{4}-\d{2}-\d{2}|today)$/)
-        .optional()
-        .describe("The start date to get the tasks for. Format: YYYY-MM-DD or 'today'."),
-    overdueOption: z
-        .enum(['overdue-only', 'include-overdue', 'exclude-overdue'])
-        .optional()
-        .describe("How to handle overdue tasks. 'overdue-only' to get only overdue tasks, 'include-overdue' to include overdue tasks along with tasks for the specified date(s), and 'exclude-overdue' to exclude overdue tasks. Default is 'include-overdue'."),
-    daysCount: z
-        .number()
-        .int()
-        .min(1)
-        .max(30)
-        .default(1)
-        .describe('The number of days to get the tasks for, starting from the start date. Default is 1 which means only tasks for the start date.'),
-    limit: z
-        .number()
-        .int()
-        .min(1)
-        .max(ApiLimits.TASKS_MAX)
-        .default(ApiLimits.TASKS_DEFAULT)
-        .describe('The maximum number of tasks to return.'),
-    cursor: z
-        .string()
-        .optional()
-        .describe('The cursor to get the next page of tasks (cursor is obtained from the previous call to this tool, with the same parameters).'),
-    responsibleUser: z
-        .string()
-        .optional()
-        .describe('Find tasks assigned to this user. Can be a user ID, name, or email address.'),
-    responsibleUserFiltering: z
-        .enum(RESPONSIBLE_USER_FILTERING)
-        .optional()
-        .describe('How to filter by responsible user when responsibleUser is not provided. "assigned" = only tasks assigned to others; "unassignedOrMe" = only unassigned tasks or tasks assigned to me; "all" = all tasks regardless of assignment. Default is "unassignedOrMe".'),
-    ...LabelsSchema,
-};
-const findTasksByDate = {
-    name: ToolNames.FIND_TASKS_BY_DATE,
-    description: "Get tasks by date range. Use startDate 'today' to get today's tasks including overdue items, or provide a specific date/date range.",
-    parameters: ArgsSchema,
-    async execute(args, client) {
-        if (!args.startDate && args.overdueOption !== 'overdue-only') {
-            throw new Error('Either startDate must be provided or overdueOption must be set to overdue-only');
-        }
-        // Resolve assignee name to user ID if provided
-        const resolved = await resolveResponsibleUser(client, args.responsibleUser);
-        const resolvedAssigneeId = resolved?.userId;
-        const assigneeEmail = resolved?.email;
-        let query = '';
-        if (args.overdueOption === 'overdue-only') {
-            query = 'overdue';
-        }
-        else if (args.startDate === 'today') {
-            // For 'today', include overdue unless explicitly excluded
-            // Use parentheses to ensure correct operator precedence when combining with other filters
-            query = args.overdueOption === 'exclude-overdue' ? 'today' : '(today | overdue)';
-        }
-        else if (args.startDate) {
-            // For specific dates, never include overdue tasks
-            const startDate = args.startDate;
-            const endDate = addDays(startDate, args.daysCount);
-            const endDateStr = formatISO(endDate, { representation: 'date' });
-            query = `(due after: ${startDate} | due: ${startDate}) & due before: ${endDateStr}`;
-        }
-        // Add labels filter
-        const labelsFilter = generateLabelsFilter(args.labels, args.labelsOperator);
-        if (labelsFilter.length > 0) {
-            query = appendToQuery(query, `(${labelsFilter})`);
-        }
-        // Add responsible user filtering to the query (backend filtering)
-        const responsibleUserFilter = buildResponsibleUserQueryFilter({
-            resolvedAssigneeId,
-            assigneeEmail,
-            responsibleUserFiltering: args.responsibleUserFiltering,
-        });
-        query = appendToQuery(query, responsibleUserFilter);
-        const result = await getTasksByFilter({
-            client,
-            query,
-            cursor: args.cursor,
-            limit: args.limit,
-        });
-        // No need for post-fetch filtering since it's handled in the query
-        const filteredTasks = result.tasks;
-        const textContent = generateTextContent({
-            tasks: filteredTasks,
-            args,
-            nextCursor: result.nextCursor,
-            assigneeEmail,
-        });
-        return getToolOutput({
-            textContent,
-            structuredContent: {
-                tasks: filteredTasks,
-                nextCursor: result.nextCursor,
-                totalCount: filteredTasks.length,
-                hasMore: Boolean(result.nextCursor),
-                appliedFilters: args,
-            },
-        });
-    },
-};
-function generateTextContent({ tasks, args, nextCursor, assigneeEmail, }) {
-    // Generate filter description
-    const filterHints = [];
-    if (args.overdueOption === 'overdue-only') {
-        filterHints.push('overdue tasks only');
-    }
-    else if (args.startDate === 'today') {
-        const overdueText = args.overdueOption === 'exclude-overdue' ? '' : ' + overdue tasks';
-        filterHints.push(`today${overdueText}${args.daysCount > 1 ? ` + ${args.daysCount - 1} more days` : ''}`);
-    }
-    else if (args.startDate) {
-        const dateRange = args.daysCount > 1
-            ? ` to ${getDateString(addDays(args.startDate, args.daysCount))}`
-            : '';
-        filterHints.push(`${args.startDate}${dateRange}`);
-    }
-    // Add label filter information
-    if (args.labels && args.labels.length > 0) {
-        const labelText = args.labels
-            .map((label) => `@${label}`)
-            .join(args.labelsOperator === 'and' ? ' & ' : ' | ');
-        filterHints.push(`labels: ${labelText}`);
-    }
-    // Add responsible user filter information
-    if (args.responsibleUser) {
-        const email = assigneeEmail || args.responsibleUser;
-        filterHints.push(`assigned to: ${email}`);
-    }
-    // Generate subject description
-    let subject = '';
-    if (args.overdueOption === 'overdue-only') {
-        subject = 'Overdue tasks';
-    }
-    else if (args.startDate === 'today') {
-        subject =
-            args.overdueOption === 'exclude-overdue' ? `Today's tasks` : `Today's tasks + overdue`;
-    }
-    else if (args.startDate) {
-        subject = `Tasks for ${args.startDate}`;
-    }
-    else {
-        subject = 'Tasks';
-    }
-    // Append responsible user to subject if provided
-    if (args.responsibleUser) {
-        const email = assigneeEmail || args.responsibleUser;
-        subject += ` assigned to ${email}`;
-    }
-    // Generate helpful suggestions for empty results
-    const zeroReasonHints = [];
-    if (tasks.length === 0) {
-        if (args.overdueOption === 'overdue-only') {
-            zeroReasonHints.push('Great job! No overdue tasks');
-        }
-        else if (args.startDate === 'today') {
-            const overdueNote = args.overdueOption === 'exclude-overdue' ? '' : ' or overdue';
-            zeroReasonHints.push(`Great job! No tasks for today${overdueNote}`);
-        }
-        else {
-            zeroReasonHints.push("Expand date range with larger 'daysCount'");
-            zeroReasonHints.push("Check today's tasks with startDate='today'");
-        }
-    }
-    // Generate contextual next steps
-    const now = new Date();
-    const todayStr = getDateString(now);
-    const hasOverdue = args.overdueOption === 'overdue-only' ||
-        args.startDate === 'today' ||
-        tasks.some((task) => task.dueDate && new Date(task.dueDate) < now);
-    const nextSteps = generateTaskNextSteps('listed', tasks, {
-        hasToday: args.startDate === 'today' || tasks.some((task) => task.dueDate === todayStr),
-        hasOverdue,
-    });
-    return summarizeList({
-        subject,
-        count: tasks.length,
-        limit: args.limit,
-        nextCursor: nextCursor ?? undefined,
-        filterHints,
-        previewLines: previewTasks(tasks, Math.min(tasks.length, args.limit)),
-        zeroReasonHints,
-        nextSteps,
-    });
-}
-export { findTasksByDate };

package/dist/tools/find-tasks.js

@@ -1,329 +0,0 @@
-import { z } from 'zod';
-import { appendToQuery, filterTasksByResponsibleUser, RESPONSIBLE_USER_FILTERING, resolveResponsibleUser, } from '../filter-helpers.js';
-import { getToolOutput } from '../mcp-helpers.js';
-import { getTasksByFilter, mapTask } from '../tool-helpers.js';
-import { ApiLimits } from '../utils/constants.js';
-import { generateLabelsFilter, LabelsSchema } from '../utils/labels.js';
-import { generateTaskNextSteps, getDateString, previewTasks, summarizeList, } from '../utils/response-builders.js';
-import { ToolNames } from '../utils/tool-names.js';
-const { FIND_COMPLETED_TASKS, ADD_TASKS } = ToolNames;
-const ArgsSchema = {
-    searchText: z.string().optional().describe('The text to search for in tasks.'),
-    projectId: z
-        .string()
-        .optional()
-        .describe('Find tasks in this project. Project ID should be an ID string, or the text "inbox", for inbox tasks.'),
-    sectionId: z.string().optional().describe('Find tasks in this section.'),
-    parentId: z.string().optional().describe('Find subtasks of this parent task.'),
-    responsibleUser: z
-        .string()
-        .optional()
-        .describe('Find tasks assigned to this user. Can be a user ID, name, or email address.'),
-    responsibleUserFiltering: z
-        .enum(RESPONSIBLE_USER_FILTERING)
-        .optional()
-        .describe('How to filter by responsible user when responsibleUser is not provided. "assigned" = only tasks assigned to others; "unassignedOrMe" = only unassigned tasks or tasks assigned to me; "all" = all tasks regardless of assignment. Default value will be `unassignedOrMe`.'),
-    limit: z
-        .number()
-        .int()
-        .min(1)
-        .max(ApiLimits.TASKS_MAX)
-        .default(ApiLimits.TASKS_DEFAULT)
-        .describe('The maximum number of tasks to return.'),
-    cursor: z
-        .string()
-        .optional()
-        .describe('The cursor to get the next page of tasks (cursor is obtained from the previous call to this tool, with the same parameters).'),
-    ...LabelsSchema,
-};
-const findTasks = {
-    name: ToolNames.FIND_TASKS,
-    description: 'Find tasks by text search, or by project/section/parent container/responsible user. At least one filter must be provided.',
-    parameters: ArgsSchema,
-    async execute(args, client) {
-        const { searchText, projectId, sectionId, parentId, responsibleUser, responsibleUserFiltering, limit, cursor, labels, labelsOperator, } = args;
-        const todoistUser = await client.getUser();
-        // Validate at least one filter is provided
-        const hasLabels = labels && labels.length > 0;
-        if (!searchText &&
-            !projectId &&
-            !sectionId &&
-            !parentId &&
-            !responsibleUser &&
-            !hasLabels) {
-            throw new Error('At least one filter must be provided: searchText, projectId, sectionId, parentId, responsibleUser, or labels');
-        }
-        // Resolve assignee name to user ID if provided
-        const resolved = await resolveResponsibleUser(client, responsibleUser);
-        const resolvedAssigneeId = resolved?.userId;
-        const assigneeEmail = resolved?.email;
-        // If using container-based filtering, use direct API
-        if (projectId || sectionId || parentId) {
-            const taskParams = {
-                limit,
-                cursor: cursor ?? null,
-            };
-            if (projectId) {
-                taskParams.projectId =
-                    projectId === 'inbox' ? todoistUser.inboxProjectId : projectId;
-            }
-            if (sectionId)
-                taskParams.sectionId = sectionId;
-            if (parentId)
-                taskParams.parentId = parentId;
-            const { results, nextCursor } = await client.getTasks(taskParams);
-            const mappedTasks = results.map(mapTask);
-            // Apply search text filter
-            let filteredTasks = searchText
-                ? mappedTasks.filter((task) => task.content.toLowerCase().includes(searchText.toLowerCase()) ||
-                    task.description?.toLowerCase().includes(searchText.toLowerCase()))
-                : mappedTasks;
-            // Apply responsibleUid filter
-            filteredTasks = filterTasksByResponsibleUser({
-                tasks: filteredTasks,
-                resolvedAssigneeId,
-                currentUserId: todoistUser.id,
-                responsibleUserFiltering,
-            });
-            // Apply label filter
-            if (labels && labels.length > 0) {
-                filteredTasks =
-                    labelsOperator === 'and'
-                        ? filteredTasks.filter((task) => labels.every((label) => task.labels.includes(label)))
-                        : filteredTasks.filter((task) => labels.some((label) => task.labels.includes(label)));
-            }
-            const textContent = generateTextContent({
-                tasks: filteredTasks,
-                args,
-                nextCursor,
-                isContainerSearch: true,
-                assigneeEmail,
-            });
-            return getToolOutput({
-                textContent,
-                structuredContent: {
-                    tasks: filteredTasks,
-                    nextCursor,
-                    totalCount: filteredTasks.length,
-                    hasMore: Boolean(nextCursor),
-                    appliedFilters: args,
-                },
-            });
-        }
-        // If only responsibleUid is provided (without containers), use assignee filter
-        if (resolvedAssigneeId && !searchText && !hasLabels) {
-            const tasks = await client.getTasksByFilter({
-                query: `assigned to: ${assigneeEmail}`,
-                lang: 'en',
-                limit,
-                cursor: cursor ?? null,
-            });
-            const mappedTasks = tasks.results.map(mapTask);
-            const textContent = generateTextContent({
-                tasks: mappedTasks,
-                args,
-                nextCursor: tasks.nextCursor,
-                isContainerSearch: false,
-                assigneeEmail,
-            });
-            return getToolOutput({
-                textContent,
-                structuredContent: {
-                    tasks: mappedTasks,
-                    nextCursor: tasks.nextCursor,
-                    totalCount: mappedTasks.length,
-                    hasMore: Boolean(tasks.nextCursor),
-                    appliedFilters: args,
-                },
-            });
-        }
-        // Handle search text and/or labels using filter query (responsibleUid filtering done client-side)
-        let query = '';
-        // Add search text component
-        if (searchText) {
-            query = `search: ${searchText}`;
-        }
-        // Add labels component
-        const labelsFilter = generateLabelsFilter(labels, labelsOperator);
-        query = appendToQuery(query, labelsFilter);
-        // Execute filter query
-        const result = await getTasksByFilter({
-            client,
-            query,
-            cursor: args.cursor,
-            limit: args.limit,
-        });
-        const tasks = filterTasksByResponsibleUser({
-            tasks: result.tasks,
-            resolvedAssigneeId,
-            currentUserId: todoistUser.id,
-            responsibleUserFiltering,
-        });
-        const textContent = generateTextContent({
-            tasks,
-            args,
-            nextCursor: result.nextCursor,
-            isContainerSearch: false,
-            assigneeEmail,
-        });
-        return getToolOutput({
-            textContent,
-            structuredContent: {
-                tasks,
-                nextCursor: result.nextCursor,
-                totalCount: tasks.length,
-                hasMore: Boolean(result.nextCursor),
-                appliedFilters: args,
-            },
-        });
-    },
-};
-function getContainerZeroReasonHints(args) {
-    if (args.projectId) {
-        const hints = [
-            args.searchText ? 'No tasks in project match search' : 'Project has no tasks yet',
-        ];
-        if (!args.searchText) {
-            hints.push(`Use ${ADD_TASKS} to create tasks`);
-        }
-        return hints;
-    }
-    if (args.sectionId) {
-        const hints = [args.searchText ? 'No tasks in section match search' : 'Section is empty'];
-        if (!args.searchText) {
-            hints.push('Tasks may be in other sections of the project');
-        }
-        return hints;
-    }
-    if (args.parentId) {
-        const hints = [args.searchText ? 'No subtasks match search' : 'No subtasks created yet'];
-        if (!args.searchText) {
-            hints.push(`Use ${ADD_TASKS} with parentId to add subtasks`);
-        }
-        return hints;
-    }
-    return [];
-}
-function generateTextContent({ tasks, args, nextCursor, isContainerSearch, assigneeEmail, }) {
-    // Generate subject and filter descriptions based on search type
-    let subject = 'Tasks';
-    const filterHints = [];
-    const zeroReasonHints = [];
-    if (isContainerSearch) {
-        // Container-based search
-        if (args.projectId) {
-            subject = 'Tasks in project';
-            filterHints.push(`in project ${args.projectId}`);
-        }
-        else if (args.sectionId) {
-            subject = 'Tasks in section';
-            filterHints.push(`in section ${args.sectionId}`);
-        }
-        else if (args.parentId) {
-            subject = 'Subtasks';
-            filterHints.push(`subtasks of ${args.parentId}`);
-        }
-        else {
-            subject = 'Tasks'; // fallback, though this shouldn't happen
-        }
-        // Add search text filter if present
-        if (args.searchText) {
-            subject += ` matching "${args.searchText}"`;
-            filterHints.push(`containing "${args.searchText}"`);
-        }
-        // Add responsibleUid filter if present
-        if (args.responsibleUser) {
-            const email = assigneeEmail || args.responsibleUser;
-            subject += ` assigned to ${email}`;
-            filterHints.push(`assigned to ${email}`);
-        }
-        // Add label filter information
-        if (args.labels && args.labels.length > 0) {
-            const labelText = args.labels
-                .map((label) => `@${label}`)
-                .join(args.labelsOperator === 'and' ? ' & ' : ' | ');
-            filterHints.push(`labels: ${labelText}`);
-        }
-        // Container-specific zero result hints
-        if (tasks.length === 0) {
-            zeroReasonHints.push(...getContainerZeroReasonHints(args));
-        }
-    }
-    else {
-        // Text, responsibleUid, or labels search
-        const email = assigneeEmail || args.responsibleUser;
-        // Build subject based on filters
-        const subjectParts = [];
-        if (args.searchText) {
-            subjectParts.push(`"${args.searchText}"`);
-        }
-        if (args.responsibleUser) {
-            subjectParts.push(`assigned to ${email}`);
-        }
-        if (args.labels && args.labels.length > 0) {
-            const labelText = args.labels
-                .map((label) => `@${label}`)
-                .join(args.labelsOperator === 'and' ? ' & ' : ' | ');
-            subjectParts.push(`with labels: ${labelText}`);
-        }
-        if (args.searchText) {
-            subject = `Search results for ${subjectParts.join(' ')}`;
-            filterHints.push(`matching "${args.searchText}"`);
-        }
-        else if (args.responsibleUser && (!args.labels || args.labels.length === 0)) {
-            subject = `Tasks assigned to ${email}`;
-        }
-        else if (args.labels && args.labels.length > 0 && !args.responsibleUser) {
-            const labelText = args.labels
-                .map((label) => `@${label}`)
-                .join(args.labelsOperator === 'and' ? ' & ' : ' | ');
-            subject = `Tasks with labels: ${labelText}`;
-        }
-        else {
-            subject = `Tasks ${subjectParts.join(' ')}`;
-        }
-        // Add filter hints
-        if (args.responsibleUser) {
-            filterHints.push(`assigned to ${email}`);
-        }
-        if (args.labels && args.labels.length > 0) {
-            const labelText = args.labels
-                .map((label) => `@${label}`)
-                .join(args.labelsOperator === 'and' ? ' & ' : ' | ');
-            filterHints.push(`labels: ${labelText}`);
-        }
-        if (tasks.length === 0) {
-            if (args.responsibleUser) {
-                const email = assigneeEmail || args.responsibleUser;
-                zeroReasonHints.push(`No tasks assigned to ${email}`);
-                zeroReasonHints.push('Check if the user name is correct');
-                zeroReasonHints.push(`Check completed tasks with ${FIND_COMPLETED_TASKS}`);
-            }
-            if (args.searchText) {
-                zeroReasonHints.push('Try broader search terms');
-                zeroReasonHints.push('Verify spelling and try partial words');
-                if (!args.responsibleUser) {
-                    zeroReasonHints.push(`Check completed tasks with ${FIND_COMPLETED_TASKS}`);
-                }
-            }
-        }
-    }
-    // Generate contextual next steps
-    const now = new Date();
-    const todayDateString = getDateString(now);
-    const nextSteps = generateTaskNextSteps('listed', tasks, {
-        hasToday: tasks.some((task) => task.dueDate === todayDateString),
-        hasOverdue: tasks.some((task) => task.dueDate && new Date(task.dueDate) < now),
-    });
-    return summarizeList({
-        subject,
-        count: tasks.length,
-        limit: args.limit,
-        nextCursor: nextCursor ?? undefined,
-        filterHints,
-        previewLines: previewTasks(tasks, Math.min(tasks.length, args.limit)),
-        zeroReasonHints,
-        nextSteps,
-    });
-}
-export { findTasks };