@doist/todoist-sdk 9.2.0 → 9.4.0

package/dist/esm/clients/section-client.js

@@ -1,8 +1,7 @@
-import { z } from 'zod';
 import { ENDPOINT_REST_SECTIONS, ENDPOINT_REST_SECTIONS_SEARCH, SECTION_ARCHIVE, SECTION_UNARCHIVE, } from '../consts/endpoints.js';
 import { isSuccess, request } from '../transport/http-client.js';
 import { generatePath } from '../utils/request-helpers.js';
-import { validateSection, validateSectionArray } from '../utils/validators.js';
+import { IdSchema, validateSection, validateSectionArray } from '../utils/validators.js';
 import { BaseClient } from './base-client.js';
 /**
  * Internal sub-client handling all section-domain endpoints.
@@ -40,7 +39,7 @@ export class SectionClient extends BaseClient {
         };
     }
     async getSection(id) {
-        z.string().min(1).parse(id);
+        IdSchema.parse(id);
         const response = await request({
             httpMethod: 'GET',
             baseUri: this.syncApiBase,
@@ -63,7 +62,7 @@ export class SectionClient extends BaseClient {
         return validateSection(response.data);
     }
     async updateSection(id, args, requestId) {
-        z.string().min(1).parse(id);
+        IdSchema.parse(id);
         const response = await request({
             httpMethod: 'POST',
             baseUri: this.syncApiBase,
@@ -76,7 +75,7 @@ export class SectionClient extends BaseClient {
         return validateSection(response.data);
     }
     async deleteSection(id, requestId) {
-        z.string().min(1).parse(id);
+        IdSchema.parse(id);
         const response = await request({
             httpMethod: 'DELETE',
             baseUri: this.syncApiBase,
@@ -88,7 +87,7 @@ export class SectionClient extends BaseClient {
         return isSuccess(response);
     }
     async archiveSection(id, requestId) {
-        z.string().min(1).parse(id);
+        IdSchema.parse(id);
         const response = await request({
             httpMethod: 'POST',
             baseUri: this.syncApiBase,
@@ -100,7 +99,7 @@ export class SectionClient extends BaseClient {
         return validateSection(response.data);
     }
     async unarchiveSection(id, requestId) {
-        z.string().min(1).parse(id);
+        IdSchema.parse(id);
         const response = await request({
             httpMethod: 'POST',
             baseUri: this.syncApiBase,

package/dist/esm/clients/task-client.js

@@ -10,14 +10,13 @@ var __rest = (this && this.__rest) || function (s, e) {
     return t;
 };
 import { v4 as uuidv4 } from 'uuid';
-import { z } from 'zod';
 import { ENDPOINT_REST_TASKS, ENDPOINT_REST_TASKS_COMPLETED, ENDPOINT_REST_TASKS_COMPLETED_BY_COMPLETION_DATE, ENDPOINT_REST_TASKS_COMPLETED_BY_DUE_DATE, ENDPOINT_REST_TASKS_COMPLETED_SEARCH, ENDPOINT_REST_TASKS_FILTER, ENDPOINT_REST_TASK_CLOSE, ENDPOINT_REST_TASK_MOVE, ENDPOINT_REST_TASK_REOPEN, ENDPOINT_SYNC_QUICK_ADD, } from '../consts/endpoints.js';
 import { isSuccess, request } from '../transport/http-client.js';
 import { performSyncRequest } from '../transport/sync-request.js';
 import { TodoistRequestError } from '../types/index.js';
 import { generatePath, spreadIfDefined } from '../utils/request-helpers.js';
 import { processTaskContent } from '../utils/uncompletable-helpers.js';
-import { validateTask, validateTaskArray } from '../utils/validators.js';
+import { IdSchema, validateTask, validateTaskArray } from '../utils/validators.js';
 import { BaseClient } from './base-client.js';
 const MAX_COMMAND_COUNT = 100;
 /**
@@ -28,7 +27,7 @@ const MAX_COMMAND_COUNT = 100;
  */
 export class TaskClient extends BaseClient {
     async getTask(id) {
-        z.string().min(1).parse(id);
+        IdSchema.parse(id);
         const response = await request({
             httpMethod: 'GET',
             baseUri: this.syncApiBase,
@@ -152,7 +151,7 @@ export class TaskClient extends BaseClient {
         return validateTask(response.data);
     }
     async updateTask(id, args, requestId) {
-        z.string().min(1).parse(id);
+        IdSchema.parse(id);
         // Translate SDK alias for due-date clearing to Todoist's accepted payload value.
         const normalizedArgs = args.dueString === null ? Object.assign(Object.assign({}, args), { dueString: 'no date' }) : args;
         // Process content if both content and isUncompletable are provided
@@ -200,7 +199,7 @@ export class TaskClient extends BaseClient {
         return validateTaskArray(syncTasks);
     }
     async moveTask(id, args, requestId) {
-        z.string().min(1).parse(id);
+        IdSchema.parse(id);
         const response = await request({
             httpMethod: 'POST',
             baseUri: this.syncApiBase,
@@ -213,7 +212,7 @@ export class TaskClient extends BaseClient {
         return validateTask(response.data);
     }
     async closeTask(id, requestId) {
-        z.string().min(1).parse(id);
+        IdSchema.parse(id);
         const response = await request({
             httpMethod: 'POST',
             baseUri: this.syncApiBase,
@@ -225,7 +224,7 @@ export class TaskClient extends BaseClient {
         return isSuccess(response);
     }
     async reopenTask(id, requestId) {
-        z.string().min(1).parse(id);
+        IdSchema.parse(id);
         const response = await request({
             httpMethod: 'POST',
             baseUri: this.syncApiBase,
@@ -237,7 +236,7 @@ export class TaskClient extends BaseClient {
         return isSuccess(response);
     }
     async deleteTask(id, requestId) {
-        z.string().min(1).parse(id);
+        IdSchema.parse(id);
         const response = await request({
             httpMethod: 'DELETE',
             baseUri: this.syncApiBase,

package/dist/esm/clients/ui-extension-client.js

@@ -1,9 +1,8 @@
-import { z } from 'zod';
 import { ENDPOINT_REST_APPS_UI_EXTENSIONS, ENDPOINT_REST_APPS_UI_EXTENSIONS_INSTALLED, getUiExtensionEndpoint, getUiExtensionIconEndpoint, getUiExtensionsByIntegrationEndpoint, } from '../consts/endpoints.js';
 import { isSuccess, request } from '../transport/http-client.js';
 import { camelCaseKeys } from '../utils/case-conversion.js';
 import { uploadMultipartFile } from '../utils/multipart-upload.js';
-import { validateUiExtension, validateUiExtensionArray } from '../utils/validators.js';
+import { IdSchema, validateUiExtension, validateUiExtensionArray } from '../utils/validators.js';
 import { BaseClient } from './base-client.js';
 /**
  * Internal sub-client handling all UI-extension endpoints for developer
@@ -14,7 +13,7 @@ import { BaseClient } from './base-client.js';
  */
 export class UiExtensionClient extends BaseClient {
     async getUiExtension(uiExtensionId, requestId) {
-        z.string().min(1).parse(uiExtensionId);
+        IdSchema.parse(uiExtensionId);
         const response = await request({
             httpMethod: 'GET',
             baseUri: this.apiRootBase,
@@ -37,7 +36,7 @@ export class UiExtensionClient extends BaseClient {
         return validateUiExtensionArray(response.data);
     }
     async getUiExtensionsForApp(appId, requestId) {
-        z.string().min(1).parse(appId);
+        IdSchema.parse(appId);
         const response = await request({
             httpMethod: 'GET',
             baseUri: this.apiRootBase,
@@ -61,7 +60,7 @@ export class UiExtensionClient extends BaseClient {
         return validateUiExtension(response.data);
     }
     async updateUiExtension(uiExtensionId, args, requestId) {
-        z.string().min(1).parse(uiExtensionId);
+        IdSchema.parse(uiExtensionId);
         const response = await request({
             httpMethod: 'PATCH',
             baseUri: this.apiRootBase,
@@ -74,7 +73,7 @@ export class UiExtensionClient extends BaseClient {
         return validateUiExtension(response.data);
     }
     async deleteUiExtension(uiExtensionId, requestId) {
-        z.string().min(1).parse(uiExtensionId);
+        IdSchema.parse(uiExtensionId);
         const response = await request({
             httpMethod: 'DELETE',
             baseUri: this.apiRootBase,

package/dist/esm/clients/workspace-client.js

@@ -9,12 +9,11 @@ var __rest = (this && this.__rest) || function (s, e) {
         }
     return t;
 };
-import { z } from 'zod';
 import { ENDPOINT_REST_WORKSPACES, ENDPOINT_WORKSPACE_INVITATIONS, ENDPOINT_WORKSPACE_INVITATIONS_ALL, ENDPOINT_WORKSPACE_INVITATIONS_DELETE, ENDPOINT_WORKSPACE_JOIN, ENDPOINT_WORKSPACE_LOGO, ENDPOINT_WORKSPACE_MEMBERS, ENDPOINT_WORKSPACE_PLAN_DETAILS, ENDPOINT_WORKSPACE_USERS, getWorkspaceActiveProjectsEndpoint, getWorkspaceArchivedProjectsEndpoint, getWorkspaceInvitationAcceptEndpoint, getWorkspaceInvitationRejectEndpoint, getWorkspaceInviteUsersEndpoint, getWorkspaceUserEndpoint, getWorkspaceUserTasksEndpoint, } from '../consts/endpoints.js';
 import { isSuccess, request } from '../transport/http-client.js';
 import { uploadMultipartFile } from '../utils/multipart-upload.js';
 import { generatePath } from '../utils/request-helpers.js';
-import { validateJoinWorkspaceResult, validateMemberActivityInfoArray, validateProject, validateWorkspace, validateWorkspaceArray, validateWorkspaceInvitation, validateWorkspaceInvitationArray, validateWorkspacePlanDetails, validateWorkspaceUserArray, validateWorkspaceUserTaskArray, } from '../utils/validators.js';
+import { IdSchema, validateJoinWorkspaceResult, validateMemberActivityInfoArray, validateProject, validateWorkspace, validateWorkspaceArray, validateWorkspaceInvitation, validateWorkspaceInvitationArray, validateWorkspacePlanDetails, validateWorkspaceUserArray, validateWorkspaceUserTaskArray, } from '../utils/validators.js';
 import { BaseClient } from './base-client.js';
 /**
  * Internal sub-client handling all workspace-domain endpoints —
@@ -196,7 +195,7 @@ export class WorkspaceClient extends BaseClient {
         return validateWorkspaceArray(response.data);
     }
     async getWorkspace(id, requestId) {
-        z.string().min(1).parse(id);
+        IdSchema.parse(id);
         const response = await request({
             httpMethod: 'GET',
             baseUri: this.syncApiBase,
@@ -220,7 +219,7 @@ export class WorkspaceClient extends BaseClient {
         return validateWorkspace(response.data);
     }
     async updateWorkspace(id, args, requestId) {
-        z.string().min(1).parse(id);
+        IdSchema.parse(id);
         const response = await request({
             httpMethod: 'POST',
             baseUri: this.syncApiBase,
@@ -233,7 +232,7 @@ export class WorkspaceClient extends BaseClient {
         return validateWorkspace(response.data);
     }
     async deleteWorkspace(id, requestId) {
-        z.string().min(1).parse(id);
+        IdSchema.parse(id);
         const response = await request({
             httpMethod: 'DELETE',
             baseUri: this.syncApiBase,

package/dist/esm/types/index.js

@@ -20,3 +20,4 @@ export * from './http.js';
 export * from './sync/index.js';
 export * from './apps/index.js';
 export * from './ui-extensions/index.js';
+export * from './webhooks/index.js';

package/dist/esm/types/webhooks/envelope.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { WebhookVersionSchema } from '../apps/types.js';
+/**
+ * Collaborator info for the user that triggered a webhook event.
+ * @see https://developer.todoist.com/sync/v1/#webhooks
+ */
+export const WebhookInitiatorSchema = z.object({
+    id: z.string(),
+    fullName: z.string(),
+    email: z.string(),
+    imageId: z.string().nullable(),
+    isPremium: z.boolean(),
+});
+/**
+ * Fields common to every webhook payload, regardless of `eventName`.
+ * Meant to be spread into per-event variant schemas.
+ */
+export const BaseWebhookEnvelopeShape = {
+    version: WebhookVersionSchema,
+    userId: z.string(),
+    initiator: WebhookInitiatorSchema,
+    triggeredAt: z.coerce.date(),
+};

package/dist/esm/types/webhooks/index.js

@@ -0,0 +1,3 @@
+export * from './envelope.js';
+export * from './tasks.js';
+export * from './types.js';

package/dist/esm/types/webhooks/tasks.js

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { TaskSchema } from '../tasks/types.js';
+import { BaseWebhookEnvelopeShape } from './envelope.js';
+/**
+ * Enum-like object of task (`item:*`) webhook event names. Single source of
+ * truth for the discriminator values — `TASK_WEBHOOK_EVENTS` and every
+ * `z.literal()` below derive from it.
+ */
+export const TaskWebhookEventEnum = {
+    Added: 'item:added',
+    Updated: 'item:updated',
+    Completed: 'item:completed',
+    Uncompleted: 'item:uncompleted',
+    Deleted: 'item:deleted',
+};
+/**
+ * Webhook events that carry a {@link Task} as their `eventData`.
+ *
+ * The on-the-wire event names remain `item:*` for historical reasons; the
+ * SDK types call them `Task*` to match the rest of the public API where the
+ * resource is named `Task`.
+ */
+export const TASK_WEBHOOK_EVENTS = [
+    TaskWebhookEventEnum.Added,
+    TaskWebhookEventEnum.Updated,
+    TaskWebhookEventEnum.Completed,
+    TaskWebhookEventEnum.Uncompleted,
+    TaskWebhookEventEnum.Deleted,
+];
+/**
+ * Possible values for the `updateIntent` field on `item:updated`'s
+ * `eventDataExtra`. `item_updated` is the default; the others narrow the
+ * reason for the update (for example, a recurring completion or a change of
+ * assignee).
+ *
+ * @see https://developer.todoist.com/sync/v1/#webhooks (Events Extra)
+ */
+export const UPDATE_INTENTS = [
+    'item_updated',
+    'item_completed',
+    'item_uncompleted',
+    'responsible_uid_changed',
+];
+/**
+ * An unrecognised value from a future backend release degrades gracefully to
+ * `'item_updated'` rather than crashing the whole payload parse.
+ */
+export const UpdateIntentSchema = z.enum(UPDATE_INTENTS).catch('item_updated');
+/**
+ * Extra info delivered alongside an `item:updated` event when the initiator
+ * is the acting user. Contains the pre-update task state plus the reason for
+ * the update — useful for diffing or for distinguishing manual edits from
+ * recurring-task completions.
+ *
+ * @see https://developer.todoist.com/sync/v1/#webhooks (Events Extra)
+ */
+export const TaskUpdatedExtraSchema = z.object({
+    oldItem: TaskSchema,
+    updateIntent: UpdateIntentSchema,
+});
+export const TaskAddedPayloadSchema = z.object(Object.assign(Object.assign({}, BaseWebhookEnvelopeShape), { eventName: z.literal(TaskWebhookEventEnum.Added), eventData: TaskSchema }));
+export const TaskUpdatedPayloadSchema = z.object(Object.assign(Object.assign({}, BaseWebhookEnvelopeShape), { eventName: z.literal(TaskWebhookEventEnum.Updated), eventData: TaskSchema, eventDataExtra: TaskUpdatedExtraSchema.optional() }));
+export const TaskCompletedPayloadSchema = z.object(Object.assign(Object.assign({}, BaseWebhookEnvelopeShape), { eventName: z.literal(TaskWebhookEventEnum.Completed), eventData: TaskSchema }));
+export const TaskUncompletedPayloadSchema = z.object(Object.assign(Object.assign({}, BaseWebhookEnvelopeShape), { eventName: z.literal(TaskWebhookEventEnum.Uncompleted), eventData: TaskSchema }));
+export const TaskDeletedPayloadSchema = z.object(Object.assign(Object.assign({}, BaseWebhookEnvelopeShape), { eventName: z.literal(TaskWebhookEventEnum.Deleted), eventData: TaskSchema }));

package/dist/esm/types/webhooks/types.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { WEBHOOK_EVENTS, WebhookEventSchema } from '../apps/types.js';
+import { BaseWebhookEnvelopeShape } from './envelope.js';
+import { TASK_WEBHOOK_EVENTS, TaskAddedPayloadSchema, TaskCompletedPayloadSchema, TaskDeletedPayloadSchema, TaskUncompletedPayloadSchema, TaskUpdatedPayloadSchema, } from './tasks.js';
+const untypedEventNames = WEBHOOK_EVENTS.filter((event) => !TASK_WEBHOOK_EVENTS.includes(event));
+/**
+ * A single branch covering every event whose payload has not yet been typed
+ * per resource. Follow-up PRs will replace slices of this with dedicated
+ * variants (notes, projects, sections, labels, filters, reminders).
+ */
+export const UntypedWebhookPayloadSchema = z.object(Object.assign(Object.assign({}, BaseWebhookEnvelopeShape), { eventName: z.enum(untypedEventNames), eventData: z.unknown(), eventDataExtra: z.unknown().optional() }));
+/**
+ * Wrapper schema for an incoming webhook payload.
+ *
+ * The backend sends snake_case keys and uses the public event form
+ * (`item:added`) in the `event_name` field, so consumers using
+ * `parseWebhookPayload` receive camelCase fields directly.
+ *
+ * Typed today: `item:*` events carry a parsed {@link Task}. Other events
+ * still expose `eventData` as `unknown`; they will be narrowed in follow-up
+ * PRs (notes, projects, sections, labels, filters, reminders).
+ */
+export const WebhookPayloadSchema = z.discriminatedUnion('eventName', [
+    TaskAddedPayloadSchema,
+    TaskUpdatedPayloadSchema,
+    TaskCompletedPayloadSchema,
+    TaskUncompletedPayloadSchema,
+    TaskDeletedPayloadSchema,
+    UntypedWebhookPayloadSchema,
+]);
+export { WebhookEventSchema };

package/dist/esm/utils/index.js

@@ -3,3 +3,4 @@ export * from './sanitization.js';
 export { getTaskUrl, getProjectUrl, getSectionUrl } from './url-helpers.js';
 export { createCommand } from './sync-helpers.js';
 export * from './project-helpers.js';
+export { parseWebhookPayload, verifyWebhookSignature } from './webhook-parser.js';

package/dist/esm/utils/validators.js

@@ -21,6 +21,11 @@ function createValidator(schema) {
         validateArray: (input) => z.array(schema).parse(input),
     };
 }
+const TMP_ID_MESSAGE = 'This looks like a client-side placeholder — wait for sync to complete before calling the API.';
+export const IdSchema = z
+    .string()
+    .min(1)
+    .refine((id) => !id.startsWith('tmp-'), { message: TMP_ID_MESSAGE });
 // Entity validators
 export const { validate: validateTask, validateArray: validateTaskArray } = createValidator(TaskSchema);
 /**

package/dist/esm/utils/webhook-parser.js

@@ -0,0 +1,56 @@
+import { WebhookPayloadSchema } from '../types/webhooks/types.js';
+import { camelCaseKeys } from './case-conversion.js';
+/**
+ * Parses an incoming webhook request body into a typed payload.
+ *
+ * The backend sends snake_case keys (e.g. `event_name`, `user_id`, `added_at`);
+ * this converts them to camelCase and validates against
+ * {@link WebhookPayloadSchema}. Event-specific `eventData` is returned as
+ * `unknown` for events that are not yet narrowed per-resource.
+ *
+ * Pass the parsed JSON body (or any unknown value) — validation throws on
+ * unexpected shape.
+ */
+export function parseWebhookPayload(raw) {
+    return WebhookPayloadSchema.parse(camelCaseKeys(raw));
+}
+const encoder = new TextEncoder();
+function base64ToBytes(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+/**
+ * Verifies a webhook request's HMAC signature.
+ *
+ * Todoist signs webhook deliveries with an HMAC-SHA256 of the raw request body
+ * using the app's `client_secret` as the key, base64-encoded in the
+ * `X-Todoist-Hmac-SHA256` header.
+ *
+ * Uses the Web Crypto API (`crypto.subtle`), which is available in Node ≥ 20,
+ * modern browsers, React Native (with polyfills), and edge runtimes. The
+ * comparison is constant-time.
+ *
+ * @returns `true` when the signature is valid, `false` otherwise. Never throws
+ * on malformed input.
+ */
+export async function verifyWebhookSignature({ rawBody, signature, clientSecret, }) {
+    let provided;
+    try {
+        provided = base64ToBytes(signature);
+    }
+    catch (_a) {
+        return false;
+    }
+    const key = await crypto.subtle.importKey('raw', encoder.encode(clientSecret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+    const body = typeof rawBody === 'string' ? encoder.encode(rawBody) : rawBody;
+    try {
+        return await crypto.subtle.verify('HMAC', key, provided, body);
+    }
+    catch (_b) {
+        return false;
+    }
+}

package/dist/types/types/index.d.ts

@@ -20,3 +20,4 @@ export * from './http.js';
 export * from './sync/index.js';
 export * from './apps/index.js';
 export * from './ui-extensions/index.js';
+export * from './webhooks/index.js';

package/dist/types/types/webhooks/envelope.d.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+/**
+ * Collaborator info for the user that triggered a webhook event.
+ * @see https://developer.todoist.com/sync/v1/#webhooks
+ */
+export declare const WebhookInitiatorSchema: z.ZodObject<{
+    id: z.ZodString;
+    fullName: z.ZodString;
+    email: z.ZodString;
+    imageId: z.ZodNullable<z.ZodString>;
+    isPremium: z.ZodBoolean;
+}, z.core.$strip>;
+/**
+ * Collaborator info for the user that triggered a webhook event.
+ */
+export type WebhookInitiator = z.infer<typeof WebhookInitiatorSchema>;
+/**
+ * Fields common to every webhook payload, regardless of `eventName`.
+ * Meant to be spread into per-event variant schemas.
+ */
+export declare const BaseWebhookEnvelopeShape: {
+    readonly version: z.ZodEnum<{
+        1: "1";
+    }>;
+    readonly userId: z.ZodString;
+    readonly initiator: z.ZodObject<{
+        id: z.ZodString;
+        fullName: z.ZodString;
+        email: z.ZodString;
+        imageId: z.ZodNullable<z.ZodString>;
+        isPremium: z.ZodBoolean;
+    }, z.core.$strip>;
+    readonly triggeredAt: z.ZodCoercedDate<unknown>;
+};

package/dist/types/types/webhooks/index.d.ts

@@ -0,0 +1,3 @@
+export * from './envelope.js';
+export * from './tasks.js';
+export * from './types.js';