@doist/todoist-ai 0.1.0

package/src/tools/projects-list.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import type { TodoistTool } from "../todoist-tool.js";
+
+const ArgsSchema = {
+	limit: z
+		.number()
+		.int()
+		.min(1)
+		.max(100)
+		.default(50)
+		.describe("The maximum number of projects to return."),
+	cursor: z
+		.string()
+		.optional()
+		.describe(
+			"The cursor to get the next page of projects (cursor is obtained from the previous call to this tool, with the same parameters).",
+		),
+};
+
+const projectsList = {
+	name: "projects-list",
+	description: "List all projects for the user.",
+	parameters: ArgsSchema,
+	async execute(args, client) {
+		const { results, nextCursor } = await client.getProjects({
+			limit: args.limit,
+			cursor: args.cursor ?? null,
+		});
+		return {
+			projects: results,
+			nextCursor,
+		};
+	},
+} satisfies TodoistTool<typeof ArgsSchema>;
+
+export { projectsList };

package/src/tools/projects-search.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import type { TodoistTool } from "../todoist-tool.js";
+import { mapProject } from "./shared.js";
+
+const ArgsSchema = {
+	search: z
+		.string()
+		.optional()
+		.describe(
+			"Search for a project by name (partial and case insensitive match). If omitted, all projects are returned.",
+		),
+	limit: z
+		.number()
+		.int()
+		.min(1)
+		.max(100)
+		.default(50)
+		.describe("The maximum number of projects to return."),
+	cursor: z
+		.string()
+		.optional()
+		.describe(
+			"The cursor to get the next page of projects (cursor is obtained from the previous call to this tool, with the same parameters).",
+		),
+};
+
+const projectsSearch = {
+	name: "projects-search",
+	description: "Search for projects by name or other criteria.",
+	parameters: ArgsSchema,
+	async execute(args, client) {
+		const { results, nextCursor } = await client.getProjects({
+			limit: args.limit,
+			cursor: args.cursor ?? null,
+		});
+		const searchLower = args.search ? args.search.toLowerCase() : undefined;
+		const filtered = searchLower
+			? results.filter((project) =>
+					project.name.toLowerCase().includes(searchLower),
+				)
+			: results;
+		return {
+			projects: filtered.map(mapProject),
+			nextCursor,
+		};
+	},
+} satisfies TodoistTool<typeof ArgsSchema>;
+
+export { projectsSearch };

package/src/tools/projects-update-one.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import type { TodoistTool } from "../todoist-tool.js";
+
+const ArgsSchema = {
+	id: z.string().min(1).describe("The ID of the project to update."),
+	name: z.string().min(1).describe("The new name for the project."),
+};
+
+const projectsUpdateOne = {
+	name: "projects-update-one",
+	description: "Update a project's name by its ID.",
+	parameters: ArgsSchema,
+	async execute(args, client) {
+		const { id, name } = args;
+		const project = await client.updateProject(id, { name });
+		return project;
+	},
+} satisfies TodoistTool<typeof ArgsSchema>;
+
+export { projectsUpdateOne };

package/src/tools/sections-add-one.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import type { TodoistTool } from "../todoist-tool.js";
+
+const ArgsSchema = {
+	name: z.string().min(1).describe("The name of the section to add."),
+	projectId: z
+		.string()
+		.min(1)
+		.describe("The ID of the project to add the section to."),
+};
+
+const sectionsAddOne = {
+	name: "sections-add-one",
+	description: "Add a new section to a project.",
+	parameters: ArgsSchema,
+	async execute(args, client) {
+		const section = await client.addSection({
+			name: args.name,
+			projectId: args.projectId,
+		});
+		return section;
+	},
+} satisfies TodoistTool<typeof ArgsSchema>;
+
+export { sectionsAddOne };

