@azysinovacao/todoist-client

Cliente JS da API v1 unificada do Todoist. Cobertura ~100% do REST (102 ops) + Sync API + compostos. Zero dependências (usa fetch/FormData/Blob nativos do Node 18+), dual CJS/ESM. Gotchas embutidos (D1–D10).

Status: desenvolvida e testada de ponta a ponta contra a API real (2026-06-07): bateria completa 74/74 métodos PASS, ambiente descartável limpo (ver 2026-06-07_testes_todoist-api.md §BATERIA 6). Endereça a lacuna da Piece oficial do Activepieces (parcial) e da camada do MCP oficial (curada). NÃO publicada no npm nesta rodada — ver "Publicar" abaixo.

Uso

const { createTodoist } = require("@azysinovacao/todoist-client"); // ou: import { createTodoist } from "@azysinovacao/todoist-client"
const td = createTodoist(process.env.TODOIST_TOKEN);

await td.getUser();
const p = await td.addProject({ name: "Trabalho", color: "blue" });
const t = await td.addTask({ content: "Comprar pão", project_id: p.id, priority: 4, due_string: "amanhã 9h" });
await td.updateTask(t.id, { description: "integral" });   // patch parcial seguro (D8)
await td.commentWithFile({ task_id: t.id }, "nota fiscal", { name: "nf.pdf", mimeType: "application/pdf", base64: "<...>" });

Gotchas embutidos

• priority é INVERTIDO (D3): na API 4 = mais alta, 1 = mais baixa. Helpers td.uiPriority(api) e td.apiPriority(ui) convertem (UI P1 = API 4).
• IDs são string (D4) — Label/Filter são strings numéricas; demais são alfanuméricos. A lib trata tudo como string.
• update* é patch parcial seguro (D8): envie só o que muda; o resto é preservado (sem GET-merge).
• color aceita nome (berry_red…taupe) ou inteiro (30–49) (D7).
• completedByCompletionDate/ByDueDate retornam a chave items (D5).
• Paginação: métodos getAll* seguem next_cursor; ou use td.paginate(method, path, params, listKey).
• 429: auto-retry com backoff (respeita Retry-After).
• commentWithFile(target, content, file) = upload + comentário com anexo numa chamada (target = {task_id} ou {project_id}).
• Filtros salvos só via Sync: td.addFilter({name,query,color}) / td.deleteFilter(id).
• Escotilha: td.raw(method, path, { params, json, form }) para qualquer endpoint.

Métodos (cobertura ~100%)

• Tasks: addTask, getTasks, getAllTasks, getTask, updateTask, deleteTask, moveTask, closeTask, reopenTask, quickAdd, getTasksByFilter, completedByCompletionDate, completedByDueDate
• Projects: addProject, getProjects, getAllProjects, getProject, updateProject, deleteProject, archiveProject, unarchiveProject, joinProject, getProjectCollaborators, getArchivedProjects, searchProjects, getProjectPermissions
• Sections: addSection, getSections, getSection, updateSection, deleteSection, archiveSection, unarchiveSection, searchSections
• Labels: addLabel, getLabels, getLabel, updateLabel, deleteLabel, searchLabels, getSharedLabels, renameSharedLabel, removeSharedLabel
• Comments: addComment, getComments, getComment, updateComment, deleteComment · composto commentWithFile
• Reminders: addReminder, getReminders, getReminder, updateReminder, deleteReminder
• Location reminders: addLocationReminder, getLocationReminders, getLocationReminder, updateLocationReminder, deleteLocationReminder
• Folders: addFolder, getFolders, getFolder, updateFolder, deleteFolder
• Uploads: uploadFile, deleteUpload
• Templates: exportTemplateUrl, exportTemplateFile, createProjectFromFile, importIntoProjectFromFile, importFromTemplateId
• User/Activity/Backups: getUser, getProductivityStats, updateNotificationSetting, getActivities, getBackups, downloadBackup
• Emails/Ids: getOrCreateEmail, disableEmail, getIdMappings
• Workspaces: createWorkspace, getWorkspaces, getWorkspace, updateWorkspace, deleteWorkspace, getWorkspaceUsers, inviteWorkspaceUsers, updateWorkspaceUser, removeWorkspaceUser, getWorkspaceActiveProjects, getWorkspaceArchivedProjects, getPlanDetails, joinWorkspace, updateWorkspaceLogo, getInvitations, getAllInvitations, deleteInvitation, acceptInvitation, rejectInvitation
• Auth (destrutivo): migratePersonalToken, revokeAccessToken, revokeToken
• Billing: getSubscriptionInfo, reactivatePlan, cancelPlan
• Sync: sync, syncCommand, addFilter, deleteFilter
• Utilidades: raw, paginate, uiPriority, apiPriority, getGotchas

Publicar (npm)

@azysinovacao exige a org no npm. Publicar com token Granular Read/Write ou Classic Automation (Publish dá 403 por 2FA), via .npmrc temporário fora do vault: npm publish --access public. 1º publish de escopo novo pode levar minutos para propagar. Ver guia §6a.