@doist/todoist-sdk 9.3.0 → 9.5.0

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,51 @@
+import { z } from 'zod';
+import { WEBHOOK_EVENTS, WebhookEventSchema } from '../apps/types.js';
+import { COMMENT_WEBHOOK_EVENTS, CommentAddedPayloadSchema, CommentDeletedPayloadSchema, CommentUpdatedPayloadSchema, } from './comments.js';
+import { BaseWebhookEnvelopeShape } from './envelope.js';
+import { LABEL_WEBHOOK_EVENTS, LabelAddedPayloadSchema, LabelDeletedPayloadSchema, LabelUpdatedPayloadSchema, } from './labels.js';
+import { TASK_WEBHOOK_EVENTS, TaskAddedPayloadSchema, TaskCompletedPayloadSchema, TaskDeletedPayloadSchema, TaskUncompletedPayloadSchema, TaskUpdatedPayloadSchema, } from './tasks.js';
+/**
+ * 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 = [
+    ...TASK_WEBHOOK_EVENTS,
+    ...COMMENT_WEBHOOK_EVENTS,
+    ...LABEL_WEBHOOK_EVENTS,
+];
+const untypedEventNames = 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).
+ */
+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}; `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).
+ */
+export const WebhookPayloadSchema = z.discriminatedUnion('eventName', [
+    TaskAddedPayloadSchema,
+    TaskUpdatedPayloadSchema,
+    TaskCompletedPayloadSchema,
+    TaskUncompletedPayloadSchema,
+    TaskDeletedPayloadSchema,
+    CommentAddedPayloadSchema,
+    CommentUpdatedPayloadSchema,
+    CommentDeletedPayloadSchema,
+    LabelAddedPayloadSchema,
+    LabelUpdatedPayloadSchema,
+    LabelDeletedPayloadSchema,
+    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/test-utils/webhook-fixtures.d.ts

@@ -0,0 +1,13 @@
+export declare const CLIENT_SECRET = "test-client-secret";
+/** HMAC-SHA256 signs a raw body with the test client secret (or an override). */
+export declare function sign(body: string, secret?: string): string;
+/**
+ * Snake_case task payload matching the v1 webhook wire shape.
+ */
+export declare function rawTask(overrides?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * 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 declare function envelope(event: string, eventData: unknown, extra?: Record<string, unknown>): Record<string, unknown>;

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';