package/src/tools/sections-delete-one.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import type { TodoistTool } from "../todoist-tool.js";
+
+const ArgsSchema = {
+	id: z.string().min(1).describe("The ID of the section to delete."),
+};
+
+const sectionsDeleteOne = {
+	name: "sections-delete-one",
+	description: "Delete a section by its ID.",
+	parameters: ArgsSchema,
+	async execute(args, client) {
+		await client.deleteSection(args.id);
+		return { success: true };
+	},
+} satisfies TodoistTool<typeof ArgsSchema>;
+
+export { sectionsDeleteOne };

package/src/tools/sections-search.ts

@@ -0,0 +1,39 @@
+import type { Section } from "@doist/todoist-api-typescript";
+import { z } from "zod";
+import type { TodoistTool } from "../todoist-tool.js";
+
+const ArgsSchema = {
+	projectId: z
+		.string()
+		.min(1)
+		.describe("The ID of the project to search sections in."),
+	search: z
+		.string()
+		.optional()
+		.describe(
+			"Search for a section by name (partial and case insensitive match). If omitted, all sections in the project are returned.",
+		),
+};
+
+const sectionsSearch = {
+	name: "sections-search",
+	description: "Search for sections by name or other criteria in a project.",
+	parameters: ArgsSchema,
+	async execute(args, client) {
+		const { results } = await client.getSections({
+			projectId: args.projectId,
+		});
+		const searchLower = args.search ? args.search.toLowerCase() : undefined;
+		const filtered = searchLower
+			? results.filter((section: Section) =>
+					section.name.toLowerCase().includes(searchLower),
+				)
+			: results;
+		return filtered.map((section: Section) => ({
+			id: section.id,
+			name: section.name,
+		}));
+	},
+} satisfies TodoistTool<typeof ArgsSchema>;
+
+export { sectionsSearch };

package/src/tools/sections-update-one.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import type { TodoistTool } from "../todoist-tool.js";
+
+const ArgsSchema = {
+	id: z.string().min(1).describe("The ID of the section to update."),
+	name: z.string().min(1).describe("The new name for the section."),
+};
+
+const sectionsUpdateOne = {
+	name: "sections-update-one",
+	description: "Update a section's name by its ID.",
+	parameters: ArgsSchema,
+	async execute(args, client) {
+		const { id, name } = args;
+		const section = await client.updateSection(id, { name });
+		return section;
+	},
+} satisfies TodoistTool<typeof ArgsSchema>;
+
+export { sectionsUpdateOne };

package/src/tools/shared.ts

@@ -0,0 +1,94 @@
+import {
+	type Project,
+	type Task,
+	type TodoistApi,
+	getSanitizedContent,
+} from "@doist/todoist-api-typescript";
+import z from "zod";
+
+/**
+ * Map a single Todoist task to a more structured format, for LLM consumption.
+ * @param task - The task to map.
+ * @returns The mapped task.
+ */
+function mapTask(task: Task) {
+	return {
+		id: task.id,
+		content: getSanitizedContent(task.content),
+		description: getSanitizedContent(task.description),
+		dueDate: task.due?.date,
+		recurring:
+			task.due?.isRecurring && task.due.string ? task.due.string : false,
+		priority: task.priority,
+		projectId: task.projectId,
+		sectionId: task.sectionId,
+		parentId: task.parentId,
+		labels: task.labels,
+	};
+}
+
+/**
+ * Map a single Todoist project to a more structured format, for LLM consumption.
+ * @param project - The project to map.
+ * @returns The mapped project.
+ */
+function mapProject(project: Project) {
+	return {
+		id: project.id,
+		name: project.name,
+		color: project.color,
+		isFavorite: project.isFavorite,
+		isShared: project.isShared,
+		parentId: project.parentId ?? null,
+		inboxProject: project.isInboxProject ?? false,
+		viewStyle: project.viewStyle,
+	};
+}
+
+const ErrorSchema = z.object({
+	httpStatusCode: z.number(),
+	responseData: z.object({
+		error: z.string(),
+		errorCode: z.number(),
+		errorTag: z.string(),
+	}),
+});
+
+async function getTasksByFilter({
+	client,
+	query,
+	limit,
+	cursor,
+}: {
+	client: TodoistApi;
+	query: string;
+	limit: number | undefined;
+	cursor: string | undefined;
+}) {
+	try {
+		const { results, nextCursor } = await client.getTasksByFilter({
+			query,
+			cursor,
+			limit,
+		});
+
+		return {
+			tasks: results.map(mapTask),
+			nextCursor,
+		};
+	} catch (error) {
+		const parsedError = ErrorSchema.safeParse(error);
+		if (!parsedError.success) {
+			throw error;
+		}
+		const { responseData } = parsedError.data;
+		if (responseData.errorTag === "INVALID_SEARCH_QUERY") {
+			throw new Error(`Invalid filter query: ${query}`);
+		}
+		throw new Error(
+			`${responseData.error} (tag: ${responseData.errorTag}, code: ${responseData.errorCode})`,
+		);
+	}
+}
+
+export { getTasksByFilter, mapTask, mapProject };

