@todoist/mcp 0.0.1 → 15.0.0

package/dist/mcp-server.d.ts

@@ -0,0 +1,16 @@
+import { McpServer } from '@modelcontextprotocol/server';
+import { McpServerOptions } from '@todoist/mcp-core/host';
+import { FEATURE_NAMES, Feature, FeatureName, Features } from './mcp-helpers.js';
+export declare const instructions = "\n## Todoist Task and Project Management Tools\n\nYou have access to comprehensive Todoist management tools for personal productivity and team collaboration. Use these tools to help users manage tasks, projects, sections, comments, and assignments effectively.\n\n### Core Capabilities:\n- Create, update, complete, and search tasks with rich metadata (priorities, due dates, durations, assignments)\n- Manage projects and sections with flexible organization\n- Handle comments and collaboration features\n- Bulk assignment operations for team workflows\n- Get overviews and insights about workload and progress\n\n### Choosing between tools\n\nWhat each tool does and how to fill its parameters is in the tool's own description and input schema. This section covers only what those cannot: which tool to reach for, and how tools relate to each other.\n\n**Dates**\n\n- To move a task to a different date or time use **reschedule-tasks**, never **update-tasks**. It also sets duration, for time-blocking. update-tasks replaces the whole due string, so it refuses a dueString on a recurring task unless replaceRecurrence is true.\n- Never send a task's existing projectId, sectionId or parentId back to **update-tasks** \u2014 those fields are treated as a move.\n- All dates respect the user's timezone.\n- Todoist apps only display task durations under 24 hours. A longer one (\"36h\") or a day-based one (\"3d\") is stored and reported faithfully, but the apps show the task as having no duration \u2014 only set one when the user explicitly asks for it.\n\n**Finding things**\n\n- For \"what did I complete?\", call **user-info** for the asker's user ID, then **find-activity** with objectType=\"task\", eventType=\"completed\", initiatorId, and dateFrom/dateTo. Without initiatorId the answer covers every collaborator. find-activity reports completion events, including each occurrence of a recurring task; **find-completed-tasks** lists completed tasks, which is not the same question.\n- To resolve a person's name or email to a user ID, or to answer \"who is X?\", use **find-project-collaborators** with just a searchTerm. It covers every shared project you can access plus yourself, so an empty result means they collaborate on none of them \u2014 not that they do not exist.\n- Before assigning work to someone, call **find-project-collaborators** again with the target projectId. Resolving an ID only proves they collaborate on *some* project you can see; assignment fails unless they collaborate on that one.\n- To find out whether a task hides subtasks, use **fetch-object** with includeChildren rather than a speculative **find-tasks** call.\n- Filter tasks by label **name**. Label IDs are only for **delete-object** and **update-labels**. Shared labels can be renamed but not recoloured, reordered or favourited.\n\n**Comments**\n\n- Comments notify only the people **add-comments** is handed. When a comment mentions someone, name them in `notifyUsers` \u2014 writing \"@Ana\" in the text notifies nobody. Omit `notifyUsers` to notify whoever the Todoist apps would, or pass `[\"none\"]` to stay silent.\n- Notification cannot be sent when editing a comment, only when adding one.\n\n**Deleting and archiving**\n\n- **delete-object** removes every object type; there is no per-type delete tool. Reminders use type \"reminder\", location reminders \"location_reminder\".\n- A workspace project must be archived with **project-management** before it can be deleted. A personal project can be deleted directly.\n\n**Templates**\n\n- Templates cannot be listed through this server, so only use an ID or URL the user gave you. To start a new project from one, call **add-projects** first and import into it. Imports write immediately and cannot be undone.\n\n**Project health**\n\n- Health data may be stale \u2014 check the isStale flag, and call **analyze-project-health** to refresh it before reading again.\n\n**Batches**\n\n- Prefer a batch tool over one call per item.\n- Where a batch tool returns per-item `failures` alongside successes, one failure does not undo the rest: never retry the whole batch, re-send only the items whose failure reason is fixable. **reschedule-tasks** is the exception \u2014 it has no per-item failures and throws if any task fails, so retry it as a whole.\n\nUse the **productivity-analysis** prompt for a combined productivity review \u2014 it pulls together user-info, get-productivity-stats and find-completed-tasks.\n\nAlways provide clear, actionable task titles and descriptions. Use the overview tools to give users context about their workload and project status.\n";
+/**
+ * Create the MCP server.
+ * @param token - The user's Todoist API token.
+ * @param baseUrl - The base URL for the todoist API.
+ * @param features - Features to enable for the server.
+ * @returns the MCP server.
+ */
+declare function getMcpServer({ token, baseUrl, features, }: McpServerOptions & {
+    features?: Features;
+}): McpServer;
+export { FEATURE_NAMES, type Feature, type FeatureName, type Features, getMcpServer };
+//# sourceMappingURL=mcp-server.d.ts.map

