@mindtnv/todoist-cli 0.4.0 → 0.5.0

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@mindtnv/todoist-cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A fast, keyboard-driven Todoist client for the terminal — interactive TUI and scriptable CLI",
   "type": "module",
   "bin": {
-    "todoist": "dist/index.js"
+    "todoist": "src/cli/index.ts"
   },
   "files": [
-    "dist",
+    "src",
     "marketplace.json"
   ],
   "scripts": {
-    "dev": "bun run src/cli/index.ts",
-    "build": "bun build src/cli/index.ts --outdir dist --target node --packages external --external react-devtools-core",
+    "dev": "TODOIST_CLI_CONFIG_DIR=$HOME/.config/todoist-cli-dev bun run src/cli/index.ts",
+    "build": "bun build src/cli/index.ts --outdir dist --target bun --packages external --external react-devtools-core",
     "prepublishOnly": "bun run build",
     "test": "bun test"
   },
@@ -37,7 +37,7 @@
   },
   "homepage": "https://github.com/mindtnv/todoist-cli#readme",
   "engines": {
-    "node": ">=18"
+    "bun": ">=1.0"
   },
   "dependencies": {
     "@iarna/toml": "^2.2.5",

package/src/api/activity.ts

@@ -0,0 +1,8 @@
+import { api } from "./client.ts";
+import type { ActivityEvent } from "./types.ts";
+
+export async function getActivity(limit?: number): Promise<ActivityEvent[]> {
+  const params: Record<string, string> = {};
+  if (limit) params.limit = String(limit);
+  return api.get<ActivityEvent[]>("/activities", params);
+}

package/src/api/client.ts

@@ -0,0 +1,214 @@
+import { requireToken } from "../config/index.ts";
+
+const BASE_URL = "https://api.todoist.com/api/v1";
+
+const MAX_RETRIES = 3;
+const BASE_BACKOFF_MS = 1000;
+const RATE_LIMIT_BASE_BACKOFF_MS = 5000;
+const REQUEST_TIMEOUT_MS = 30_000;
+const JITTER_FACTOR = 0.25;
+
+interface PaginatedResponse<T> {
+  results: T[];
+  next_cursor: string | null;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Add ±25% jitter to a delay value. */
+function addJitter(ms: number): number {
+  const jitter = ms * JITTER_FACTOR * (2 * Math.random() - 1);
+  return Math.max(0, ms + jitter);
+}
+
+/** Check if an error is a network/connectivity error worth retrying. */
+function isNetworkError(err: unknown): boolean {
+  if (err instanceof TypeError) return true;
+  if (err instanceof Error && err.message.includes("fetch failed")) return true;
+  return false;
+}
+
+/** Check if an error is a timeout abort. */
+function isTimeoutError(err: unknown): boolean {
+  if (err instanceof DOMException && err.name === "AbortError") return true;
+  if (err instanceof Error && err.name === "AbortError") return true;
+  return false;
+}
+
+class TodoistClient {
+  private get headers(): Record<string, string> {
+    return {
+      Authorization: `Bearer ${requireToken()}`,
+      "Content-Type": "application/json",
+    };
+  }
+
+  async get<T>(path: string, params?: Record<string, string>): Promise<T> {
+    let url = `${BASE_URL}${path}`;
+    if (params) {
+      const query = new URLSearchParams(params).toString();
+      if (query) url += `?${query}`;
+    }
+    const res = await this.fetchWithRetry(url, { headers: this.headers });
+    const data = await this.handleResponse<T | PaginatedResponse<unknown>>(res);
+    if (data && typeof data === "object" && "results" in data && "next_cursor" in data) {
+      return (data as PaginatedResponse<unknown>).results as T;
+    }
+    return data as T;
+  }
+
+  async post<T>(path: string, body?: Record<string, unknown>): Promise<T> {
+    const res = await this.fetchWithRetry(`${BASE_URL}${path}`, {
+      method: "POST",
+      headers: this.headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    return this.handleResponse<T>(res);
+  }
+
+  async del(path: string): Promise<void> {
+    const res = await this.fetchWithRetry(`${BASE_URL}${path}`, {
+      method: "DELETE",
+      headers: this.headers,
+    });
+    if (!res.ok) await this.throwError(res);
+    await res.text();
+  }
+
+  /**
+   * Fetch with retry, exponential backoff, rate-limit handling, and timeout.
+   * Retries on: network errors, timeouts, 5xx responses, and 429 rate limits.
+   * Does NOT retry on 4xx errors (except 429).
+   */
+  private async fetchWithRetry(url: string, init: RequestInit): Promise<Response> {
+    let lastError: Error | undefined;
+    let lastRetryAfter: number | undefined;
+    let skipNextBackoff = false;
+
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      // Wait before retrying (skip delay on first attempt and after 429 which has its own delay)
+      if (attempt > 0 && !skipNextBackoff) {
+        const backoff = BASE_BACKOFF_MS * Math.pow(2, attempt - 1);
+        const delay = addJitter(backoff);
+        process.stderr.write(
+          `[todoist-cli] Retry ${attempt}/${MAX_RETRIES} in ${Math.round(delay)}ms...\n`,
+        );
+        await sleep(delay);
+      }
+      skipNextBackoff = false;
+
+      // Set up per-request timeout via AbortController
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+      const fetchInit: RequestInit = {
+        ...init,
+        signal: controller.signal,
+      };
+
+      let res: Response;
+      try {
+        res = await fetch(url, fetchInit);
+      } catch (err) {
+        clearTimeout(timeoutId);
+
+        if (isTimeoutError(err)) {
+          lastError = new Error(`Request timed out after 30s`);
+          continue; // retry on timeout
+        }
+
+        if (isNetworkError(err)) {
+          lastError = new Error(
+            "Network error: unable to reach Todoist API. Check your connection.",
+          );
+          continue; // retry on network error
+        }
+
+        throw err; // unknown error, don't retry
+      } finally {
+        clearTimeout(timeoutId);
+      }
+
+      // Success — return response
+      if (res.ok) {
+        return res;
+      }
+
+      // 429 Rate Limit — retry with Retry-After header or rate-limit backoff
+      if (res.status === 429) {
+        const retryAfterHeader = res.headers.get("Retry-After");
+        let waitMs: number;
+
+        if (retryAfterHeader) {
+          const retryAfterSec = parseInt(retryAfterHeader, 10);
+          waitMs = (Number.isNaN(retryAfterSec) ? RATE_LIMIT_BASE_BACKOFF_MS / 1000 : retryAfterSec) * 1000;
+        } else {
+          waitMs = RATE_LIMIT_BASE_BACKOFF_MS * Math.pow(2, attempt);
+        }
+
+        lastRetryAfter = Math.ceil(waitMs / 1000);
+
+        if (attempt < MAX_RETRIES) {
+          const delay = addJitter(waitMs);
+          process.stderr.write(
+            `[todoist-cli] Rate limited (429). Retry ${attempt + 1}/${MAX_RETRIES} in ${Math.round(delay)}ms...\n`,
+          );
+          await sleep(delay);
+          skipNextBackoff = true; // already waited with rate-limit-specific delay
+          continue;
+        }
+
+        throw new Error(
+          `Rate limit exceeded. Retried ${MAX_RETRIES} times. Try again in ${lastRetryAfter} seconds.`,
+        );
+      }
+
+      // 5xx Server Error — retry
+      if (res.status >= 500) {
+        lastError = new Error(`API error ${res.status}: ${res.statusText}`);
+        continue;
+      }
+
+      // 4xx Client Error (non-429) — do NOT retry, return for throwError handling
+      return res;
+    }
+
+    // All retries exhausted
+    throw lastError ?? new Error("Request failed after all retries.");
+  }
+
+  private async handleResponse<T>(res: Response): Promise<T> {
+    if (!res.ok) await this.throwError(res);
+    const text = await res.text();
+    if (!text) return undefined as T;
+    return JSON.parse(text) as T;
+  }
+
+  private async throwError(res: Response): Promise<never> {
+    if (res.status === 401) {
+      throw new Error("Authentication failed. Run `todoist auth` to set a valid API token.");
+    }
+    if (res.status === 429) {
+      throw new Error("Rate limit exceeded. Please wait and try again.");
+    }
+    let detail = res.statusText;
+    try {
+      const body = await res.text();
+      if (body) {
+        try {
+          const parsed = JSON.parse(body);
+          if (parsed.error) detail = parsed.error;
+          else detail = body;
+        } catch {
+          detail = body;
+        }
+      }
+    } catch {
+      // use statusText as fallback
+    }
+    throw new Error(`API error ${res.status}: ${detail}`);
+  }
+}
+
+export const api = new TodoistClient();

package/src/api/comments.ts

@@ -0,0 +1,18 @@
+import { api } from "./client.ts";
+import type { Comment, CreateCommentParams, UpdateCommentParams } from "./types.ts";
+
+export async function getComments(taskId: string): Promise<Comment[]> {
+  return api.get<Comment[]>("/comments", { task_id: taskId });
+}
+
+export async function createComment(params: CreateCommentParams): Promise<Comment> {
+  return api.post<Comment>("/comments", params as unknown as Record<string, unknown>);
+}
+
+export async function updateComment(id: string, params: UpdateCommentParams): Promise<Comment> {
+  return api.post<Comment>(`/comments/${id}`, params as unknown as Record<string, unknown>);
+}
+
+export async function deleteComment(id: string): Promise<void> {
+  await api.del(`/comments/${id}`);
+}

package/src/api/completed.ts

@@ -0,0 +1,15 @@
+import { api } from "./client.ts";
+import type { CompletedTask } from "./types.ts";
+
+interface CompletedResponse {
+  items: CompletedTask[];
+  projects: Record<string, unknown>;
+  sections: Record<string, unknown>;
+}
+
+export async function getCompletedTasks(since?: string): Promise<CompletedTask[]> {
+  const params: Record<string, string> = {};
+  if (since) params.since = since;
+  const data = await api.get<CompletedResponse>("/tasks/completed", params);
+  return data.items ?? [];
+}

package/src/api/labels.ts

@@ -0,0 +1,18 @@
+import { api } from "./client.ts";
+import type { Label, CreateLabelParams, UpdateLabelParams } from "./types.ts";
+
+export async function getLabels(): Promise<Label[]> {
+  return api.get<Label[]>("/labels");
+}
+
+export async function createLabel(params: CreateLabelParams): Promise<Label> {
+  return api.post<Label>("/labels", params as unknown as Record<string, unknown>);
+}
+
+export async function updateLabel(id: string, params: UpdateLabelParams): Promise<Label> {
+  return api.post<Label>(`/labels/${id}`, params as unknown as Record<string, unknown>);
+}
+
+export async function deleteLabel(id: string): Promise<void> {
+  await api.del(`/labels/${id}`);
+}

package/src/api/projects.ts

@@ -0,0 +1,22 @@
+import { api } from "./client.ts";
+import type { Project, CreateProjectParams, UpdateProjectParams } from "./types.ts";
+
+export async function getProjects(): Promise<Project[]> {
+  return api.get<Project[]>("/projects");
+}
+
+export async function getProject(id: string): Promise<Project> {
+  return api.get<Project>(`/projects/${id}`);
+}
+
+export async function createProject(params: CreateProjectParams): Promise<Project> {
+  return api.post<Project>("/projects", params as unknown as Record<string, unknown>);
+}
+
+export async function updateProject(id: string, params: UpdateProjectParams): Promise<Project> {
+  return api.post<Project>(`/projects/${id}`, params as unknown as Record<string, unknown>);
+}
+
+export async function deleteProject(id: string): Promise<void> {
+  await api.del(`/projects/${id}`);
+}

package/src/api/sections.ts

@@ -0,0 +1,20 @@
+import { api } from "./client.ts";
+import type { Section, CreateSectionParams, UpdateSectionParams } from "./types.ts";
+
+export async function getSections(projectId?: string): Promise<Section[]> {
+  const params: Record<string, string> = {};
+  if (projectId) params.project_id = projectId;
+  return api.get<Section[]>("/sections", params);
+}
+
+export async function createSection(params: CreateSectionParams): Promise<Section> {
+  return api.post<Section>("/sections", params as unknown as Record<string, unknown>);
+}
+
+export async function updateSection(id: string, params: UpdateSectionParams): Promise<Section> {
+  return api.post<Section>(`/sections/${id}`, params as unknown as Record<string, unknown>);
+}
+
+export async function deleteSection(id: string): Promise<void> {
+  await api.del(`/sections/${id}`);
+}

package/src/api/stats.ts

@@ -0,0 +1,38 @@
+import { api } from "./client.ts";
+import type { UserStats, DayStats, WeekStats } from "./types.ts";
+
+interface UserResponse {
+  karma: number;
+  karma_trend: string;
+  completed_today: number;
+  completed_count: number;
+}
+
+interface SyncStatsResponse {
+  stats?: {
+    completed_count: number;
+    days_items: Array<{ date: string; total_completed: number }>;
+    week_items: Array<{ from: string; to: string; total_completed: number }>;
+  };
+}
+
+export async function getStats(): Promise<UserStats> {
+  const [user, syncData] = await Promise.all([
+    api.get<UserResponse>("/user"),
+    api.post<SyncStatsResponse>("/sync", {
+      resource_types: ["stats"],
+      sync_token: "*",
+    }),
+  ]);
+
+  const stats = syncData.stats;
+
+  return {
+    completed_count: user.completed_count,
+    karma: user.karma,
+    karma_trend: user.karma_trend,
+    completed_today: user.completed_today,
+    days_items: (stats?.days_items ?? []) as DayStats[],
+    week_items: (stats?.week_items ?? []) as WeekStats[],
+  };
+}

package/src/api/tasks.ts

@@ -0,0 +1,34 @@
+import { api } from "./client.ts";
+import type { Task, TaskFilter, CreateTaskParams, UpdateTaskParams } from "./types.ts";
+
+export async function getTasks(filter?: TaskFilter): Promise<Task[]> {
+  const params: Record<string, string> = {};
+  if (filter?.project_id) params.project_id = filter.project_id;
+  if (filter?.label) params.label = filter.label;
+  if (filter?.filter) params.filter = filter.filter;
+  return api.get<Task[]>("/tasks", params);
+}
+
+export async function getTask(id: string): Promise<Task> {
+  return api.get<Task>(`/tasks/${id}`);
+}
+
+export async function createTask(params: CreateTaskParams): Promise<Task> {
+  return api.post<Task>("/tasks", params as unknown as Record<string, unknown>);
+}
+
+export async function updateTask(id: string, params: UpdateTaskParams): Promise<Task> {
+  return api.post<Task>(`/tasks/${id}`, params as unknown as Record<string, unknown>);
+}
+
+export async function closeTask(id: string): Promise<void> {
+  await api.post<void>(`/tasks/${id}/close`);
+}
+
+export async function reopenTask(id: string): Promise<void> {
+  await api.post<void>(`/tasks/${id}/reopen`);
+}
+
+export async function deleteTask(id: string): Promise<void> {
+  await api.del(`/tasks/${id}`);
+}

package/src/api/types.ts

@@ -0,0 +1,202 @@
+export type Priority = 1 | 2 | 3 | 4;
+
+export interface Deadline {
+  date: string; // YYYY-MM-DD
+}
+
+export interface Task {
+  id: string;
+  content: string;
+  description: string;
+  project_id: string;
+  section_id: string | null;
+  parent_id: string | null;
+  order: number;
+  priority: Priority;
+  due: Due | null;
+  deadline: Deadline | null;
+  labels: string[];
+  assignee_id: string | null;
+  is_completed: boolean;
+  created_at: string;
+  comment_count: number;
+  creator_id: string;
+  url: string;
+}
+
+export interface Due {
+  date: string;
+  string: string;
+  lang: string;
+  is_recurring: boolean;
+  datetime: string | null;
+  timezone: string | null;
+}
+
+export interface Project {
+  id: string;
+  name: string;
+  color: string;
+  parent_id: string | null;
+  order: number;
+  comment_count: number;
+  is_shared: boolean;
+  is_favorite: boolean;
+  is_inbox_project: boolean;
+  view_style: "list" | "board";
+  url: string;
+}
+
+export interface Label {
+  id: string;
+  name: string;
+  color: string;
+  order: number;
+  is_favorite: boolean;
+}
+
+export interface Comment {
+  id: string;
+  task_id: string;
+  content: string;
+  posted_at: string;
+}
+
+export interface Section {
+  id: string;
+  project_id: string;
+  order: number;
+  name: string;
+}
+
+export interface CreateTaskParams {
+  content: string;
+  description?: string;
+  project_id?: string;
+  priority?: Priority;
+  due_string?: string;
+  due_date?: string;
+  deadline_date?: string | null;
+  labels?: string[];
+  parent_id?: string;
+  section_id?: string;
+}
+
+export interface UpdateTaskParams {
+  content?: string;
+  description?: string;
+  priority?: Priority;
+  due_string?: string;
+  due_date?: string;
+  deadline_date?: string | null;
+  labels?: string[];
+  project_id?: string;
+  section_id?: string;
+}
+
+export interface UpdateProjectParams {
+  name?: string;
+  color?: string;
+  is_favorite?: boolean;
+  view_style?: "list" | "board";
+}
+
+export interface UpdateLabelParams {
+  name?: string;
+  color?: string;
+  order?: number;
+  is_favorite?: boolean;
+}
+
+export interface UpdateSectionParams {
+  name?: string;
+}
+
+export interface UpdateCommentParams {
+  content?: string;
+}
+
+export interface CreateProjectParams {
+  name: string;
+  color?: string;
+  parent_id?: string;
+  view_style?: "list" | "board";
+}
+
+export interface CreateLabelParams {
+  name: string;
+  color?: string;
+  order?: number;
+}
+
+export interface CreateCommentParams {
+  task_id: string;
+  content: string;
+}
+
+export interface TaskFilter {
+  project_id?: string;
+  label?: string;
+  filter?: string;
+}
+
+export interface ApiError {
+  error: string;
+  http_code: number;
+}
+
+export interface TaskTemplate {
+  name: string;
+  content: string;
+  description?: string;
+  priority?: Priority;
+  labels?: string[];
+  due_string?: string;
+  deadline_date?: string;
+}
+
+export interface CreateSectionParams {
+  name: string;
+  project_id: string;
+  order?: number;
+}
+
+export interface CompletedTask {
+  id: string;
+  task_id: string;
+  content: string;
+  project_id: string;
+  section_id: string | null;
+  completed_at: string;
+  user_id: string;
+  note_count: number;
+}
+
+export interface ActivityEvent {
+  id: string;
+  object_type: string;
+  object_id: string;
+  event_type: string;
+  event_date: string;
+  extra_data: Record<string, unknown>;
+}
+
+export interface UserStats {
+  completed_count: number;
+  completed_today: number;
+  karma: number;
+  karma_trend: string;
+  days_items: DayStats[];
+  week_items: WeekStats[];
+}
+
+export interface DayStats {
+  date: string;
+  total_completed: number;
+}
+
+export interface WeekStats {
+  from: string;
+  to: string;
+  total_completed: number;
+}

package/src/cli/auth.ts

@@ -0,0 +1,40 @@
+import type { Command } from "commander";
+import chalk from "chalk";
+import { setToken } from "../config/index.ts";
+import { cliExit } from "../utils/exit.ts";
+import { getProjects } from "../api/projects.ts";
+import { createInterface } from "readline";
+
+export function registerAuthCommand(program: Command): void {
+  program
+    .command("auth")
+    .description("Authenticate with your Todoist API token")
+    .action(async () => {
+      const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+      });
+
+      const token = await new Promise<string>((resolve) => {
+        rl.question("Enter your Todoist API token: ", (answer) => {
+          rl.close();
+          resolve(answer.trim());
+        });
+      });
+
+      if (!token) {
+        console.error(chalk.red("Token cannot be empty."));
+        cliExit(1);
+      }
+
+      setToken(token);
+
+      try {
+        const projects = await getProjects();
+        console.log(chalk.green(`Authenticated successfully. Found ${projects.length} project(s).`));
+      } catch {
+        console.error(chalk.red("Authentication failed. The token may be invalid."));
+        cliExit(1);
+      }
+    });
+}