package/src/tools/subtasks-list-for-parent-task.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import type { TodoistTool } from "../todoist-tool.js";
+import { mapTask } from "./shared.js";
+
+const ArgsSchema = {
+	parentId: z
+		.string()
+		.min(1)
+		.describe("The ID of the parent task to get subtasks for."),
+	limit: z
+		.number()
+		.int()
+		.min(1)
+		.max(50)
+		.default(10)
+		.describe("The maximum number of subtasks to return."),
+	cursor: z
+		.string()
+		.optional()
+		.describe(
+			"The cursor to get the next page of subtasks (from previous call).",
+		),
+};
+
+const subtasksListForParentTask = {
+	name: "subtasks-list-for-parent-task",
+	description: "List subtasks for a given parent task.",
+	parameters: ArgsSchema,
+	async execute(args, client) {
+		const { parentId, limit, cursor } = args;
+		const { results, nextCursor } = await client.getTasks({
+			parentId,
+			limit,
+			cursor: cursor ?? null,
+		});
+		return {
+			tasks: results.map(mapTask),
+			nextCursor,
+		};
+	},
+} satisfies TodoistTool<typeof ArgsSchema>;
+
+export { subtasksListForParentTask };

package/src/tools/tasks-add-multiple.ts

@@ -0,0 +1,53 @@
+import type { Task } from "@doist/todoist-api-typescript";
+import { z } from "zod";
+import type { TodoistTool } from "../todoist-tool.js";
+import { mapTask } from "./shared.js";
+
+const TaskSchema = z.object({
+	content: z.string().min(1).describe("The content of the task to create."),
+	description: z.string().optional().describe("The description of the task."),
+	priority: z
+		.number()
+		.int()
+		.min(1)
+		.max(4)
+		.optional()
+		.describe("The priority of the task (1-4)."),
+	dueString: z
+		.string()
+		.optional()
+		.describe("The due date for the task, in natural language."),
+});
+
+const ArgsSchema = {
+	projectId: z
+		.string()
+		.optional()
+		.describe("The project ID to add the tasks to."),
+	sectionId: z
+		.string()
+		.optional()
+		.describe("The section ID to add the tasks to."),
+	parentId: z
+		.string()
+		.optional()
+		.describe("The parent task ID (for subtasks)."),
+	tasks: z.array(TaskSchema).min(1).describe("The array of tasks to add."),
+};
+
+const tasksAddMultiple = {
+	name: "tasks-add-multiple",
+	description: "Add one or more tasks to a project, section, or parent.",
+	parameters: ArgsSchema,
+	async execute(args, client) {
+		const { projectId, sectionId, parentId, tasks } = args;
+		const newTasks: Task[] = [];
+		for (const task of tasks) {
+			const taskArgs = { ...task, projectId, sectionId, parentId };
+			newTasks.push(await client.addTask(taskArgs));
+		}
+		return newTasks.map(mapTask);
+	},
+} satisfies TodoistTool<typeof ArgsSchema>;
+
+export { tasksAddMultiple };