package/dist/mcp-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAA;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AAE9D,OAAO,EACH,aAAa,EACb,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,QAAQ,EAEhB,MAAM,kBAAkB,CAAA;AAMzB,eAAO,MAAM,YAAY,qhJAyDxB,CAAA;AAgBD;;;;;;GAMG;AAEH,iBAAS,YAAY,CAAC,EAClB,KAAK,EACL,OAAO,EACP,QAAa,GAChB,EAAE,gBAAgB,GAAG;IAClB,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACtB,aA+CA;AAED,OAAO,EAAE,aAAa,EAAE,KAAK,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAE,YAAY,EAAE,CAAA"}

package/dist/middleware/require-trusted-host.d.ts

@@ -0,0 +1,44 @@
+import { RequestHandler } from 'express';
+type RequireTrustedHostOptions = {
+    /**
+     * Port-agnostic hostnames permitted in the `Host` and `Origin` headers.
+     * IPv6 entries must be bracketed, e.g. `[::1]`. Invalid entries cause
+     * {@link requireTrustedHost} to throw at construction time (fail fast).
+     */
+    allowedHosts: string[];
+};
+/**
+ * Loopback hostnames always trusted by {@link requireTrustedHost}. Stored
+ * bracketed for IPv6 because `new URL('http://[::1]').hostname` returns `[::1]`.
+ */
+declare const DEFAULT_ALLOWED_HOSTS: string[];
+/**
+ * Build the list of hostnames trusted in the Host and Origin headers. Always
+ * includes the loopback defaults, plus any names from `allowedHostsEnv`
+ * (comma-separated), plus the configured `host` (so an explicit bind — loopback
+ * alias like 127.0.1.1, a LAN IP, etc. — is always trusted). Bind wildcards
+ * (0.0.0.0/::) are never added because they are never valid Host header values —
+ * operators exposing on a wildcard must enumerate client hostnames via
+ * ALLOWED_HOSTS.
+ */
+declare function buildAllowedHosts(host: string, allowedHostsEnv?: string): string[];
+/**
+ * Express middleware that rejects requests whose `Host` or `Origin` header is
+ * not in the trusted allowlist. This is DNS-rebinding protection: a malicious
+ * website that rebinds its domain to a victim's loopback address keeps its own
+ * `Host`/`Origin`, so string-matching against the allowlist (we never DNS
+ * resolve) blocks the request before it can reach the MCP transport.
+ *
+ * - Missing `Host` → 403.
+ * - `Host` hostname not in the allowlist → 403.
+ * - `Origin` absent → allowed (non-browser clients such as `mcp-remote`/`curl`
+ *   send none; the browser attack path always sends one).
+ * - `Origin` present but untrusted or unparseable → 403.
+ *
+ * Throws at construction time if `allowedHosts` contains an entry that isn't a
+ * valid authority, so misconfiguration fails fast instead of becoming opaque
+ * 403s at request time.
+ */
+declare function requireTrustedHost(options: RequireTrustedHostOptions): RequestHandler;
+export { DEFAULT_ALLOWED_HOSTS, buildAllowedHosts, requireTrustedHost, type RequireTrustedHostOptions, };
+//# sourceMappingURL=require-trusted-host.d.ts.map

