@doist/todoist-sdk 9.3.0 → 9.5.0

package/dist/cjs/test-utils/webhook-fixtures.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLIENT_SECRET = void 0;
+exports.sign = sign;
+exports.rawTask = rawTask;
+exports.envelope = envelope;
+const node_crypto_1 = require("node:crypto");
+exports.CLIENT_SECRET = 'test-client-secret';
+/** HMAC-SHA256 signs a raw body with the test client secret (or an override). */
+function sign(body, secret = exports.CLIENT_SECRET) {
+    return (0, node_crypto_1.createHmac)('sha256', secret).update(body).digest('base64');
+}
+/**
+ * Snake_case task payload matching the v1 webhook wire shape.
+ */
+function rawTask(overrides = {}) {
+    return Object.assign({ id: '6XR4GqQQCW6Gv9h4', user_id: '2671355', project_id: '6XR4H993xv8H5qCR', section_id: null, parent_id: null, added_by_uid: '2671355', assigned_by_uid: null, responsible_uid: null, labels: [], deadline: null, duration: null, is_collapsed: false, checked: false, is_deleted: false, added_at: '2025-02-10T10:33:38.000000Z', completed_at: null, completed_by_uid: null, updated_at: '2025-02-10T10:33:38.000000Z', due: null, priority: 1, child_order: 3, content: 'Buy Milk', description: '', note_count: 0, day_order: -1, goal_ids: [], url: 'https://app.todoist.com/app/task/6XR4GqQQCW6Gv9h4' }, overrides);
+}
+/**
+ * Wraps an event's `event_data` in the snake_case envelope the backend sends
+ * (initiator, version, timestamps, etc). `extra` passes extra top-level keys
+ * like `event_data_extra`.
+ */
+function envelope(event, eventData, extra) {
+    return Object.assign({ version: '1', user_id: '2671355', initiator: {
+            id: '2671355',
+            full_name: 'Alice',
+            email: 'alice@example.com',
+            image_id: 'ad38375bdb094286af59f1eab36d8f20',
+            is_premium: true,
+        }, event_name: event, event_data: eventData, triggered_at: '2025-02-10T10:39:38.000000Z' }, extra);
+}

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/comments.js