package/src/tools/tasks-by-date-range.ts

@@ -0,0 +1,58 @@
+import { addDays, formatISO } from "date-fns";
+import { z } from "zod";
+import type { TodoistTool } from "../todoist-tool.js";
+import { getTasksByFilter } from "./shared.js";
+
+const ArgsSchema = {
+	startDate: z
+		.string()
+		.regex(/^(\d{4}-\d{2}-\d{2}|today)$/)
+		.describe(
+			"The start date to get the tasks for. Format: YYYY-MM-DD or 'today'.",
+		),
+	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.",
+		),
+	limit: z
+		.number()
+		.int()
+		.min(1)
+		.max(50)
+		.default(10)
+		.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).",
+		),
+};
+
+const tasksListByDate = {
+	name: "tasks-list-by-date",
+	description: "Get tasks by date range.",
+	parameters: ArgsSchema,
+	async execute(args, client) {
+		const startDate =
+			args.startDate === "today"
+				? formatISO(new Date(), { representation: "date" })
+				: args.startDate;
+		const endDate = addDays(startDate, args.daysCount + 1);
+		const endDateStr = formatISO(endDate, { representation: "date" });
+		const query = `(due after: ${startDate} | due: ${startDate}) & due before: ${endDateStr}`;
+		return await getTasksByFilter({
+			client,
+			query,
+			cursor: args.cursor,
+			limit: args.limit,
+		});
+	},
+} satisfies TodoistTool<typeof ArgsSchema>;
+
+export { tasksListByDate };

package/src/tools/tasks-by-project.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import type { TodoistTool } from "../todoist-tool.js";
+import { mapTask } from "./shared.js";
+
+const ArgsSchema = {
+	projectId: z
+		.string()
+		.min(1)
+		.describe("The ID of the project to get tasks for."),
+	limit: z
+		.number()
+		.int()
+		.min(1)
+		.max(50)
+		.default(10)
+		.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).",
+		),
+};
+
+const tasksListForProject = {
+	name: "tasks-list-for-project",
+	description: "Get tasks by project ID.",
+	parameters: ArgsSchema,
+	async execute(args, client) {
+		const { projectId, limit, cursor } = args;
+		const { results, nextCursor } = await client.getTasks({
+			projectId,
+			limit,
+			cursor: cursor ?? null,
+		});
+		return {
+			tasks: results.map(mapTask),
+			nextCursor,
+		};
+	},
+} satisfies TodoistTool<typeof ArgsSchema>;
+
+export { tasksListForProject };

package/src/tools/tasks-complete-multiple.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { TodoistTool } from "../todoist-tool.js";
+
+const ArgsSchema = {
+	ids: z
+		.array(z.string().min(1))
+		.min(1)
+		.describe("The IDs of the tasks to complete."),
+};
+
+const tasksCompleteMultiple = {
+	name: "tasks-complete-multiple",
+	description: "Complete one or more tasks by their IDs.",
+	parameters: ArgsSchema,
+	async execute(args, client) {
+		const completed: string[] = [];
+		for (const id of args.ids) {
+			try {
+				await client.closeTask(id);
+				completed.push(id);
+			} catch {
+				// Ignore errors for individual tasks, continue with others
+			}
+		}
+		return { success: true, completed };
+	},
+} satisfies TodoistTool<typeof ArgsSchema>;
+
+export { tasksCompleteMultiple };

