@baack-software/baack-ts-tasks 0.0.0-stage → 0.0.1

package/dist/server/webhooks.js

@@ -0,0 +1,243 @@
+import { isBaackApiError } from '@baack-software/baack-ts-client';
+import { parseTimestamp } from "../time.js";
+/**
+ * Receiving Baack webhooks: verifying a delivery's signature, reading its event, and fetching the task it is about.
+ * Uses Web Crypto and the Fetch API types only, so it runs on Node 20+, Deno, Bun and edge runtimes.
+ *
+ * A delivery is a POST whose body is a webhook event, an envelope naming what changed (`trigger`) and where it is
+ * (`v1`), without the changed representation itself; read it from the API. Its headers:
+ *
+ * - `Signature`: base64 HMAC-SHA256, keyed with the subscription's secret, over the UTF-8 bytes of the parts
+ *   `Signed-Headers` lists, in that order and without separators. Today that is the body, then `Last-Modified`, then
+ *   `Idempotency-Key`.
+ * - `Last-Modified`: when the trigger happened, an ISO local date-time (UTC, without a zone, like other Baack
+ *   timestamps), signed as sent.
+ * - `Idempotency-Key`: the trigger's URN. Retries carry the same key, so handle each key once.
+ * - `X-Attempt-Number` and `X-Attempts-Remaining`: where a delivery is in its retries.
+ */
+/** Header names, lower case as the Fetch API's `Headers` and Node's `IncomingMessage` give them. */
+export const WEBHOOK_HEADERS = {
+    signature: 'signature',
+    signedHeaders: 'signed-headers',
+    timestamp: 'last-modified',
+    idempotencyKey: 'idempotency-key',
+    attempt: 'x-attempt-number',
+    attemptsRemaining: 'x-attempts-remaining',
+};
+/** What a delivery signs when it doesn't say, the order the API uses. */
+export const DEFAULT_SIGNED_PARTS = ['body', WEBHOOK_HEADERS.timestamp, WEBHOOK_HEADERS.idempotencyKey];
+/** Thrown when a delivery can't be trusted or read. Answer 401 (or 400 for `malformed-event`) and don't act on it. */
+export class WebhookVerificationError extends Error {
+    reason;
+    name = 'WebhookVerificationError';
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+}
+/**
+ * Checks a delivery's signature and returns its event. `body` must be the raw bytes or text as received: parsing and
+ * re-serialising the JSON changes the bytes and the signature won't match. Throws `WebhookVerificationError`.
+ */
+export async function verifyWebhook(delivery, secret, options = {}) {
+    const header = (name) => readHeader(delivery.headers, name);
+    const signature = header(WEBHOOK_HEADERS.signature);
+    if (!signature)
+        throw new WebhookVerificationError('missing-signature', 'The delivery has no Signature header.');
+    const listed = header(WEBHOOK_HEADERS.signedHeaders);
+    const parts = listed ? listed.split(',').map((part) => part.trim().toLowerCase()) : [...DEFAULT_SIGNED_PARTS];
+    // A signature that doesn't cover the body proves nothing about the event.
+    if (!parts.includes('body'))
+        throw new WebhookVerificationError('unsigned-body', 'Signed-Headers does not include the body.');
+    const body = typeof delivery.body === 'string' ? encoder.encode(delivery.body) : delivery.body;
+    const signed = [];
+    for (const part of parts) {
+        if (part === 'body') {
+            signed.push(body);
+            continue;
+        }
+        const value = header(part);
+        if (value === undefined)
+            throw new WebhookVerificationError('missing-header', `The signed header ${part} is missing.`);
+        signed.push(encoder.encode(value));
+    }
+    const expected = decodeBase64(signature);
+    const key = await hmacKey(secret, ['verify']);
+    // Web Crypto's verify compares in constant time.
+    if (!expected || !(await crypto.subtle.verify('HMAC', key, expected, concat(signed)))) {
+        throw new WebhookVerificationError('bad-signature', 'The signature does not match.');
+    }
+    const timestamp = header(WEBHOOK_HEADERS.timestamp) ?? '';
+    if (options.maxAgeMs !== undefined) {
+        // Zoneless, so parseTimestamp (UTC) rather than Date.parse, which would read it as local time.
+        const at = parseTimestamp(timestamp)?.getTime();
+        const now = (options.now ?? new Date()).getTime();
+        if (at === undefined || now - at > options.maxAgeMs) {
+            throw new WebhookVerificationError('stale', `The delivery is from ${timestamp || 'an unknown time'}, too long ago.`);
+        }
+    }
+    const event = parseWebhookEvent(typeof delivery.body === 'string' ? delivery.body : decoder.decode(delivery.body));
+    const idempotencyKey = header(WEBHOOK_HEADERS.idempotencyKey) ?? event.trigger.urn;
+    const attempt = toNumber(header(WEBHOOK_HEADERS.attempt));
+    const attemptsRemaining = toNumber(header(WEBHOOK_HEADERS.attemptsRemaining));
+    return {
+        event,
+        idempotencyKey,
+        timestamp,
+        ...(attempt === undefined ? {} : { attempt }),
+        ...(attemptsRemaining === undefined ? {} : { attemptsRemaining }),
+    };
+}
+/** `verifyWebhook` for a Fetch API `Request`, reading its body. */
+export async function verifyWebhookRequest(request, secret, options) {
+    const body = new Uint8Array(await request.arrayBuffer());
+    return verifyWebhook({ body, headers: request.headers }, secret, options);
+}
+/** Reads a delivery's body as a webhook event, checking the parts handlers rely on. Throws `WebhookVerificationError`. */
+export function parseWebhookEvent(body) {
+    let value;
+    try {
+        value = JSON.parse(body);
+    }
+    catch {
+        throw new WebhookVerificationError('malformed-event', 'The body is not JSON.');
+    }
+    const trigger = value?.trigger;
+    if (!trigger || typeof trigger.urn !== 'string' || typeof trigger.subject !== 'string' || typeof trigger.event !== 'string') {
+        throw new WebhookVerificationError('malformed-event', 'The event has no trigger with a urn, subject and event.');
+    }
+    return value;
+}
+/** The URN of the representation an event is about. */
+export function webhookTarget(event) {
+    return event.v1?.urn || event.trigger.targetUrn || undefined;
+}
+/**
+ * Signs a delivery the way the API does, returning the headers to send with `body`. For tests and for replaying or
+ * simulating deliveries locally.
+ */
+export async function signWebhook(body, secret, { timestamp, idempotencyKey }) {
+    const key = await hmacKey(secret, ['sign']);
+    const data = concat([encoder.encode(body), encoder.encode(timestamp), encoder.encode(idempotencyKey)]);
+    const mac = new Uint8Array(await crypto.subtle.sign('HMAC', key, data));
+    return {
+        Signature: encodeBase64(mac),
+        'Signed-Headers': DEFAULT_SIGNED_PARTS.join(','),
+        'Last-Modified': timestamp,
+        'Idempotency-Key': idempotencyKey,
+    };
+}
+/**
+ * The task an event is about, read fresh, since events don't carry it. `null` when the task was deleted, by the event
+ * or since. Throws for events about anything but a task.
+ */
+export async function taskFromWebhook(event, tasks) {
+    if (event.trigger.subject !== 'TASK')
+        throw new TypeError(`The event is about a ${event.trigger.subject}, not a task.`);
+    const urn = webhookTarget(event);
+    if (!urn || event.trigger.event === 'DELETE')
+        return null;
+    try {
+        return await tasks.get(urn);
+    }
+    catch (error) {
+        if (isBaackApiError(error) && error.isNotFound)
+            return null;
+        throw error;
+    }
+}
+/**
+ * Keys held in memory for `ttlMs` (default a day). Enough for one process; use a shared store (a database row with
+ * a unique key, Redis `SET NX`) when several handle deliveries.
+ */
+export function memoryIdempotencyStore(ttlMs = 24 * 3600_000) {
+    const seen = new Map();
+    return {
+        claim(key) {
+            const now = Date.now();
+            for (const [old, at] of seen)
+                if (now - at > ttlMs)
+                    seen.delete(old);
+            if (seen.has(key))
+                return false;
+            seen.set(key, now);
+            return true;
+        },
+        release(key) {
+            seen.delete(key);
+        },
+    };
+}
+/**
+ * A Fetch API handler (`(request) => Response`) for a webhook endpoint: verifies, skips repeats, and runs `onEvent`.
+ * Answers 401 to an untrusted delivery, 400 to an unreadable one, 200 once handled or already handled.
+ */
+export function webhookHandler(options) {
+    const idempotency = options.idempotency ?? memoryIdempotencyStore();
+    return async (request) => {
+        let delivery;
+        try {
+            delivery = await verifyWebhookRequest(request, options.secret, options.verify);
+        }
+        catch (error) {
+            if (error instanceof WebhookVerificationError) {
+                return new Response(error.message, { status: error.reason === 'malformed-event' ? 400 : 401 });
+            }
+            throw error;
+        }
+        if (!(await idempotency.claim(delivery.idempotencyKey)))
+            return new Response('Already handled', { status: 200 });
+        try {
+            await options.onEvent(delivery);
+        }
+        catch (error) {
+            // Not handled after all: let the retry run it.
+            await idempotency.release?.(delivery.idempotencyKey);
+            throw error;
+        }
+        return new Response('OK', { status: 200 });
+    };
+}
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function hmacKey(secret, usages) {
+    return crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, usages);
+}
+function readHeader(headers, name) {
+    if (typeof headers.get === 'function')
+        return headers.get(name) ?? undefined;
+    const record = headers;
+    const key = Object.keys(record).find((k) => k.toLowerCase() === name);
+    const value = key === undefined ? undefined : record[key];
+    return Array.isArray(value) ? value.join(', ') : value;
+}
+function concat(parts) {
+    const result = new Uint8Array(parts.reduce((length, part) => length + part.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        result.set(part, offset);
+        offset += part.length;
+    }
+    return result;
+}
+function encodeBase64(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+function decodeBase64(text) {
+    try {
+        return Uint8Array.from(atob(text.trim()), (char) => char.charCodeAt(0));
+    }
+    catch {
+        return undefined;
+    }
+}
+function toNumber(value) {
+    if (value === undefined || value === '')
+        return undefined;
+    const number = Number(value);
+    return Number.isFinite(number) ? number : undefined;
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/server/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../../src/server/webhooks.ts"],"names":[],"mappings":"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"}

package/dist/store.d.ts

@@ -0,0 +1,124 @@
+import { type SearchItem, type Task, type TaskLog, type TaskPriority, type TaskStatus, type Workflow } from '@baack-software/baack-ts-client';
+import type { TaskField } from './conflicts.ts';
+import { type DraftInput } from './draft.ts';
+import type { ChangeOptions, TaskClient } from './task-client.ts';
+import { type TaskComparator, type TaskFilter, type TaskGrouping } from './tasks.ts';
+import type { RefLike, TaskDraft, TaskInput, TaskListField } from './types.ts';
+export interface TaskStoreOptions {
+    /** The company whose tasks the store holds. */
+    owner: RefLike;
+    /** The identity changes are attributed to in the activity log, unless a change names another. */
+    actor?: RefLike;
+    /** Load identities and projects for names and pickers. Default true. */
+    includeRelated?: boolean;
+    /**
+     * Workflows whose stages tasks can move through, loaded with the tasks for stage columns and pickers. The API has
+     * no way to list them, so the app names them. One that can't be read is left out.
+     */
+    workflows?: readonly RefLike[];
+    /**
+     * The server can change a task after accepting a write. This long after each write, the store reads the task (and
+     * its log, if loaded) again. Default 500 ms; 0 turns it off.
+     */
+    settleMs?: number;
+}
+export type LoadStatus = 'idle' | 'loading' | 'ready' | 'error';
+export interface TaskLogState {
+    status: LoadStatus;
+    /** Newest first. */
+    logs: readonly TaskLog[];
+    /** Set while older pages remain. */
+    after?: string;
+    error?: unknown;
+}
+/** A snapshot of the store. Each change replaces it, so it can be compared by reference. */
+export interface TaskStoreState {
+    status: LoadStatus;
+    error?: unknown;
+    /** Tasks as the reader should see them, pending changes applied, in search order with new tasks first. */
+    tasks: readonly Task[];
+    byUrn: ReadonlyMap<string, Task>;
+    identities: ReadonlyMap<string, SearchItem>;
+    projects: ReadonlyMap<string, SearchItem>;
+    /** The workflows named in the options, by URN, in the order named. */
+    workflows: ReadonlyMap<string, Workflow>;
+    /** URNs of tasks with a write in flight. */
+    saving: ReadonlySet<string>;
+    /** Activity logs of the tasks whose logs were loaded. */
+    logs: ReadonlyMap<string, TaskLogState>;
+    /**
+     * Fields someone else changed while this person was editing, found when one of their changes was saved, by task
+     * URN. Kept until `dismissChangedElsewhere`.
+     */
+    changedElsewhere: ReadonlyMap<string, readonly (TaskField | TaskListField)[]>;
+}
+/**
+ * Holds a company's tasks for a UI: loads them, applies changes straight away and rolls them back if the server
+ * refuses, and notifies subscribers. `subscribe` and `getState` fit React's `useSyncExternalStore`.
+ *
+ * ```ts
+ * const store = new TaskStore(tasks, { owner: companyUrn, actor: me });
+ * store.subscribe(() => render(selectTasks(store.getState(), { assignee: [me], open: true }, byUrgency)));
+ * await store.load();
+ * await store.setStatus(urn, 'COMPLETED');
+ * ```
+ */
+export declare class TaskStore {
+    #private;
+    readonly client: TaskClient;
+    readonly options: TaskStoreOptions;
+    constructor(client: TaskClient, options: TaskStoreOptions);
+    getState: () => TaskStoreState;
+    subscribe: (listener: () => void) => (() => void);
+    /** The task as the reader should see it. */
+    get(task: RefLike): Task | undefined;
+    /** Stops pending work and drops subscribers. */
+    dispose(): void;
+    /** Loads (or reloads) every task. A load already running is cancelled. Pending changes stay applied. */
+    load(): Promise<void>;
+    /** Reads one task again. Removes it when it no longer exists. */
+    reload(task: RefLike): Promise<Task | undefined>;
+    create(input: TaskDraft | Omit<DraftInput, 'owner'>, options?: ChangeOptions): Promise<Task>;
+    /**
+     * Shows `changes` at once and sends them. On success the server's task replaces the shown one; on failure the
+     * change is rolled back and the error rethrown.
+     *
+     * The change is checked against the task as shown when it was made. If someone else changed one of the same fields
+     * since, it throws `TaskConflictError`, saves nothing and shows the task as it is now; resolve the conflict with
+     * `resolveConflicts` and update again. Other fields they changed are kept and listed in `changedElsewhere`.
+     */
+    update(task: RefLike, changes: TaskInput, options?: ChangeOptions): Promise<Task>;
+    /** Clears the note of fields someone else changed on the task. */
+    dismissChangedElsewhere(task: RefLike): void;
+    delete(task: RefLike): Promise<void>;
+    setStatus(task: RefLike, status: TaskStatus, options?: ChangeOptions): Promise<Task>;
+    setPriority(task: RefLike, priority: TaskPriority, options?: ChangeOptions): Promise<Task>;
+    assign(task: RefLike, assignee: RefLike | null, options?: ChangeOptions): Promise<Task>;
+    setDue(task: RefLike, dueTimestamp: string | null, options?: ChangeOptions): Promise<Task>;
+    setProject(task: RefLike, project: RefLike | null, options?: ChangeOptions): Promise<Task>;
+    setWorkflowStage(task: RefLike, stage: RefLike | null, options?: ChangeOptions): Promise<Task>;
+    addBlocker(task: RefLike, blocker: RefLike, options?: ChangeOptions): Promise<Task>;
+    removeBlocker(task: RefLike, blocker: RefLike, options?: ChangeOptions): Promise<Task>;
+    /** Adds a reference to one of the task's lists, building on pending changes. */
+    addTo(task: RefLike, field: TaskListField, value: RefLike, options?: ChangeOptions): Promise<Task>;
+    /** Removes a reference from one of the task's lists, building on pending changes. */
+    removeFrom(task: RefLike, field: TaskListField, value: RefLike, options?: ChangeOptions): Promise<Task>;
+    /** Loads the newest page of the task's log, replacing what was loaded. */
+    loadLogs(task: RefLike): Promise<void>;
+    /** Loads the next older page of the task's log, if there is one. */
+    loadMoreLogs(task: RefLike): Promise<void>;
+    /** Adds a comment and shows it at the top of the task's log. */
+    comment(task: RefLike, text: string, options?: {
+        actor?: RefLike;
+        replyTo?: RefLike;
+    }): Promise<TaskLog>;
+}
+/** Tasks matching `filter`, sorted when a comparator is given. */
+export declare function selectTasks(state: TaskStoreState, filter?: TaskFilter, sort?: TaskComparator): Task[];
+/** Tasks matching `filter`, grouped for a board, each group sorted when a comparator is given. */
+export declare function selectGroups(state: TaskStoreState, by: TaskGrouping, filter?: TaskFilter, sort?: TaskComparator): Map<string, Task[]>;
+/** The display name of an identity, project, task or workflow stage, falling back to the end of its URN. */
+export declare function selectName(state: TaskStoreState, item: RefLike): string;
+/** The URNs of the open tasks blocking `task`, by the store's tasks. */
+export declare function selectOpenBlockers(state: TaskStoreState, task: Task): string[];
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}