package/dist/middleware/require-trusted-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-trusted-host.d.ts","sourceRoot":"","sources":["../../src/middleware/require-trusted-host.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAyB,cAAc,EAAY,MAAM,SAAS,CAAA;AAG9E,KAAK,yBAAyB,GAAG;IAC7B;;;;OAIG;IACH,YAAY,EAAE,MAAM,EAAE,CAAA;CACzB,CAAA;AAED;;;GAGG;AACH,QAAA,MAAM,qBAAqB,UAAsC,CAAA;AA4CjE;;;;;;;;GAQG;AACH,iBAAS,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAkB3E;AAUD;;;;;;;;;;;;;;;;GAgBG;AACH,iBAAS,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,cAAc,CAyC9E;AAED,OAAO,EACH,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,yBAAyB,GACjC,CAAA"}

package/dist/middleware/require-valid-todoist-token.d.ts

@@ -0,0 +1,39 @@
+import { Request, RequestHandler } from 'express';
+type StaticTokenSource = {
+    type: 'static';
+    apiKey: string;
+    baseUrl?: string;
+};
+type DynamicTokenSource = {
+    type: 'dynamic';
+    getApiKey: (req: Request) => string | undefined;
+    baseUrl?: string;
+};
+type TokenSource = StaticTokenSource | DynamicTokenSource;
+type RequireValidTodoistTokenOptions = TokenSource & {
+    /**
+     * Cache TTL in milliseconds. Defaults to 300_000 (5 minutes) for static,
+     * 120_000 (2 minutes) for dynamic.
+     */
+    cacheTtlMs?: number;
+    /**
+     * URL for the Protected Resource Metadata document (RFC 9728).
+     * Included in the WWW-Authenticate header when returning 401.
+     * If omitted, the header is sent without resource_metadata.
+     */
+    resourceMetadataUrl?: string;
+};
+/**
+ * Express middleware that validates the Todoist API token before MCP processing.
+ *
+ * Returns HTTP 401 with a spec-compliant WWW-Authenticate header if the token
+ * is invalid, allowing MCP clients to trigger OAuth token refresh, and 403 with
+ * an `insufficient_scope` challenge if it lacks a scope the tools need.
+ */
+declare function requireValidTodoistToken(options: RequireValidTodoistTokenOptions): RequestHandler;
+/**
+ * Clear the token validation cache. Useful for testing.
+ */
+declare function clearTokenValidationCache(): void;
+export { clearTokenValidationCache, requireValidTodoistToken, type RequireValidTodoistTokenOptions };
+//# sourceMappingURL=require-valid-todoist-token.d.ts.map

package/dist/middleware/require-valid-todoist-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-valid-todoist-token.d.ts","sourceRoot":"","sources":["../../src/middleware/require-valid-todoist-token.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAgB,OAAO,EAAE,cAAc,EAAY,MAAM,SAAS,CAAA;AAI9E,KAAK,iBAAiB,GAAG;IACrB,IAAI,EAAE,QAAQ,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,KAAK,kBAAkB,GAAG;IACtB,IAAI,EAAE,SAAS,CAAA;IACf,SAAS,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAA;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,KAAK,WAAW,GAAG,iBAAiB,GAAG,kBAAkB,CAAA;AAEzD,KAAK,+BAA+B,GAAG,WAAW,GAAG;IACjD;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC/B,CAAA;AAgED;;;;;;GAMG;AACH,iBAAS,wBAAwB,CAAC,OAAO,EAAE,+BAA+B,GAAG,cAAc,CAgC1F;AAED;;GAEG;AACH,iBAAS,yBAAyB,IAAI,IAAI,CAEzC;AAED,OAAO,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,KAAK,+BAA+B,EAAE,CAAA"}

package/dist/prompts/productivity-analysis.d.ts