@@ -0,0 +1,96 @@
+"use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommentDeletedPayloadSchema = exports.CommentUpdatedPayloadSchema = exports.CommentAddedPayloadSchema = exports.WebhookCommentSchema = exports.WebhookProjectCommentSchema = exports.WebhookItemCommentSchema = exports.COMMENT_WEBHOOK_EVENTS = exports.CommentWebhookEventEnum = void 0;
+const zod_1 = require("zod");
+const types_1 = require("../comments/types");
+const types_2 = require("../tasks/types");
+const envelope_1 = require("./envelope");
+/**
+ * Enum-like object of comment (`note:*`) webhook event names. Single source
+ * of truth for the discriminator values — `COMMENT_WEBHOOK_EVENTS` and every
+ * `z.literal()` below derive from it.
+ *
+ * The on-the-wire event names remain `note:*` for historical reasons; the
+ * SDK types use `Comment*` to match the rest of the public API where the
+ * resource is named `Comment`.
+ */
+exports.CommentWebhookEventEnum = {
+    Added: 'note:added',
+    Updated: 'note:updated',
+    Deleted: 'note:deleted',
+};
+/**
+ * Webhook events that carry a comment as their `eventData`.
+ */
+exports.COMMENT_WEBHOOK_EVENTS = [
+    exports.CommentWebhookEventEnum.Added,
+    exports.CommentWebhookEventEnum.Updated,
+    exports.CommentWebhookEventEnum.Deleted,
+];
+/**
+ * Fields common to both item and project comment payloads.
+ *
+ * `postedAt` and `postedUid` are nullable here (unlike
+ * {@link RawCommentSchema}) because webhook payloads may omit them — for
+ * example when the poster could not be resolved, or on a deleted-note
+ * tombstone.
+ */
+const WebhookCommentBaseSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    content: zod_1.z.string(),
+    postedAt: zod_1.z.coerce.date().nullable(),
+    postedUid: zod_1.z.string().nullable(),
+    fileAttachment: types_1.AttachmentSchema.nullable(),
+    uidsToNotify: zod_1.z.array(zod_1.z.string()).nullable(),
+    reactions: zod_1.z.record(zod_1.z.string(), zod_1.z.array(zod_1.z.string())).nullable(),
+    isDeleted: zod_1.z.boolean(),
+});
+/**
+ * A comment attached to a task, delivered in a webhook payload.
+ *
+ * Webhook item-comment payloads carry two fields that don't appear on the
+ * REST comment resource: `url` (the direct task URL) and `item` (the full
+ * embedded {@link Task}). Both are parsed here so consumers handling a
+ * `note:added` event also get the task it belongs to.
+ *
+ * `itemId` is exposed as `taskId` to match the rest of the SDK surface.
+ */
+exports.WebhookItemCommentSchema = WebhookCommentBaseSchema.extend({
+    itemId: zod_1.z.string(),
+    url: zod_1.z.string(),
+    item: types_2.TaskSchema,
+})
+    .strict()
+    .transform((_a) => {
+    var { itemId } = _a, rest = __rest(_a, ["itemId"]);
+    return (Object.assign(Object.assign({}, rest), { taskId: itemId }));
+});
+/**
+ * A comment attached to a project, delivered in a webhook payload.
+ *
+ * Project comments do not carry the extra `url` or embedded project fields
+ * that item comments carry for the parent task.
+ */
+exports.WebhookProjectCommentSchema = WebhookCommentBaseSchema.extend({
+    projectId: zod_1.z.string(),
+}).strict();
+/**
+ * The `eventData` of a `note:*` webhook payload — either an item comment
+ * (includes `taskId` and an embedded {@link Task}) or a project comment
+ * (includes `projectId`). Narrow with `'taskId' in eventData`.
+ */
+exports.WebhookCommentSchema = zod_1.z.union([exports.WebhookItemCommentSchema, exports.WebhookProjectCommentSchema]);
+exports.CommentAddedPayloadSchema = zod_1.z.object(Object.assign(Object.assign({}, envelope_1.BaseWebhookEnvelopeShape), { eventName: zod_1.z.literal(exports.CommentWebhookEventEnum.Added), eventData: exports.WebhookCommentSchema }));
+exports.CommentUpdatedPayloadSchema = zod_1.z.object(Object.assign(Object.assign({}, envelope_1.BaseWebhookEnvelopeShape), { eventName: zod_1.z.literal(exports.CommentWebhookEventEnum.Updated), eventData: exports.WebhookCommentSchema }));
+exports.CommentDeletedPayloadSchema = zod_1.z.object(Object.assign(Object.assign({}, envelope_1.BaseWebhookEnvelopeShape), { eventName: zod_1.z.literal(exports.CommentWebhookEventEnum.Deleted), eventData: exports.WebhookCommentSchema }));

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,21 @@
+"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("./comments"), exports);
+__exportStar(require("./envelope"), exports);
+__exportStar(require("./labels"), exports);
+__exportStar(require("./tasks"), exports);
+__exportStar(require("./types"), exports);

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

