@doist/todoist-sdk 9.3.0 → 9.4.0

package/dist/cjs/types/index.js

@@ -36,3 +36,4 @@ __exportStar(require("./http"), exports);
 __exportStar(require("./sync"), exports);
 __exportStar(require("./apps"), exports);
 __exportStar(require("./ui-extensions"), exports);
+__exportStar(require("./webhooks"), exports);

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

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseWebhookEnvelopeShape = exports.WebhookInitiatorSchema = void 0;
+const zod_1 = require("zod");
+const types_1 = require("../apps/types");
+/**
+ * Collaborator info for the user that triggered a webhook event.
+ * @see https://developer.todoist.com/sync/v1/#webhooks
+ */
+exports.WebhookInitiatorSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    fullName: zod_1.z.string(),
+    email: zod_1.z.string(),
+    imageId: zod_1.z.string().nullable(),
+    isPremium: zod_1.z.boolean(),
+});
+/**
+ * Fields common to every webhook payload, regardless of `eventName`.
+ * Meant to be spread into per-event variant schemas.
+ */
+exports.BaseWebhookEnvelopeShape = {
+    version: types_1.WebhookVersionSchema,
+    userId: zod_1.z.string(),
+    initiator: exports.WebhookInitiatorSchema,
+    triggeredAt: zod_1.z.coerce.date(),
+};

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

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./envelope"), exports);
+__exportStar(require("./tasks"), exports);
+__exportStar(require("./types"), exports);

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

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskDeletedPayloadSchema = exports.TaskUncompletedPayloadSchema = exports.TaskCompletedPayloadSchema = exports.TaskUpdatedPayloadSchema = exports.TaskAddedPayloadSchema = exports.TaskUpdatedExtraSchema = exports.UpdateIntentSchema = exports.UPDATE_INTENTS = exports.TASK_WEBHOOK_EVENTS = exports.TaskWebhookEventEnum = void 0;
+const zod_1 = require("zod");
+const types_1 = require("../tasks/types");
+const envelope_1 = require("./envelope");
+/**
+ * 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.
+ */
+exports.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`.
+ */
+exports.TASK_WEBHOOK_EVENTS = [
+    exports.TaskWebhookEventEnum.Added,
+    exports.TaskWebhookEventEnum.Updated,
+    exports.TaskWebhookEventEnum.Completed,
+    exports.TaskWebhookEventEnum.Uncompleted,
+    exports.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)
+ */
+exports.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.
+ */
+exports.UpdateIntentSchema = zod_1.z.enum(exports.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)
+ */
+exports.TaskUpdatedExtraSchema = zod_1.z.object({
+    oldItem: types_1.TaskSchema,
+    updateIntent: exports.UpdateIntentSchema,
+});
+exports.TaskAddedPayloadSchema = zod_1.z.object(Object.assign(Object.assign({}, envelope_1.BaseWebhookEnvelopeShape), { eventName: zod_1.z.literal(exports.TaskWebhookEventEnum.Added), eventData: types_1.TaskSchema }));
+exports.TaskUpdatedPayloadSchema = zod_1.z.object(Object.assign(Object.assign({}, envelope_1.BaseWebhookEnvelopeShape), { eventName: zod_1.z.literal(exports.TaskWebhookEventEnum.Updated), eventData: types_1.TaskSchema, eventDataExtra: exports.TaskUpdatedExtraSchema.optional() }));
+exports.TaskCompletedPayloadSchema = zod_1.z.object(Object.assign(Object.assign({}, envelope_1.BaseWebhookEnvelopeShape), { eventName: zod_1.z.literal(exports.TaskWebhookEventEnum.Completed), eventData: types_1.TaskSchema }));
+exports.TaskUncompletedPayloadSchema = zod_1.z.object(Object.assign(Object.assign({}, envelope_1.BaseWebhookEnvelopeShape), { eventName: zod_1.z.literal(exports.TaskWebhookEventEnum.Uncompleted), eventData: types_1.TaskSchema }));
+exports.TaskDeletedPayloadSchema = zod_1.z.object(Object.assign(Object.assign({}, envelope_1.BaseWebhookEnvelopeShape), { eventName: zod_1.z.literal(exports.TaskWebhookEventEnum.Deleted), eventData: types_1.TaskSchema }));

package/dist/cjs/types/webhooks/types.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookEventSchema = exports.WebhookPayloadSchema = exports.UntypedWebhookPayloadSchema = void 0;
+const zod_1 = require("zod");
+const types_1 = require("../apps/types");
+Object.defineProperty(exports, "WebhookEventSchema", { enumerable: true, get: function () { return types_1.WebhookEventSchema; } });
+const envelope_1 = require("./envelope");
+const tasks_1 = require("./tasks");
+const untypedEventNames = types_1.WEBHOOK_EVENTS.filter((event) => !tasks_1.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).
+ */
+exports.UntypedWebhookPayloadSchema = zod_1.z.object(Object.assign(Object.assign({}, envelope_1.BaseWebhookEnvelopeShape), { eventName: zod_1.z.enum(untypedEventNames), eventData: zod_1.z.unknown(), eventDataExtra: zod_1.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).
+ */
+exports.WebhookPayloadSchema = zod_1.z.discriminatedUnion('eventName', [
+    tasks_1.TaskAddedPayloadSchema,
+    tasks_1.TaskUpdatedPayloadSchema,
+    tasks_1.TaskCompletedPayloadSchema,
+    tasks_1.TaskUncompletedPayloadSchema,
+    tasks_1.TaskDeletedPayloadSchema,
+    exports.UntypedWebhookPayloadSchema,
+]);

package/dist/cjs/utils/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createCommand = exports.getSectionUrl = exports.getProjectUrl = exports.getTaskUrl = void 0;
+exports.verifyWebhookSignature = exports.parseWebhookPayload = exports.createCommand = exports.getSectionUrl = exports.getProjectUrl = exports.getTaskUrl = void 0;
 __exportStar(require("./colors"), exports);
 __exportStar(require("./sanitization"), exports);
 var url_helpers_1 = require("./url-helpers");
@@ -24,3 +24,6 @@ Object.defineProperty(exports, "getSectionUrl", { enumerable: true, get: functio
 var sync_helpers_1 = require("./sync-helpers");
 Object.defineProperty(exports, "createCommand", { enumerable: true, get: function () { return sync_helpers_1.createCommand; } });
 __exportStar(require("./project-helpers"), exports);
+var webhook_parser_1 = require("./webhook-parser");
+Object.defineProperty(exports, "parseWebhookPayload", { enumerable: true, get: function () { return webhook_parser_1.parseWebhookPayload; } });
+Object.defineProperty(exports, "verifyWebhookSignature", { enumerable: true, get: function () { return webhook_parser_1.verifyWebhookSignature; } });

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

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseWebhookPayload = parseWebhookPayload;
+exports.verifyWebhookSignature = verifyWebhookSignature;
+const types_1 = require("../types/webhooks/types");
+const case_conversion_1 = require("./case-conversion");
+/**
+ * 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.
+ */
+function parseWebhookPayload(raw) {
+    return types_1.WebhookPayloadSchema.parse((0, case_conversion_1.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.
+ */
+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/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/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';