slicetest 0.7.0 → 0.9.0

package/dist/scenario.js

@@ -6,25 +6,41 @@ const slot = globalThis;
 export function setRuntime(runtime) {
     slot[KEY] = runtime;
 }
+/**
+ * Whether a scenario with `tags` runs under `filter` (`SLICETEST_TAGS`): comma- or space-separated tags,
+ * any of which it must have, and `!tag`s it must not have. No filter runs everything.
+ */
+export function tagsSelected(tags = [], filter = process.env.SLICETEST_TAGS) {
+    const terms = (filter ?? "").split(/[\s,]+/).filter(Boolean);
+    const excluded = terms.filter((t) => t.startsWith("!")).map((t) => t.slice(1));
+    const wanted = terms.filter((t) => !t.startsWith("!"));
+    if (tags.some((t) => excluded.includes(t)))
+        return false;
+    return wanted.length === 0 || tags.some((t) => wanted.includes(t));
+}
 function define(register) {
-    return (name, body, timeout) => register(name, async ({ onTestFailed, task }) => {
-        const runtime = slot[KEY];
-        if (!runtime) {
-            throw new Error("slicetest: runtime not started. Add the slicetest() plugin to your vitest config.");
-        }
-        if (task.concurrent) {
-            throw new Error("slicetest: scenarios share one app and database per file, so they can't run concurrently. Remove .concurrent / sequence.concurrent.");
-        }
-        const file = task.file?.filepath ?? task.file?.name ?? "";
-        onTestFailed(async () => {
-            console.error(`--- slicetest ---\n${await runtime.diagnostics()}\n-----------------`);
-            await runtime.reportDiagram(file, task.name, true);
-        });
-        await runtime.beforeScenario();
-        await body(runtime.context());
-        await runtime.afterScenario();
-        await runtime.reportDiagram(file, task.name, false);
-    }, timeout);
+    return (name, body, options) => {
+        const { timeout, tags } = typeof options === "number" ? { timeout: options, tags: undefined } : (options ?? {});
+        // Scenarios the tag filter leaves out show as skipped, so the filter is visible in the summary.
+        return (tagsSelected(tags) ? register : test.skip)(name, async ({ onTestFailed, task }) => {
+            const runtime = slot[KEY];
+            if (!runtime) {
+                throw new Error("slicetest: runtime not started. Add the slicetest() plugin to your vitest config.");
+            }
+            if (task.concurrent) {
+                throw new Error("slicetest: scenarios share one app and database per file, so they can't run concurrently. Remove .concurrent / sequence.concurrent.");
+            }
+            const file = task.file?.filepath ?? task.file?.name ?? "";
+            onTestFailed(async () => {
+                console.error(`--- slicetest ---\n${await runtime.diagnostics()}\n-----------------`);
+                await runtime.reportDiagram(file, task.name, true);
+            });
+            await runtime.beforeScenario();
+            await body(runtime.context());
+            await runtime.afterScenario();
+            await runtime.reportDiagram(file, task.name, false);
+        }, timeout);
+    };
 }
 /**
  * A test that runs against the real app. The database is reset to the
@@ -36,10 +52,10 @@ export const scenario = Object.assign(define(test), {
     todo: (name) => test.todo(name),
     /** Same scenario for each row: `scenario.each(rows)("name %s", async (row, ctx) => ...)`. */
     each(rows) {
-        return (name, body, timeout) => {
+        return (name, body, options) => {
             rows.forEach((row, i) => {
                 const title = format(name, row, i);
-                define(test)(title, (ctx) => body(row, ctx), timeout);
+                define(test)(title, (ctx) => body(row, ctx), options);
             });
         };
     },

package/dist/sql-migrations.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Files `migrate: { sql }` applies, in order: the file itself, or a directory's `.sql` files (and
+ * Diesel's `<version>_<name>/up.sql`) sorted by name with numbers compared as numbers. Rollback
+ * files are left out: golang-migrate / sqlx `*.down.sql`, Diesel's `down.sql` and Flyway undo
+ * migrations (`U2__…`).
+ */
+export declare function sqlMigrationFiles(target: string): Promise<string[]>;
+/** The statements of a migration file that migrate up: without a goose or dbmate down section. */
+export declare function upSection(sql: string): string;
+/** Apply `files` in order with `exec`, naming the file that fails. */
+export declare function applySqlFiles(files: string[], exec: (sql: string) => Promise<unknown>, root: string): Promise<void>;

package/dist/sql-migrations.js

@@ -0,0 +1,38 @@
+import { existsSync } from "node:fs";
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+/** Version numbers compare as numbers: Flyway's `V2__` comes before `V10__`. */
+const byVersion = new Intl.Collator("en", { numeric: true }).compare;
+/**
+ * Files `migrate: { sql }` applies, in order: the file itself, or a directory's `.sql` files (and
+ * Diesel's `<version>_<name>/up.sql`) sorted by name with numbers compared as numbers. Rollback
+ * files are left out: golang-migrate / sqlx `*.down.sql`, Diesel's `down.sql` and Flyway undo
+ * migrations (`U2__…`).
+ */
+export async function sqlMigrationFiles(target) {
+    if (!(await stat(target)).isDirectory())
+        return [target];
+    const entries = await readdir(target, { withFileTypes: true });
+    const files = entries.filter((e) => e.isFile() && e.name.toLowerCase().endsWith(".sql") && !/\.down\.sql$/i.test(e.name) && !/^U\d+(\.\d+)*__/.test(e.name)).map((e) => e.name);
+    // Diesel: one directory per migration, holding up.sql and down.sql.
+    const dirs = entries.filter((e) => e.isDirectory() && existsSync(path.join(target, e.name, "up.sql"))).map((e) => path.join(e.name, "up.sql"));
+    return [...files, ...dirs].sort(byVersion).map((f) => path.join(target, f));
+}
+/** Where a migration's rollback section starts in goose (`-- +goose Down`) and dbmate (`-- migrate:down`) files. */
+const DOWN = /^--\s*(\+goose\s+down|migrate:down)\b/im;
+/** The statements of a migration file that migrate up: without a goose or dbmate down section. */
+export function upSection(sql) {
+    const m = DOWN.exec(sql);
+    return m ? sql.slice(0, m.index) : sql;
+}
+/** Apply `files` in order with `exec`, naming the file that fails. */
+export async function applySqlFiles(files, exec, root) {
+    for (const file of files) {
+        try {
+            await exec(upSection(await readFile(file, "utf8")));
+        }
+        catch (e) {
+            throw new Error(`slicetest: db.migrate.sql: ${path.relative(root, file) || file}: ${e.message}`, { cause: e });
+        }
+    }
+}

package/dist/stub.d.ts

@@ -8,6 +8,13 @@ export interface RecordedCall {
     body: string;
     /** Parsed JSON body, or undefined when the body isn't JSON. */
     json: any;
+    /**
+     * Fields of an `application/x-www-form-urlencoded` body (Stripe, Twilio, OAuth token requests),
+     * with bracket keys nested as the providers read them: `metadata[order]=7&items[0][price]=p_1`
+     * is `{ metadata: { order: "7" }, items: [{ price: "p_1" }] }`. For `multipart/form-data`, the
+     * fields with files as `{ filename, type, size, text }`. Undefined for other bodies.
+     */
+    form?: Record<string, unknown>;
     /** Values captured by `:name` segments of the matching route's path. */
     params: Record<string, string>;
     /** Whether a registered route answered this call. */
@@ -47,7 +54,7 @@ export interface ChaosOptions {
 export interface StubResponse {
     status?: number;
     headers?: Record<string, string>;
-    /** Objects are sent as JSON. */
+    /** Strings and bytes (`Uint8Array`, `ArrayBuffer`) are sent as they are; anything else as JSON. */
     body?: unknown;
 }
 /** One server-sent event: `[event, data]`, or `{ event, data, id }`. Data that isn't a string is sent as JSON. */
@@ -68,9 +75,12 @@ export type Responder = StubResponse | ((call: RecordedCall) => StubResponse | P
  * `expect.*` asymmetric matchers receive the actual value.
  */
 export interface MatchOptions {
-    query?: Record<string, Matcher>;
+    /** A list matches a repeated parameter's values in order: `{ ids: ["1", "2"] }` for `?ids=1&ids=2`. */
+    query?: Record<string, Matcher | Matcher[]>;
     headers?: Record<string, Matcher>;
     json?: unknown;
+    /** Subset of a form-encoded body's fields (`call.form`). Numbers and booleans compare as the strings sent. */
+    form?: Record<string, unknown>;
     body?: Matcher;
     /** A GraphQL request for this operation (its name, or a RegExp), with `variables` as a subset. */
     graphql?: {
@@ -128,6 +138,7 @@ export declare class Stub {
     /**
      * Answer `method path`. `path` may contain `:name` segments (captured into
      * `call.params`) or be a RegExp; `method` may be `*`. Later routes win.
+     * A query in `path` (`/search?q=tea`) is a condition on those parameters; others may come along.
      */
     on(method: string, path: string | RegExp, match?: MatchOptions): RouteBuilder;
     /**
@@ -151,7 +162,12 @@ export declare class Stub {
     /** The active `chaos()` settings and what they did, for failure output; undefined when off. */
     describeChaos(): string | undefined;
     /** Calls received so far, optionally filtered by method, path and conditions (same syntax as `on()`). */
-    calls(method?: string, path?: string | RegExp, match?: MatchOptions): RecordedCall[];
+    calls(method?: string, fullPath?: string | RegExp, fullMatch?: MatchOptions): RecordedCall[];
+    /** Calls whose reply function or fallback threw, with the error; the app got a 500 (502 for a fallback). */
+    handlerErrors(): {
+        call: RecordedCall;
+        error: unknown;
+    }[];
     unmatched(): RecordedCall[];
     /** Routes registered in this scenario that no call reached, except `optional()` ones. */
     unusedRoutes(): string[];
@@ -173,4 +189,17 @@ export declare class Stub {
 }
 /** `expected` is contained in `actual`: objects compare key by key, arrays element-wise. */
 export declare function subset(expected: unknown, actual: unknown): boolean;
+/**
+ * A form body as nested fields, the way Rack, PHP and Stripe read bracket keys: `a[b]=1` is
+ * `{ a: { b: "1" } }`, `a[]=1&a[]=2` and `a[0]=1&a[1]=2` are arrays, and a plain key sent
+ * twice (`to=1&to=2`) becomes an array too.
+ */
+export declare function parseForm(body: string): Record<string, unknown>;
+/** A file in a multipart body, as `call.form` shows it. `text` only for text, JSON, XML and CSV files. */
+export interface UploadedFile {
+    filename: string;
+    type: string;
+    size: number;
+    text?: string;
+}
 export {};

package/dist/stub.js

@@ -30,6 +30,8 @@ export class Stub {
     /** Appended to the 501 answer for a call nothing could answer. */
     #hint;
     #chaos;
+    /** Reply functions (and fallbacks) that threw: the app got a 500 / 502, the scenario must fail with the error. */
+    #errors = [];
     url = "";
     constructor(name) {
         this.name = name;
@@ -54,6 +56,7 @@ export class Stub {
     /**
      * Answer `method path`. `path` may contain `:name` segments (captured into
      * `call.params`) or be a RegExp; `method` may be `*`. Later routes win.
+     * A query in `path` (`/search?q=tea`) is a condition on those parameters; others may come along.
      */
     on(method, path, match = {}) {
         return this.#on(method, path, match);
@@ -77,7 +80,8 @@ export class Stub {
         };
         return gql;
     }
-    #on(method, path, match, label) {
+    #on(method, fullPath, fullMatch, label) {
+        const { path, match } = splitQuery(fullPath, fullMatch);
         const { pattern, paramNames } = compilePath(path);
         const route = {
             method: method.toUpperCase(),
@@ -179,12 +183,17 @@ export class Stub {
         this.#send(call, res, { status: fault.status, headers: retry, body: { error: "slicetest chaos", status: fault.status } });
     }
     /** Calls received so far, optionally filtered by method, path and conditions (same syntax as `on()`). */
-    calls(method, path, match = {}) {
+    calls(method, fullPath, fullMatch = {}) {
+        const { path, match } = fullPath === undefined ? { path: undefined, match: fullMatch } : splitQuery(fullPath, fullMatch);
         const compiled = path === undefined ? undefined : compilePath(path);
         return this.#calls.filter((c) => (!method || method === "*" || c.method === method.toUpperCase()) &&
             (!compiled || matchPath(path, compiled.pattern, c.path) !== undefined) &&
             matchConditions(match, c));
     }
+    /** Calls whose reply function or fallback threw, with the error; the app got a 500 (502 for a fallback). */
+    handlerErrors() {
+        return this.#errors;
+    }
     unmatched() {
         return this.#calls.filter((c) => !c.matched);
     }
@@ -239,6 +248,7 @@ export class Stub {
         this.#routes = [];
         this.#calls = [];
         this.#chaos = undefined;
+        this.#errors = [];
     }
     /**
      * Answer calls that no registered route matches, instead of failing with 501.
@@ -259,7 +269,9 @@ export class Stub {
         const chunks = [];
         for await (const chunk of req)
             chunks.push(chunk);
-        const body = Buffer.concat(chunks).toString("utf8");
+        const raw = Buffer.concat(chunks);
+        const body = raw.toString("utf8");
+        const contentType = req.headers["content-type"] ?? "";
         const url = new URL(req.url ?? "/", this.url);
         const call = {
             method: req.method ?? "GET",
@@ -268,6 +280,7 @@ export class Stub {
             headers: req.headers,
             body,
             json: parseJson(body),
+            form: isForm(contentType) ? parseForm(body) : /^multipart\/form-data/i.test(contentType) ? await parseMultipart(raw, contentType) : undefined,
             params: {},
             matched: false,
         };
@@ -300,6 +313,7 @@ export class Stub {
                 out = await this.#fallback?.(call);
             }
             catch (e) {
+                this.#errors.push({ call, error: e });
                 res.writeHead(502, { "content-type": "text/plain" }).end(e.message);
                 return;
             }
@@ -327,10 +341,15 @@ export class Stub {
             this.#send(call, res, typeof route.respond === "function" ? await route.respond(call) : route.respond);
         }
         catch (e) {
+            this.#errors.push({ call, error: e });
             res.writeHead(500).end(`slicetest: stub handler threw: ${e}`);
         }
     }
     #send(call, res, out) {
+        if (out.body instanceof ArrayBuffer || (ArrayBuffer.isView(out.body) && !(out.body instanceof Uint8Array))) {
+            const view = out.body;
+            out = { ...out, body: view instanceof ArrayBuffer ? new Uint8Array(view) : new Uint8Array(view.buffer, view.byteOffset, view.byteLength) };
+        }
         const raw = out.body === undefined || typeof out.body === "string" || out.body instanceof Uint8Array;
         const headers = { ...out.headers };
         if (!raw && !Object.keys(headers).some((h) => h.toLowerCase() === "content-type")) {
@@ -346,6 +365,15 @@ export class Stub {
         res.end(payload);
     }
 }
+/** `/search?q=tea` is the path `/search` with the query condition `q: "tea"`; `match.query` wins over the path's. */
+function splitQuery(path, match) {
+    if (typeof path !== "string" || !path.includes("?"))
+        return { path, match };
+    const [bare, search] = [path.slice(0, path.indexOf("?")), path.slice(path.indexOf("?") + 1)];
+    const params = new URLSearchParams(search);
+    const query = Object.fromEntries([...new Set(params.keys())].map((k) => [k, params.getAll(k).length > 1 ? params.getAll(k) : params.get(k)]));
+    return { path: bare || "/", match: { ...match, query: { ...query, ...match.query } } };
+}
 function compilePath(path) {
     if (typeof path !== "string" || !path.includes("/:"))
         return { pattern: undefined, paramNames: [] };
@@ -371,12 +399,21 @@ function matchPath(path, pattern, actual, names = []) {
     if (!m)
         return undefined;
     const params = { ...m.groups };
-    names.forEach((n, i) => (params[n] = decodeURIComponent(m[i + 1])));
+    names.forEach((n, i) => (params[n] = decodeSegment(m[i + 1])));
     return params;
 }
+/** A path segment decoded, or as sent when it isn't valid percent-encoding (`%zz`), instead of dropping the call. */
+function decodeSegment(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
+}
 function matchConditions(match, call) {
     for (const [k, m] of Object.entries(match.query ?? {})) {
-        if (!test(m, call.query.get(k) ?? undefined))
+        if (!testQuery(m, call.query, k))
             return false;
     }
     for (const [k, m] of Object.entries(match.headers ?? {})) {
@@ -388,6 +425,8 @@ function matchConditions(match, call) {
         return false;
     if (match.json !== undefined && !subset(match.json, call.json))
         return false;
+    if (match.form !== undefined && !subset(formExpectation(match.form, call.form), call.form))
+        return false;
     if (match.graphql) {
         const g = call.graphql;
         if (!g)
@@ -403,9 +442,11 @@ function matchConditions(match, call) {
 /** The first condition of `match` that `call` fails, described; undefined when it meets them all. */
 function conditionMismatch(match, call) {
     for (const [k, m] of Object.entries(match.query ?? {})) {
-        const v = call.query.get(k) ?? undefined;
-        if (!test(m, v))
-            return `query ${k}: expected ${show(m)}, got ${v === undefined ? "nothing" : JSON.stringify(v)}`;
+        if (testQuery(m, call.query, k))
+            continue;
+        const all = call.query.getAll(k);
+        const got = all.length === 0 ? "nothing" : Array.isArray(m) || all.length > 1 ? JSON.stringify(all) : JSON.stringify(all[0]);
+        return `query ${k}: expected ${Array.isArray(m) ? `[${m.map(show).join(", ")}]` : show(m)}, got ${got}`;
     }
     for (const [k, m] of Object.entries(match.headers ?? {})) {
         const raw = call.headers[k.toLowerCase()];
@@ -422,6 +463,13 @@ function conditionMismatch(match, call) {
         if (diff)
             return diff;
     }
+    if (match.form !== undefined) {
+        if (call.form === undefined)
+            return `form: expected a form-encoded body, got ${call.body ? `${call.headers["content-type"] ?? "no content type"}: ${JSON.stringify(call.body.slice(0, 100))}` : "an empty body"}`;
+        const diff = difference(formExpectation(match.form, call.form), call.form, "form");
+        if (diff)
+            return diff;
+    }
     if (match.graphql) {
         const g = call.graphql;
         if (!g)
@@ -504,6 +552,13 @@ function distance(a, b) {
     }
     return row[b.length];
 }
+/** A query condition: one matcher for the first value, or a list for every value of a repeated parameter, in order. */
+function testQuery(m, query, key) {
+    if (!Array.isArray(m))
+        return test(m, query.get(key) ?? undefined);
+    const values = query.getAll(key);
+    return values.length === m.length && m.every((x, i) => test(x, values[i]));
+}
 function test(m, value) {
     if (isAsymmetric(m))
         return m.asymmetricMatch(value);
@@ -534,6 +589,91 @@ export function subset(expected, actual) {
 function isAsymmetric(m) {
     return !!m && typeof m === "object" && typeof m.asymmetricMatch === "function";
 }
+function isForm(contentType) {
+    return !!contentType && contentType.split(";")[0].trim().toLowerCase() === "application/x-www-form-urlencoded";
+}
+/** Keys kept as plain fields rather than nested into, so a body can't reach `Object.prototype`. */
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/**
+ * A form body as nested fields, the way Rack, PHP and Stripe read bracket keys: `a[b]=1` is
+ * `{ a: { b: "1" } }`, `a[]=1&a[]=2` and `a[0]=1&a[1]=2` are arrays, and a plain key sent
+ * twice (`to=1&to=2`) becomes an array too.
+ */
+export function parseForm(body) {
+    const out = {};
+    for (const [key, value] of new URLSearchParams(body)) {
+        const m = /^([^[\]]+)((?:\[[^\]]*\])*)$/.exec(key);
+        const path = m?.[2] ? [m[1], ...[...m[2].matchAll(/\[([^\]]*)\]/g)].map((x) => x[1])] : undefined;
+        // `__proto__[x]=1` is sent by whatever the app forwards; it must not reach Object.prototype.
+        if (!path || path.some((seg) => UNSAFE_KEYS.has(seg))) {
+            const prev = Object.hasOwn(out, key) ? out[key] : undefined;
+            Object.defineProperty(out, key, { value: prev === undefined ? value : Array.isArray(prev) ? [...prev, value] : [prev, value], enumerable: true, writable: true, configurable: true });
+            continue;
+        }
+        let node = out;
+        for (let i = 0; i < path.length; i++) {
+            const seg = path[i];
+            const last = i === path.length - 1;
+            const nextIsIndex = !last && (path[i + 1] === "" || /^\d+$/.test(path[i + 1]));
+            if (Array.isArray(node)) {
+                const index = seg === "" ? node.length : Number(seg);
+                if (last)
+                    node[index] = value;
+                else
+                    node = (node[index] ??= nextIsIndex ? [] : {});
+            }
+            else {
+                if (last)
+                    node[seg] = value;
+                else {
+                    const child = node[seg];
+                    node = (child && typeof child === "object" ? child : (node[seg] = nextIsIndex ? [] : {}));
+                }
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Form values arrive as strings: compare `amount: 2000` and `capture: true` with what was sent.
+ * Only where a string was sent, so an uploaded file's `size` stays a number.
+ */
+function formExpectation(expected, actual) {
+    if ((typeof expected === "number" || typeof expected === "boolean") && typeof actual === "string")
+        return String(expected);
+    if (Array.isArray(expected))
+        return expected.map((e, i) => formExpectation(e, Array.isArray(actual) ? actual[i] : undefined));
+    if (expected && typeof expected === "object" && !isAsymmetric(expected) && !(expected instanceof RegExp)) {
+        const at = (k) => (actual && typeof actual === "object" ? actual[k] : undefined);
+        return Object.fromEntries(Object.entries(expected).map(([k, v]) => [k, formExpectation(v, at(k))]));
+    }
+    return expected;
+}
+const TEXTUAL = /^(text\/|application\/(json|xml|csv|x-ndjson|yaml|javascript)|[^;]*\+(json|xml))/i;
+/** Fields of a `multipart/form-data` body, files as `{ filename, type, size, text }`. Undefined if it can't be parsed. */
+async function parseMultipart(raw, contentType) {
+    let data;
+    try {
+        data = await new Response(new Uint8Array(raw), { headers: { "content-type": contentType } }).formData();
+    }
+    catch {
+        return undefined;
+    }
+    const out = {};
+    for (const [key, value] of data) {
+        const v = typeof value === "string"
+            ? value
+            : {
+                filename: value.name,
+                type: value.type,
+                size: value.size,
+                ...(TEXTUAL.test(value.type) ? { text: await value.text() } : {}),
+            };
+        const prev = out[key];
+        out[key] = prev === undefined ? v : Array.isArray(prev) ? [...prev, v] : [prev, v];
+    }
+    return out;
+}
 function parseJson(body) {
     if (!body)
         return undefined;

package/dist/webhook.d.ts

@@ -8,12 +8,12 @@ export interface HmacScheme {
     /** Prepended to the digest, e.g. `sha256=`. */
     prefix?: string;
 }
-export type WebhookProvider = "stripe" | "github" | "slack" | "shopify" | "standard" | HmacScheme;
+export type WebhookProvider = "stripe" | "github" | "slack" | "shopify" | "standard" | "line" | "paddle" | "linear" | "gitlab" | "zoom" | "twitch" | "twilio" | HmacScheme;
 export interface WebhookOptions {
     provider: WebhookProvider;
     /** The signing secret the app is configured with. For `standard` (Svix), `whsec_<base64>` or the raw key. */
     secret: string;
-    /** Event type, sent where the provider puts it: `X-GitHub-Event`, `X-Shopify-Topic`. */
+    /** Event type, sent where the provider puts it: `X-GitHub-Event`, `X-Shopify-Topic`, `X-Gitlab-Event`, `Linear-Event`, `Twitch-Eventsub-Message-Type`. */
     event?: string;
     /** Unix seconds the signature is made for. Default: now. */
     timestamp?: number;
@@ -21,20 +21,29 @@ export interface WebhookOptions {
     stale?: boolean;
     /** Signed with a different secret: the app must refuse it. */
     invalidSignature?: boolean;
-    /** Message id for `standard` (`webhook-id`). Default: a random `msg_…`. */
+    /** Message id for `standard` (`webhook-id`, default a random `msg_…`) and `twitch`. */
     id?: string;
+    /**
+     * The URL the app sees the request at, for providers that sign it (Twilio). `http.webhook()` fills in
+     * the app's address and the path; set it when the app validates against a public URL it's configured with.
+     */
+    url?: string;
     /** Extra request headers. */
     headers?: Record<string, string>;
 }
+/** The providers `signWebhook` knows by name. */
+export declare const WEBHOOK_PROVIDERS: readonly ["stripe", "github", "slack", "shopify", "standard", "line", "paddle", "linear", "gitlab", "zoom", "twitch", "twilio"];
 /**
  * The headers a provider sends with `body`, signed with `secret` the way its
  * SDK verifies them: Stripe's `Stripe-Signature`, GitHub's
- * `X-Hub-Signature-256`, Slack's `v0` signature, Shopify's base64 HMAC and
- * Standard Webhooks (Svix, Resend, Clerk, …).
+ * `X-Hub-Signature-256`, Slack's `v0` signature, Shopify's base64 HMAC,
+ * Standard Webhooks (Svix, Resend, Clerk, …), LINE's `X-Line-Signature`,
+ * Paddle Billing's `Paddle-Signature`, Linear, GitLab's token, Zoom's `v0`
+ * signature and Twitch EventSub.
  */
 export declare function signWebhook(body: string, opts: WebhookOptions): Record<string, string>;
-/** The bytes to send and their content type: objects as JSON, URLSearchParams as a form (Slack commands), strings as-is. */
-export declare function webhookBody(payload: unknown): {
+/** The bytes to send and their content type: objects as JSON (as a form for Twilio), URLSearchParams as a form (Slack commands), strings as-is. */
+export declare function webhookBody(payload: unknown, provider?: WebhookProvider): {
     body: string;
     type: string;
 };

package/dist/webhook.js

@@ -1,10 +1,15 @@
 import { createHmac, randomUUID } from "node:crypto";
+import { encodeForm } from "./form.js";
+/** The providers `signWebhook` knows by name. */
+export const WEBHOOK_PROVIDERS = ["stripe", "github", "slack", "shopify", "standard", "line", "paddle", "linear", "gitlab", "zoom", "twitch", "twilio"];
 const hmac = (algorithm, key, data) => createHmac(algorithm, key).update(data);
 /**
  * The headers a provider sends with `body`, signed with `secret` the way its
  * SDK verifies them: Stripe's `Stripe-Signature`, GitHub's
- * `X-Hub-Signature-256`, Slack's `v0` signature, Shopify's base64 HMAC and
- * Standard Webhooks (Svix, Resend, Clerk, …).
+ * `X-Hub-Signature-256`, Slack's `v0` signature, Shopify's base64 HMAC,
+ * Standard Webhooks (Svix, Resend, Clerk, …), LINE's `X-Line-Signature`,
+ * Paddle Billing's `Paddle-Signature`, Linear, GitLab's token, Zoom's `v0`
+ * signature and Twitch EventSub.
  */
 export function signWebhook(body, opts) {
     const now = Math.floor(Date.now() / 1000);
@@ -38,15 +43,50 @@ export function signWebhook(body, opts) {
             const key = secret.startsWith("whsec_") ? Buffer.from(secret.slice(6), "base64") : Buffer.from(secret);
             return { "webhook-id": id, "webhook-timestamp": String(ts), "webhook-signature": `v1,${hmac("sha256", key, `${id}.${ts}.${body}`).digest("base64")}` };
         }
+        case "line":
+            return { "x-line-signature": hmac("sha256", secret, body).digest("base64") };
+        case "paddle":
+            return { "paddle-signature": `ts=${ts};h1=${hmac("sha256", secret, `${ts}:${body}`).digest("hex")}` };
+        case "linear":
+            return {
+                "linear-signature": hmac("sha256", secret, body).digest("hex"),
+                "linear-delivery": randomUUID(),
+                ...(opts.event ? { "linear-event": opts.event } : {}),
+            };
+        case "gitlab":
+            return { "x-gitlab-token": secret, "x-gitlab-event": opts.event ?? "Push Hook", "x-gitlab-event-uuid": randomUUID() };
+        case "zoom":
+            return { "x-zm-request-timestamp": String(ts), "x-zm-signature": `v0=${hmac("sha256", secret, `v0:${ts}:${body}`).digest("hex")}` };
+        case "twitch": {
+            const id = opts.id ?? randomUUID();
+            const at = new Date(ts * 1000).toISOString();
+            return {
+                "twitch-eventsub-message-id": id,
+                "twitch-eventsub-message-timestamp": at,
+                "twitch-eventsub-message-type": opts.event ?? "notification",
+                "twitch-eventsub-message-signature": `sha256=${hmac("sha256", secret, `${id}${at}${body}`).digest("hex")}`,
+            };
+        }
+        case "twilio": {
+            // Twilio's validateRequest: the URL, then each POST parameter's name and value, sorted by name; HMAC-SHA1, base64.
+            if (!opts.url)
+                throw new Error("slicetest: a twilio webhook is signed over its URL: pass `url`, or send it with http.webhook()");
+            const params = [...new URLSearchParams(body)].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+            return { "x-twilio-signature": hmac("sha1", secret, opts.url + params.map(([k, v]) => k + v).join("")).digest("base64") };
+        }
         default:
-            throw new Error(`slicetest: unknown webhook provider ${JSON.stringify(p)} (expected stripe, github, slack, shopify, standard or { header, prefix, encoding })`);
+            throw new Error(`slicetest: unknown webhook provider ${JSON.stringify(p)} (expected ${WEBHOOK_PROVIDERS.join(", ")} or { header, prefix, encoding })`);
     }
 }
-/** The bytes to send and their content type: objects as JSON, URLSearchParams as a form (Slack commands), strings as-is. */
-export function webhookBody(payload) {
+/** The bytes to send and their content type: objects as JSON (as a form for Twilio), URLSearchParams as a form (Slack commands), strings as-is. */
+export function webhookBody(payload, provider) {
+    const form = "application/x-www-form-urlencoded";
     if (typeof payload === "string")
-        return { body: payload, type: "application/json" };
+        return { body: payload, type: provider === "twilio" ? form : "application/json" };
     if (payload instanceof URLSearchParams)
-        return { body: payload.toString(), type: "application/x-www-form-urlencoded" };
+        return { body: payload.toString(), type: form };
+    // Twilio posts its parameters as a form.
+    if (provider === "twilio" && payload && typeof payload === "object")
+        return { body: encodeForm(payload).toString(), type: form };
     return { body: JSON.stringify(payload ?? {}), type: "application/json" };
 }

package/dist/yaml-runtime.d.ts

@@ -12,8 +12,9 @@ export declare function lookup(obj: unknown, path: string): unknown;
  */
 export declare function interpolate(value: unknown, vars: Vars): unknown;
 /**
- * `{ $type: number }`, `{ $regex: "^ch_" }`, `{ $contains: "x" }` and
- * `{ $any: true }` become Vitest asymmetric matchers.
+ * `{ $type: number }`, `{ $regex: "^ch_" }`, `{ $contains: "x" }`, `{ $any: true }`,
+ * `{ $gte: 1, $lt: 10 }`, `{ $len: 3 }`, `{ $not: … }`, `{ $oneOf: [...] }` and
+ * `{ $format: uuid }` become Vitest asymmetric matchers. Several `$` keys must all hold.
  */
 export declare function toMatchers(value: unknown): unknown;
 export {};