@@ -0,0 +1,58 @@
+import { GetPromptResult } from '@modelcontextprotocol/server';
+import { z } from 'zod';
+declare const argsSchema: z.ZodObject<{
+    period: z.ZodDefault<z.ZodEnum<{
+        today: "today";
+        "7d": "7d";
+        "14d": "14d";
+        "30d": "30d";
+        "this-week": "this-week";
+        "this-month": "this-month";
+    }>>;
+    focus: z.ZodDefault<z.ZodEnum<{
+        overall: "overall";
+        goals: "goals";
+        projects: "projects";
+        trends: "trends";
+        recommendations: "recommendations";
+    }>>;
+    projectId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type PromptArgs = z.infer<typeof argsSchema>;
+/**
+ * Compute the date range (since/until as YYYY-MM-DD) for a given period.
+ * Uses UTC since the prompt instructs the LLM to call user-info for timezone.
+ */
+declare function computeDateRange(period: PromptArgs['period'], now?: Date): {
+    since: string;
+    until: string;
+    periodDescription: string;
+};
+declare function buildPromptText(args: PromptArgs): string;
+declare function callback(args: PromptArgs): GetPromptResult;
+declare const productivityAnalysis: {
+    name: string;
+    title: string;
+    description: string;
+    argsSchema: z.ZodObject<{
+        period: z.ZodDefault<z.ZodEnum<{
+            today: "today";
+            "7d": "7d";
+            "14d": "14d";
+            "30d": "30d";
+            "this-week": "this-week";
+            "this-month": "this-month";
+        }>>;
+        focus: z.ZodDefault<z.ZodEnum<{
+            overall: "overall";
+            goals: "goals";
+            projects: "projects";
+            trends: "trends";
+            recommendations: "recommendations";
+        }>>;
+        projectId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    callback: typeof callback;
+};
+export { buildPromptText, computeDateRange, productivityAnalysis };
+//# sourceMappingURL=productivity-analysis.d.ts.map

package/dist/prompts/productivity-analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"productivity-analysis.d.ts","sourceRoot":"","sources":["../../src/prompts/productivity-analysis.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAA;AACnE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;;iBAiBd,CAAA;AAEF,KAAK,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAA;AAE5C;;;GAGG;AACH,iBAAS,gBAAgB,CACrB,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,EAC5B,GAAG,GAAE,IAAiB,GACvB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CA0D7D;AAwCD,iBAAS,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAkCjD;AAED,iBAAS,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,eAAe,CAYnD;AAED,QAAA,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;CAOzB,CAAA;AAED,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,CAAA"}

package/dist/require-valid-todoist-token-I1jh7sbd.js

@@ -0,0 +1,63 @@
+import { validateBearerToken as _, createTokenVerdictCache as p, buildBearerChallenge as u } from "@todoist/mcp-core/host";
+import { $ as v, a0 as A } from "./mcp-server-y4HhlBJW.js";
+const k = "https://api.todoist.com", U = (e, t) => _({
+  // Resolved the way the SDK resolves its own requests against a custom base URL. An empty
+  // base (`TODOIST_BASE_URL=`) means the default, as it does for the SDK client.
+  url: new URL("/api/v1/user", t || k),
+  token: e,
+  headers: A({ label: "auth:validate-token" }),
+  fetch: v
+}), b = 3e5, g = 12e4, y = 1e4, d = /* @__PURE__ */ new Map();
+function E(e) {
+  let t = d.get(e);
+  return t || (t = p({
+    ttlMs: e,
+    maxEntries: y,
+    now: () => Date.now()
+  }), d.set(e, t)), t;
+}
+function T(e, t) {
+  e.status(401).set("WWW-Authenticate", u({ resourceMetadataUrl: t })).json({
+    error: "invalid_token",
+    error_description: "Todoist API token is invalid or expired"
+  });
+}
+function L(e, t) {
+  e.status(403).set(
+    "WWW-Authenticate",
+    u({ error: "insufficient_scope", resourceMetadataUrl: t })
+  ).json({
+    error: "insufficient_scope",
+    error_description: "Todoist API token does not have the required scopes"
+  });
+}
+function l(e, t, a, r) {
+  e === "valid" ? a() : e === "forbidden" ? L(t, r) : T(t, r);
+}
+function C(e) {
+  const t = e.type === "static" ? b : g, a = E(e.cacheTtlMs ?? t), { resourceMetadataUrl: r } = e;
+  return async (f, n, o) => {
+    const i = e.type === "static" ? e.apiKey : e.getApiKey(f);
+    if (!i) {
+      T(n, r);
+      return;
+    }
+    const c = a.get(i, e.baseUrl);
+    if (c !== void 0) {
+      l(c, n, o, r);
+      return;
+    }
+    let s;
+    try {
+      s = await U(i, e.baseUrl);
+    } catch (h) {
+      console.warn("[Token validation] Validation failed, proceeding:", h), o();
+      return;
+    }
+    a.set(i, e.baseUrl, s), l(s, n, o, r);
+  };
+}
+export {
+  C as r,
+  U as v
+};

package/dist/todoist-tool.d.ts

@@ -0,0 +1,15 @@
+import { TodoistApi } from '@doist/todoist-sdk';
+import { AnyMcpTool, ExecuteResult, McpTool, RequiredToolAnnotations } from '@todoist/mcp-core';
+import { z } from 'zod';
+/**
+ * A Todoist tool that can be used in an MCP server or other conversational AI interfaces: an
+ * `McpTool` whose `execute` receives the Todoist API client.
+ */
+type TodoistTool<Params extends z.ZodRawShape, Output extends z.ZodRawShape = Record<string, never>> = McpTool<Params, Output, TodoistApi>;
+/**
+ * A Todoist tool of any parameter and output shape, for collections that hold tools of mixed
+ * shapes. Individual tools keep their precise types through their own `satisfies TodoistTool<...>`.
+ */
+type AnyTodoistTool = AnyMcpTool<TodoistApi>;
+export type { AnyTodoistTool, ExecuteResult, RequiredToolAnnotations, TodoistTool };
+//# sourceMappingURL=todoist-tool.d.ts.map

package/dist/todoist-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"todoist-tool.d.ts","sourceRoot":"","sources":["../src/todoist-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AACpG,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAE5B;;;GAGG;AACH,KAAK,WAAW,CACZ,MAAM,SAAS,CAAC,CAAC,WAAW,EAC5B,MAAM,SAAS,CAAC,CAAC,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IACpD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,CAAA;AAEvC;;;GAGG;AACH,KAAK,cAAc,GAAG,UAAU,CAAC,UAAU,CAAC,CAAA;AAE5C,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,uBAAuB,EAAE,WAAW,EAAE,CAAA"}

package/dist/tool-execution-error.d.ts

@@ -0,0 +1,27 @@
+export declare class DueStringParseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Compact single-line variant of {@link formatToolExecutionError} for batch
+ * tools that report per-item failures. Unlike `error.message` (which for SDK
+ * errors is just "HTTP 403: Forbidden"), this preserves the API error signals
+ * (status, code, tag) so failures like MAX_ITEMS_LIMIT_REACHED stay
+ * recognizable after aggregation.
+ */
+export declare function formatBatchItemError(error: unknown): string;
+/**
+ * Return task-specific recovery guidance only when Todoist rejected a supplied
+ * natural-language due string. The REST API currently returns the generic
+ * text "Invalid date format" without a stable field/tag, so callers must pass
+ * the known field context before we use that fallback.
+ */
+export declare function formatDueStringParseError(error: unknown, { taskContent, dueString, deadlineDate, }: {
+    taskContent: string;
+    dueString: string | undefined;
+    deadlineDate?: string;
+}): string | undefined;
+/**
+ * Format tool execution errors in a consistent, actionable format.
+ */
+export declare function formatToolExecutionError(error: unknown): string;
+//# sourceMappingURL=tool-execution-error.d.ts.map

package/dist/tool-execution-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-execution-error.d.ts","sourceRoot":"","sources":["../src/tool-execution-error.ts"],"names":[],"mappings":"AA+fA,qBAAa,mBAAoB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI9B;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAkB3D;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACrC,KAAK,EAAE,OAAO,EACd,EACI,WAAW,EACX,SAAS,EACT,YAAY,GACf,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,GACjF,MAAM,GAAG,SAAS,CA+BpB;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAe/D"}

package/dist/tool-helpers.d.ts

@@ -0,0 +1,318 @@
+import { isPersonalProject, isWorkspaceProject, ActivityEvent, ColorKey, Comment, CurrentUser, Label, MoveTaskArgs, PersonalProject, Reminder, Section, Task, TodoistApi, WorkspaceProject } from '@doist/todoist-sdk';
+export { appendToQuery, buildResponsibleUserQueryFilter, filterTasksByResponsibleUser, RESPONSIBLE_USER_FILTERING, type ResponsibleUserFiltering, resolveResponsibleUser, } from './filter-helpers.js';
+export type Project = PersonalProject | WorkspaceProject;
+export { isPersonalProject, isWorkspaceProject };
+/**
+ * Checks if a project ID represents the inbox (case-insensitive).
+ *
+ * @param projectId - The project ID to check
+ * @returns true if the project ID is inbox-like
+ */
+export declare function isInboxProjectId(projectId: string | undefined): boolean;
+/**
+ * Resolves "inbox" project ID to actual inbox project ID (case-insensitive).
+ * Only makes API calls when necessary (when projectId is inbox-like and user not provided).
+ *
+ * @param args - Configuration object
+ * @param args.projectId - The project ID to resolve (may be "inbox", "Inbox", etc.)
+ * @param args.user - The current user object (if already fetched)
+ * @param args.client - The API client (if user needs to be fetched)
+ * @returns Promise resolving to the resolved project ID
+ */
+export declare function resolveInboxProjectId(args: {
+    projectId: string | undefined;
+    user?: CurrentUser;
+    client?: TodoistApi;
+}): Promise<string | undefined>;
+/**
+ * Generic pagination utility for Todoist API methods
+ *
+ * Recursively fetches all pages of data from paginated Todoist API endpoints.
+ *
+ * @template TArgs - The type of arguments accepted by the API method
+ * @template TResponse - The type of response returned by the API method
+ * @template TResult - The type of individual result items in the response
+ *
+ * @param options - Configuration options
+ * @param options.apiMethod - The Todoist API method to call (e.g., todoistApi.getLabels)
+ * @param options.args - Initial arguments to pass to the API method (excluding cursor and limit)
+ * @param options.limit - Number of items to fetch per page (default: 100)
+ * @returns Promise resolving to an array of all result items across all pages
+ *
+ * @example
+ * const allLabels = await fetchAllPages({
+ *   apiMethod: (args) => todoistApi.getLabels(args),
+ *   args: {},
+ *   limit: 100
+ * })
+ */
+export declare function fetchAllPages<TArgs extends {
+    cursor?: string | null;
+    limit?: number;
+}, TResponse extends {
+    results: TResult[];
+    nextCursor: string | null;
+}, TResult>(options: {
+    apiMethod: (args: TArgs) => Promise<TResponse>;
+    args?: Omit<TArgs, 'cursor' | 'limit'>;
+    limit?: number;
+}): Promise<TResult[]>;
+/**
+ * Wraps a search query with wildcards for substring matching.
+ * If the query already contains unescaped wildcards, it is returned as-is
+ * to preserve intentional wildcard patterns (e.g. prefix matching with "work*").
+ */
+export declare function toWildcardQuery(query: string): string;
+/**
+ * Searches projects by name and fetches all matching pages.
+ *
+ * @param client - The Todoist API client
+ * @param query - The search query string
+ * @returns Promise resolving to array of matching projects
+ */
+export declare function searchAllProjects(client: TodoistApi, query: string): Promise<Project[]>;
+/**
+ * Fetches all active (non-archived) projects across every page.
+ *
+ * Each page is retried on its own, so a transient failure part-way through does
+ * not refetch the pages already read.
+ *
+ * @param client - The Todoist API client
+ * @returns Promise resolving to array of active projects
+ */
+export declare function fetchAllActiveProjects(client: TodoistApi): Promise<Project[]>;
+/**
+ * Fetches all archived projects across every page.
+ *
+ * The API has no server-side search for archived projects, so callers that need
+ * to filter by name should fetch all and filter client-side with
+ * {@link matchesWildcardQuery}.
+ *
+ * @param client - The Todoist API client
+ * @returns Promise resolving to array of archived projects
+ */
+export declare function fetchAllArchivedProjects(client: TodoistApi): Promise<Project[]>;
+/**
+ * Compiles a search query into a case-insensitive RegExp using the same wildcard
+ * semantics as server-side search (see {@link toWildcardQuery}): `*` matches any
+ * sequence, `\*` is a literal asterisk, and every other character (backslashes
+ * included) is matched literally. A query without an unescaped `*` matches as a
+ * substring; otherwise the whole name must match.
+ *
+ * Compile once and reuse the result when filtering many names (e.g. archived
+ * projects), rather than calling {@link matchesWildcardQuery} per item.
+ */
+export declare function compileWildcardQuery(query: string): RegExp;
+/**
+ * Tests whether a name matches a search query using the same wildcard semantics
+ * as server-side search. Used for client-side filtering where the API exposes no
+ * search endpoint (e.g. archived projects). For bulk filtering, prefer
+ * {@link compileWildcardQuery} so the pattern is compiled only once.
+ */
+export declare function matchesWildcardQuery(name: string, query: string): boolean;
+/**
+ * Searches labels by name and fetches all matching pages.
+ *
+ * @param client - The Todoist API client
+ * @param query - The search query string
+ * @returns Promise resolving to array of matching labels
+ */
+export declare function searchAllLabels(client: TodoistApi, query: string): Promise<Label[]>;
+export declare function fetchAllSharedLabels(client: TodoistApi): Promise<string[]>;
+/**
+ * Searches sections by name (optionally scoped to a project) and fetches all matching pages.
+ *
+ * @param client - The Todoist API client
+ * @param query - The search query string
+ * @param projectId - Optional project ID to scope the search
+ * @returns Promise resolving to array of matching sections
+ */
+export declare function searchAllSections(client: TodoistApi, query: string, projectId?: string): Promise<Section[]>;
+/**
+ * Creates a MoveTaskArgs object from move parameters, validating that exactly one is provided.
+ * @param taskId - The task ID (used for error messages)
+ * @param projectId - Optional project ID to move to
+ * @param sectionId - Optional section ID to move to
+ * @param parentId - Optional parent ID to move to
+ * @returns MoveTaskArgs object with exactly one destination
+ * @throws Error if multiple move parameters are provided or none are provided
+ */
+export declare function createMoveTaskArgs(taskId: string, projectId?: string, sectionId?: string, parentId?: string): MoveTaskArgs;
+/**
+ * Map a single Todoist task to a more structured format, for LLM consumption.
+ * @param task - The task to map.
+ * @returns The mapped task.
+ */
+declare function mapTask(task: Task): {
+    id: string;
+    content: string;
+    description: string;
+    dueDate: string | undefined;
+    recurring: string | boolean;
+    deadlineDate: string | undefined;
+    priority: "p1" | "p2" | "p3" | "p4";
+    projectId: string;
+    sectionId: string | undefined;
+    parentId: string | undefined;
+    labels: string[];
+    duration: string | undefined;
+    responsibleUid: string | undefined;
+    assignedByUid: string | undefined;
+    isDeleted: true | undefined;
+    checked: boolean;
+    completedAt: string | undefined;
+    addedAt: string | undefined;
+};
+type MappedTask = ReturnType<typeof mapTask>;
+/**
+ * Map a single Todoist project to a more structured format, for LLM consumption.
+ * @param project - The project to map.
+ * @returns The mapped project.
+ */
+declare function mapProject(project: Project): {
+    id: string;
+    name: string;
+    description: string;
+    color: ColorKey;
+    isFavorite: boolean;
+    isShared: boolean;
+    parentId: string | undefined;
+    inboxProject: boolean;
+    viewStyle: string;
+    workspaceId: string | undefined;
+    folderId: string | undefined;
+    childOrder: number;
+    isArchived: boolean;
+};
+/**
+ * Map a single Todoist comment to a more structured format, for LLM consumption.
+ * @param comment - The comment to map.
+ * @returns The mapped comment.
+ */
+declare function mapComment(comment: Comment): {
+    id: string;
+    taskId: string | undefined;
+    projectId: string | undefined;
+    content: string;
+    postedAt: string;
+    postedUid: string;
+    notifiedUserIds: string[] | undefined;
+    fileAttachment: {
+        resourceType: string;
+        fileName: string | undefined;
+        fileSize: number | undefined;
+        fileType: string | undefined;
+        fileUrl: string | undefined;
+        fileDuration: number | undefined;
+        uploadState: "pending" | "completed" | undefined;
+        url: string | undefined;
+        title: string | undefined;
+        image: string | undefined;
+        imageWidth: number | undefined;
+        imageHeight: number | undefined;
+    } | undefined;
+};
+/**
+ * Map a single Todoist activity event to a more structured format, for LLM consumption.
+ * @param event - The activity event to map.
+ * @returns The mapped activity event.
+ */
+declare function mapActivityEvent(event: ActivityEvent): {
+    id: string | undefined;
+    objectType: string;
+    objectId: string;
+    eventType: string;
+    eventDate: string;
+    parentProjectId: string | undefined;
+    parentItemId: string | undefined;
+    initiatorId: string | undefined;
+    extraData: Record<string, any> | undefined;
+};
+/**
+ * Normalize first-page cursor values commonly emitted by schema-driven clients.
+ */
+export declare function normalizePaginationCursor(cursor: string | undefined): string | undefined;
+declare function getTasksByFilter({ client, query, limit, cursor, }: {
+    client: TodoistApi;
+    query: string;
+    limit: number | undefined;
+    cursor: string | undefined;
+}): Promise<{
+    tasks: {
+        id: string;
+        content: string;
+        description: string;
+        dueDate: string | undefined;
+        recurring: string | boolean;
+        deadlineDate: string | undefined;
+        priority: "p1" | "p2" | "p3" | "p4";
+        projectId: string;
+        sectionId: string | undefined;
+        parentId: string | undefined;
+        labels: string[];
+        duration: string | undefined;
+        responsibleUid: string | undefined;
+        assignedByUid: string | undefined;
+        isDeleted: true | undefined;
+        checked: boolean;
+        completedAt: string | undefined;
+        addedAt: string | undefined;
+    }[];
+    nextCursor: string | null;
+}>;
+/**
+ * Map a single Todoist reminder to a more structured format, for LLM consumption.
+ * Normalizes SDK's `itemId` to `taskId` for consistency with other tools.
+ * @param reminder - The reminder to map (any of the 3 types).
+ * @returns The mapped reminder.
+ */
+declare function mapReminder(reminder: Reminder): {
+    minuteOffset: number;
+    due: {
+        isRecurring: boolean;
+        string: string;
+        date: string;
+        datetime: string | undefined;
+        timezone: string | undefined;
+    } | undefined;
+    isUrgent: boolean | undefined;
+    id: string;
+    taskId: string;
+    type: "location" | "absolute" | "relative";
+    notifyUid: string;
+} | {
+    due: {
+        isRecurring: boolean;
+        string: string;
+        date: string;
+        datetime: string | undefined;
+        timezone: string | undefined;
+    };
+    isUrgent: boolean | undefined;
+    id: string;
+    taskId: string;
+    type: "location" | "absolute" | "relative";
+    notifyUid: string;
+} | {
+    name: string;
+    locLat: string;
+    locLong: string;
+    locTrigger: "on_enter" | "on_leave";
+    radius: number;
+    id: string;
+    taskId: string;
+    type: "location" | "absolute" | "relative";
+    notifyUid: string;
+};
+/**
+ * Count reminders by category: time-based (relative/absolute) and location.
+ */
+declare function countRemindersByType(reminders: {
+    type: string;
+}[]): {
+    timeBasedCount: number;
+    locationCount: number;
+};
+export type { MappedTask };
+export { countRemindersByType, getTasksByFilter, mapActivityEvent, mapComment, mapProject, mapReminder, mapTask, };
+//# sourceMappingURL=tool-helpers.d.ts.map

package/dist/tool-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-helpers.d.ts","sourceRoot":"","sources":["../src/tool-helpers.ts"],"names":[],"mappings":"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"}