@@ -0,0 +1,54 @@
+"use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LabelDeletedPayloadSchema = exports.LabelUpdatedPayloadSchema = exports.LabelAddedPayloadSchema = exports.WebhookLabelSchema = exports.LABEL_WEBHOOK_EVENTS = exports.LabelWebhookEventEnum = void 0;
+const zod_1 = require("zod");
+const types_1 = require("../labels/types");
+const envelope_1 = require("./envelope");
+/**
+ * Enum-like object of label (`label:*`) webhook event names. Single source
+ * of truth for the discriminator values — `LABEL_WEBHOOK_EVENTS` and every
+ * `z.literal()` below derive from it.
+ */
+exports.LabelWebhookEventEnum = {
+    Added: 'label:added',
+    Updated: 'label:updated',
+    Deleted: 'label:deleted',
+};
+/** Webhook events that carry a label as their `eventData`. */
+exports.LABEL_WEBHOOK_EVENTS = [
+    exports.LabelWebhookEventEnum.Added,
+    exports.LabelWebhookEventEnum.Updated,
+    exports.LabelWebhookEventEnum.Deleted,
+];
+/**
+ * A label as delivered in a webhook payload.
+ *
+ * Webhook label payloads differ from the REST label shape in two ways:
+ * they use `item_order` (not `order`) and always include `is_deleted`. This
+ * schema reuses {@link LabelSchema}, swapping `order` for `itemOrder` on
+ * the input side and renaming it back after validation, and surfaces
+ * `isDeleted` for downstream filtering.
+ */
+exports.WebhookLabelSchema = types_1.LabelSchema.omit({ order: true })
+    .extend({
+    itemOrder: zod_1.z.number().int().nullable(),
+    isDeleted: zod_1.z.boolean(),
+})
+    .transform((_a) => {
+    var { itemOrder } = _a, rest = __rest(_a, ["itemOrder"]);
+    return (Object.assign(Object.assign({}, rest), { order: itemOrder }));
+});
+exports.LabelAddedPayloadSchema = zod_1.z.object(Object.assign(Object.assign({}, envelope_1.BaseWebhookEnvelopeShape), { eventName: zod_1.z.literal(exports.LabelWebhookEventEnum.Added), eventData: exports.WebhookLabelSchema }));
+exports.LabelUpdatedPayloadSchema = zod_1.z.object(Object.assign(Object.assign({}, envelope_1.BaseWebhookEnvelopeShape), { eventName: zod_1.z.literal(exports.LabelWebhookEventEnum.Updated), eventData: exports.WebhookLabelSchema }));
+exports.LabelDeletedPayloadSchema = zod_1.z.object(Object.assign(Object.assign({}, envelope_1.BaseWebhookEnvelopeShape), { eventName: zod_1.z.literal(exports.LabelWebhookEventEnum.Deleted), eventData: exports.WebhookLabelSchema }));

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,54 @@
+"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 comments_1 = require("./comments");
+const envelope_1 = require("./envelope");
+const labels_1 = require("./labels");
+const tasks_1 = require("./tasks");
+/**
+ * Events whose payloads have been narrowed per resource. Each phase adds to
+ * this list; {@link UntypedWebhookPayloadSchema} below is derived by taking
+ * every {@link WebhookEvent} not present here.
+ */
+const TYPED_WEBHOOK_EVENTS = [
+    ...tasks_1.TASK_WEBHOOK_EVENTS,
+    ...comments_1.COMMENT_WEBHOOK_EVENTS,
+    ...labels_1.LABEL_WEBHOOK_EVENTS,
+];
+const untypedEventNames = types_1.WEBHOOK_EVENTS.filter((event) => !TYPED_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 (projects, sections, 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}; `note:*` events
+ * carry a parsed comment (item-comment or project-comment); `label:*` events
+ * carry a parsed label. Other events still expose `eventData` as `unknown`;
+ * they will be narrowed in follow-up PRs (projects, sections, filters,
+ * reminders).
+ */
+exports.WebhookPayloadSchema = zod_1.z.discriminatedUnion('eventName', [
+    tasks_1.TaskAddedPayloadSchema,
+    tasks_1.TaskUpdatedPayloadSchema,
+    tasks_1.TaskCompletedPayloadSchema,
+    tasks_1.TaskUncompletedPayloadSchema,
+    tasks_1.TaskDeletedPayloadSchema,
+    comments_1.CommentAddedPayloadSchema,
+    comments_1.CommentUpdatedPayloadSchema,
+    comments_1.CommentDeletedPayloadSchema,
+    labels_1.LabelAddedPayloadSchema,
+    labels_1.LabelUpdatedPayloadSchema,
+    labels_1.LabelDeletedPayloadSchema,
+    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/test-utils/webhook-fixtures.js

@@ -0,0 +1,26 @@
+import { createHmac } from 'node:crypto';
+export const CLIENT_SECRET = 'test-client-secret';
+/** HMAC-SHA256 signs a raw body with the test client secret (or an override). */
+export function sign(body, secret = CLIENT_SECRET) {
+    return createHmac('sha256', secret).update(body).digest('base64');
+}
+/**
+ * Snake_case task payload matching the v1 webhook wire shape.
+ */
+export function rawTask(overrides = {}) {
+    return Object.assign({ id: '6XR4GqQQCW6Gv9h4', user_id: '2671355', project_id: '6XR4H993xv8H5qCR', section_id: null, parent_id: null, added_by_uid: '2671355', assigned_by_uid: null, responsible_uid: null, labels: [], deadline: null, duration: null, is_collapsed: false, checked: false, is_deleted: false, added_at: '2025-02-10T10:33:38.000000Z', completed_at: null, completed_by_uid: null, updated_at: '2025-02-10T10:33:38.000000Z', due: null, priority: 1, child_order: 3, content: 'Buy Milk', description: '', note_count: 0, day_order: -1, goal_ids: [], url: 'https://app.todoist.com/app/task/6XR4GqQQCW6Gv9h4' }, overrides);
+}
+/**
+ * Wraps an event's `event_data` in the snake_case envelope the backend sends
+ * (initiator, version, timestamps, etc). `extra` passes extra top-level keys
+ * like `event_data_extra`.
+ */
+export function envelope(event, eventData, extra) {
+    return Object.assign({ version: '1', user_id: '2671355', initiator: {
+            id: '2671355',
+            full_name: 'Alice',
+            email: 'alice@example.com',
+            image_id: 'ad38375bdb094286af59f1eab36d8f20',
+            is_premium: true,
+        }, event_name: event, event_data: eventData, triggered_at: '2025-02-10T10:39:38.000000Z' }, extra);
+}

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/comments.js

@@ -0,0 +1,93 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { z } from 'zod';
+import { AttachmentSchema } from '../comments/types.js';
+import { TaskSchema } from '../tasks/types.js';
+import { BaseWebhookEnvelopeShape } from './envelope.js';
+/**
+ * Enum-like object of comment (`note:*`) webhook event names. Single source
+ * of truth for the discriminator values — `COMMENT_WEBHOOK_EVENTS` and every
+ * `z.literal()` below derive from it.
+ *
+ * The on-the-wire event names remain `note:*` for historical reasons; the
+ * SDK types use `Comment*` to match the rest of the public API where the
+ * resource is named `Comment`.
+ */
+export const CommentWebhookEventEnum = {
+    Added: 'note:added',
+    Updated: 'note:updated',
+    Deleted: 'note:deleted',
+};
+/**
+ * Webhook events that carry a comment as their `eventData`.
+ */
+export const COMMENT_WEBHOOK_EVENTS = [
+    CommentWebhookEventEnum.Added,
+    CommentWebhookEventEnum.Updated,
+    CommentWebhookEventEnum.Deleted,
+];
+/**
+ * Fields common to both item and project comment payloads.
+ *
+ * `postedAt` and `postedUid` are nullable here (unlike
+ * {@link RawCommentSchema}) because webhook payloads may omit them — for
+ * example when the poster could not be resolved, or on a deleted-note
+ * tombstone.
+ */
+const WebhookCommentBaseSchema = z.object({
+    id: z.string(),
+    content: z.string(),
+    postedAt: z.coerce.date().nullable(),
+    postedUid: z.string().nullable(),
+    fileAttachment: AttachmentSchema.nullable(),
+    uidsToNotify: z.array(z.string()).nullable(),
+    reactions: z.record(z.string(), z.array(z.string())).nullable(),
+    isDeleted: z.boolean(),
+});
+/**
+ * A comment attached to a task, delivered in a webhook payload.
+ *
+ * Webhook item-comment payloads carry two fields that don't appear on the
+ * REST comment resource: `url` (the direct task URL) and `item` (the full
+ * embedded {@link Task}). Both are parsed here so consumers handling a
+ * `note:added` event also get the task it belongs to.
+ *
+ * `itemId` is exposed as `taskId` to match the rest of the SDK surface.
+ */
+export const WebhookItemCommentSchema = WebhookCommentBaseSchema.extend({
+    itemId: z.string(),
+    url: z.string(),
+    item: TaskSchema,
+})
+    .strict()
+    .transform((_a) => {
+    var { itemId } = _a, rest = __rest(_a, ["itemId"]);
+    return (Object.assign(Object.assign({}, rest), { taskId: itemId }));
+});
+/**
+ * A comment attached to a project, delivered in a webhook payload.
+ *
+ * Project comments do not carry the extra `url` or embedded project fields
+ * that item comments carry for the parent task.
+ */
+export const WebhookProjectCommentSchema = WebhookCommentBaseSchema.extend({
+    projectId: z.string(),
+}).strict();
+/**
+ * The `eventData` of a `note:*` webhook payload — either an item comment
+ * (includes `taskId` and an embedded {@link Task}) or a project comment
+ * (includes `projectId`). Narrow with `'taskId' in eventData`.
+ */
+export const WebhookCommentSchema = z.union([WebhookItemCommentSchema, WebhookProjectCommentSchema]);
+export const CommentAddedPayloadSchema = z.object(Object.assign(Object.assign({}, BaseWebhookEnvelopeShape), { eventName: z.literal(CommentWebhookEventEnum.Added), eventData: WebhookCommentSchema }));
+export const CommentUpdatedPayloadSchema = z.object(Object.assign(Object.assign({}, BaseWebhookEnvelopeShape), { eventName: z.literal(CommentWebhookEventEnum.Updated), eventData: WebhookCommentSchema }));
+export const CommentDeletedPayloadSchema = z.object(Object.assign(Object.assign({}, BaseWebhookEnvelopeShape), { eventName: z.literal(CommentWebhookEventEnum.Deleted), eventData: WebhookCommentSchema }));

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,5 @@
+export * from './comments.js';
+export * from './envelope.js';
+export * from './labels.js';
+export * from './tasks.js';
+export * from './types.js';

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

@@ -0,0 +1,51 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { z } from 'zod';
+import { LabelSchema } from '../labels/types.js';
+import { BaseWebhookEnvelopeShape } from './envelope.js';
+/**
+ * Enum-like object of label (`label:*`) webhook event names. Single source
+ * of truth for the discriminator values — `LABEL_WEBHOOK_EVENTS` and every
+ * `z.literal()` below derive from it.
+ */
+export const LabelWebhookEventEnum = {
+    Added: 'label:added',
+    Updated: 'label:updated',
+    Deleted: 'label:deleted',
+};
+/** Webhook events that carry a label as their `eventData`. */
+export const LABEL_WEBHOOK_EVENTS = [
+    LabelWebhookEventEnum.Added,
+    LabelWebhookEventEnum.Updated,
+    LabelWebhookEventEnum.Deleted,
+];
+/**
+ * A label as delivered in a webhook payload.
+ *
+ * Webhook label payloads differ from the REST label shape in two ways:
+ * they use `item_order` (not `order`) and always include `is_deleted`. This
+ * schema reuses {@link LabelSchema}, swapping `order` for `itemOrder` on
+ * the input side and renaming it back after validation, and surfaces
+ * `isDeleted` for downstream filtering.
+ */
+export const WebhookLabelSchema = LabelSchema.omit({ order: true })
+    .extend({
+    itemOrder: z.number().int().nullable(),
+    isDeleted: z.boolean(),
+})
+    .transform((_a) => {
+    var { itemOrder } = _a, rest = __rest(_a, ["itemOrder"]);
+    return (Object.assign(Object.assign({}, rest), { order: itemOrder }));
+});
+export const LabelAddedPayloadSchema = z.object(Object.assign(Object.assign({}, BaseWebhookEnvelopeShape), { eventName: z.literal(LabelWebhookEventEnum.Added), eventData: WebhookLabelSchema }));
+export const LabelUpdatedPayloadSchema = z.object(Object.assign(Object.assign({}, BaseWebhookEnvelopeShape), { eventName: z.literal(LabelWebhookEventEnum.Updated), eventData: WebhookLabelSchema }));
+export const LabelDeletedPayloadSchema = z.object(Object.assign(Object.assign({}, BaseWebhookEnvelopeShape), { eventName: z.literal(LabelWebhookEventEnum.Deleted), eventData: WebhookLabelSchema }));