slicetest 0.7.0 → 0.8.0

package/dist/stub.js

@@ -259,7 +259,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 +270,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,
         };
@@ -371,9 +374,18 @@ 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))
@@ -388,6 +400,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)
@@ -422,6 +436,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)
@@ -534,6 +555,88 @@ 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";
+}
+/**
+ * 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);
+        if (!m || !m[2]) {
+            const prev = out[key];
+            out[key] = prev === undefined ? value : Array.isArray(prev) ? [...prev, value] : [prev, value];
+            continue;
+        }
+        const path = [m[1], ...[...m[2].matchAll(/\[([^\]]*)\]/g)].map((x) => x[1])];
+        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 {};