package/src/tools/tasks-delete-one.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import type { TodoistTool } from "../todoist-tool.js";
+
+const ArgsSchema = {
+	id: z.string().min(1).describe("The ID of the task to delete."),
+};
+
+const tasksDeleteOne = {
+	name: "tasks-delete-one",
+	description: "Delete a task by its ID.",
+	parameters: ArgsSchema,
+	async execute(args, client) {
+		await client.deleteTask(args.id);
+		return { success: true };
+	},
+} satisfies TodoistTool<typeof ArgsSchema>;
+
+export { tasksDeleteOne };

package/src/tools/tasks-list-for-section.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import type { TodoistTool } from "../todoist-tool.js";
+import { mapTask } from "./shared.js";
+
+const ArgsSchema = {
+	sectionId: z
+		.string()
+		.min(1)
+		.describe("The ID of the section to get tasks for."),
+	limit: z
+		.number()
+		.int()
+		.min(1)
+		.max(50)
+		.default(10)
+		.describe("The maximum number of tasks to return."),
+	cursor: z
+		.string()
+		.optional()
+		.describe(
+			"The cursor to get the next page of tasks (from previous call).",
+		),
+};
+
+const tasksListForSection = {
+	name: "tasks-list-for-section",
+	description: "List tasks for a given section.",
+	parameters: ArgsSchema,
+	async execute(args, client) {
+		const { sectionId, limit, cursor } = args;
+		const { results, nextCursor } = await client.getTasks({
+			sectionId,
+			limit,
+			cursor: cursor ?? null,
+		});
+		return {
+			tasks: results.map(mapTask),
+			nextCursor,
+		};
+	},
+} satisfies TodoistTool<typeof ArgsSchema>;
+
+export { tasksListForSection };

package/src/tools/tasks-list-overdue.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import type { TodoistTool } from "../todoist-tool.js";
+import { getTasksByFilter } from "./shared.js";
+
+const ArgsSchema = {
+	limit: z
+		.number()
+		.int()
+		.min(1)
+		.max(50)
+		.default(10)
+		.describe("The maximum number of overdue tasks to return."),
+	cursor: z
+		.string()
+		.optional()
+		.describe(
+			"The cursor to get the next page of overdue tasks (cursor is obtained from the previous call to this tool, with the same parameters).",
+		),
+};
+
+const tasksListOverdue = {
+	name: "tasks-list-overdue",
+	description: "Get overdue tasks.",
+	parameters: ArgsSchema,
+	async execute(args, client) {
+		return await getTasksByFilter({
+			client,
+			query: "overdue",
+			cursor: args.cursor,
+			limit: args.limit,
+		});
+	},
+} satisfies TodoistTool<typeof ArgsSchema>;
+
+export { tasksListOverdue };

package/src/tools/tasks-organize-multiple.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import type { TodoistTool } from "../todoist-tool.js";
+
+const TaskUpdateSchema = z.object({
+	id: z.string().min(1).describe("The ID of the task to update."),
+	projectId: z
+		.string()
+		.optional()
+		.describe("The new project ID for the task."),
+	sectionId: z
+		.string()
+		.optional()
+		.describe("The new section ID for the task."),
+	parentId: z
+		.string()
+		.optional()
+		.describe("The new parent task ID (for subtasks)."),
+	order: z
+		.number()
+		.optional()
+		.describe("The new order of the task within its parent/section."),
+});
+
+const ArgsSchema = {
+	tasks: z
+		.array(TaskUpdateSchema)
+		.min(1)
+		.describe("Array of task updates to apply."),
+};
+
+const tasksOrganizeMultiple = {
+	name: "tasks-organize-multiple",
+	description: "Organize multiple tasks (move, reorder, etc.) in bulk.",
+	parameters: ArgsSchema,
+	async execute(args, client) {
+		const results = [];
+		for (const update of args.tasks) {
+			const { id, ...updateArgs } = update;
+			results.push(await client.updateTask(id, updateArgs));
+		}
+		return results;
+	},
+} satisfies TodoistTool<typeof ArgsSchema>;
+
+export { tasksOrganizeMultiple };