@wirebench/engine 2.2.0 → 3.1.0-rc.1

package/dist/rest/events.d.ts

@@ -0,0 +1,12 @@
+/** What a REST send reports while it runs (spec §3.2): the response opening, then each event-stream row. */
+import type { SseRow } from './sse.js';
+export type RestLiveEvent = {
+    readonly protocol: 'rest';
+    readonly kind: 'open';
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+} | {
+    readonly protocol: 'rest';
+    readonly kind: 'row';
+    readonly row: SseRow;
+};

package/dist/rest/events.js

@@ -0,0 +1 @@
+export {};

package/dist/rest/expand.d.ts

@@ -2,7 +2,7 @@
  * Property expansion for a REST send: every `${…}` reference in the base URL, the URL, the tables
  * and the body, resolved against the same scopes a SOAP send uses.
  *
- * Separate from `project/properties.ts`'s `expandSendInput` because the two inputs share no fields,
+ * Separate from `soap/expand.ts`'s `expandSendInput` because the two inputs share no fields,
  * but the rules are deliberately the same ones: names as well as values are expanded, an
  * unresolved reference is reported rather than guessed at, and escaping is applied to the body
  * alone — escaping a header value or a URL would corrupt it.
@@ -16,6 +16,11 @@ export interface ExpandRestOptions {
      * entities — which is the request's *escape properties* setting. Off by default.
      */
     readonly escape?: boolean;
+    /**
+     * Leave the request URL exactly as given: it came from a recorded exchange (a callback URL), and
+     * values from an exchange are never expanded again (ADR-0015). Everything else still expands.
+     */
+    readonly literalUrl?: boolean;
 }
 /**
  * Expands every property reference in a REST send input.

package/dist/rest/expand.js

@@ -2,13 +2,15 @@
  * Property expansion for a REST send: every `${…}` reference in the base URL, the URL, the tables
  * and the body, resolved against the same scopes a SOAP send uses.
  *
- * Separate from `project/properties.ts`'s `expandSendInput` because the two inputs share no fields,
+ * Separate from `soap/expand.ts`'s `expandSendInput` because the two inputs share no fields,
  * but the rules are deliberately the same ones: names as well as values are expanded, an
  * unresolved reference is reported rather than guessed at, and escaping is applied to the body
  * alone — escaping a header value or a URL would corrupt it.
  */
 import { expand } from '../project/properties.js';
+import { assertNoControlCharacters, assertOriginIndependent, expandWithSequenceEscaped, } from '../project/sequence-guards.js';
 import { escapeForLanguage } from './body.js';
+import { composeUrl } from './url.js';
 /**
  * Expands every property reference in a REST send input.
  *
@@ -23,34 +25,50 @@ import { escapeForLanguage } from './body.js';
  */
 export function expandRestSendInput(input, scopes, options = {}) {
     const unresolved = [];
-    const run = (text) => {
+    /** Expands `text`; `place`, when given, names a line-oriented field a Sequence value must not break. */
+    const run = (text, place) => {
         const result = expand(text, scopes);
         unresolved.push(...result.unresolved);
+        if (place !== undefined) {
+            assertNoControlCharacters(place, result, scopes);
+        }
         return result.text;
     };
-    /** A body value: expanded, then escaped for the body's language when the request asks for it. */
+    /**
+     * A body value: expanded, then escaped for the body's language when the request asks for it. A
+     * Sequence value is escaped whether or not the request asks, because it came from a response and
+     * could otherwise add fields or elements to the body (ADR-0015).
+     */
     const runBody = (text, language) => {
         const result = expand(text, scopes);
         unresolved.push(...result.unresolved);
-        if (options.escape !== true || language === undefined) {
+        if (language === undefined) {
             return result.text;
         }
         // Escaping has to happen per substituted value, not over the finished text, or the body's own
         // punctuation would be escaped too. `expand` reports which references it replaced, so the
         // cheapest correct thing is to re-expand with an escaping substitution.
-        return expand(text, escapedScopes(scopes, language)).text;
+        return expandWithSequenceEscaped((s) => (options.escape === true ? expand(text, escapedScopes(s, language)) : expand(text, s)).text, scopes, (value) => escapeForLanguage(value, language));
     };
-    const rows = (entries) => entries.map((entry) => ({ ...entry, name: run(entry.name), value: run(entry.value) }));
+    const rows = (entries, place) => entries.map((entry) => ({
+        ...entry,
+        name: run(entry.name, `A ${place} name`),
+        value: run(entry.value, `The ${place} ${entry.name}`),
+    }));
+    const url = (s) => options.literalUrl === true ? input.request.url : expand(input.request.url, s).text;
+    // Where the request goes is decided by the base URL, the URL and any path parameter placed in its
+    // host, so the guard composes the URL the way `sendRest` will.
+    assertOriginIndependent('The request URL', (s) => composeUrl(expand(input.baseUrl, s).text, url(s), input.request.pathParams.map((row) => ({ ...row, value: expand(row.value, s).text })), [], { encode: input.settings.encodeUrl ?? true }).url, scopes);
     const request = {
         method: input.request.method,
-        url: run(input.request.url),
-        pathParams: rows(input.request.pathParams),
-        query: rows(input.request.query),
-        headers: rows(input.request.headers),
+        url: options.literalUrl === true ? input.request.url : run(input.request.url, 'The request URL'),
+        pathParams: rows(input.request.pathParams, 'path parameter'),
+        query: rows(input.request.query, 'query parameter'),
+        headers: rows(input.request.headers, 'header'),
         body: expandBody(input.request.body, run, runBody),
     };
     return {
-        input: { ...input, baseUrl: run(input.baseUrl), request },
+        input: { ...input, baseUrl: run(input.baseUrl, 'The base URL'), request },
         unresolved,
     };
 }

package/dist/rest/files.d.ts

@@ -0,0 +1,439 @@
+/**
+ * The REST files of a project folder: `apis/<slug>/api.yaml` with `kind: rest`, and each
+ * `*.request.yaml` of its request tree (spec §3.2). The same request schema reads the items of the
+ * project's webhook collection, which is REST requests in a tree of its own.
+ */
+import { z } from 'zod';
+/**
+ * A request body as persisted. A raw body names its sibling file rather than carrying its text:
+ * `file` is a bare file name in the request's own directory, validated as a path segment before
+ * anything is read or written (ADR-0005).
+ */
+export declare const restBodySchema: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"none">;
+}, z.core.$loose>, z.ZodObject<{
+    kind: z.ZodLiteral<"raw">;
+    language: z.ZodEnum<{
+        xml: "xml";
+        json: "json";
+        text: "text";
+        html: "html";
+        javascript: "javascript";
+    }>;
+    contentType: z.ZodOptional<z.ZodString>;
+    file: z.ZodString;
+}, z.core.$loose>, z.ZodObject<{
+    kind: z.ZodLiteral<"form">;
+    fields: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodString;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>, z.ZodObject<{
+    kind: z.ZodLiteral<"multipart">;
+    parts: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"text">;
+        name: z.ZodString;
+        value: z.ZodString;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        contentType: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        kind: z.ZodLiteral<"file">;
+        name: z.ZodString;
+        source: z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"cache">;
+            sha256: z.ZodString;
+        }, z.core.$loose>, z.ZodObject<{
+            kind: z.ZodLiteral<"path">;
+            path: z.ZodString;
+        }, z.core.$loose>]>;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        fileName: z.ZodOptional<z.ZodString>;
+        contentType: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>]>>>;
+}, z.core.$loose>, z.ZodObject<{
+    kind: z.ZodLiteral<"binary">;
+    source: z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"cache">;
+        sha256: z.ZodString;
+    }, z.core.$loose>, z.ZodObject<{
+        kind: z.ZodLiteral<"path">;
+        path: z.ZodString;
+    }, z.core.$loose>]>;
+    contentType: z.ZodString;
+}, z.core.$loose>]>;
+/** `apis/<slug>/requests/[<folder>/…]<name>.request.yaml`. */
+export declare const restRequestFileSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"rest">;
+    id: z.ZodString;
+    name: z.ZodString;
+    order: z.ZodNumber;
+    description: z.ZodOptional<z.ZodString>;
+    method: z.ZodString;
+    url: z.ZodString;
+    pathParams: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodString;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    query: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodString;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    headers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodString;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    body: z.ZodDefault<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"none">;
+    }, z.core.$loose>, z.ZodObject<{
+        kind: z.ZodLiteral<"raw">;
+        language: z.ZodEnum<{
+            xml: "xml";
+            json: "json";
+            text: "text";
+            html: "html";
+            javascript: "javascript";
+        }>;
+        contentType: z.ZodOptional<z.ZodString>;
+        file: z.ZodString;
+    }, z.core.$loose>, z.ZodObject<{
+        kind: z.ZodLiteral<"form">;
+        fields: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            value: z.ZodString;
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>, z.ZodObject<{
+        kind: z.ZodLiteral<"multipart">;
+        parts: z.ZodDefault<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"text">;
+            name: z.ZodString;
+            value: z.ZodString;
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            contentType: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>, z.ZodObject<{
+            kind: z.ZodLiteral<"file">;
+            name: z.ZodString;
+            source: z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"cache">;
+                sha256: z.ZodString;
+            }, z.core.$loose>, z.ZodObject<{
+                kind: z.ZodLiteral<"path">;
+                path: z.ZodString;
+            }, z.core.$loose>]>;
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            fileName: z.ZodOptional<z.ZodString>;
+            contentType: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>]>>>;
+    }, z.core.$loose>, z.ZodObject<{
+        kind: z.ZodLiteral<"binary">;
+        source: z.ZodUnion<readonly [z.ZodObject<{
+            kind: z.ZodLiteral<"cache">;
+            sha256: z.ZodString;
+        }, z.core.$loose>, z.ZodObject<{
+            kind: z.ZodLiteral<"path">;
+            path: z.ZodString;
+        }, z.core.$loose>]>;
+        contentType: z.ZodString;
+    }, z.core.$loose>]>>;
+    auth: z.ZodDefault<z.ZodUnion<readonly [z.ZodObject<{
+        type: z.ZodEnum<{
+            none: "none";
+            basic: "basic";
+            ntlm: "ntlm";
+        }>;
+        username: z.ZodOptional<z.ZodString>;
+        passwordRef: z.ZodOptional<z.ZodString>;
+        passwordEnv: z.ZodOptional<z.ZodString>;
+        domain: z.ZodOptional<z.ZodString>;
+        workstation: z.ZodOptional<z.ZodString>;
+        preemptive: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"inherit">;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"bearer">;
+        tokenRef: z.ZodOptional<z.ZodString>;
+        tokenEnv: z.ZodOptional<z.ZodString>;
+        scheme: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"api-key">;
+        name: z.ZodString;
+        valueRef: z.ZodOptional<z.ZodString>;
+        valueEnv: z.ZodOptional<z.ZodString>;
+        in: z.ZodEnum<{
+            header: "header";
+            query: "query";
+        }>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"oauth2">;
+        grant: z.ZodEnum<{
+            "client-credentials": "client-credentials";
+            "authorization-code": "authorization-code";
+        }>;
+        tokenUrl: z.ZodString;
+        authorizationUrl: z.ZodOptional<z.ZodString>;
+        clientId: z.ZodString;
+        clientSecretRef: z.ZodOptional<z.ZodString>;
+        clientSecretEnv: z.ZodOptional<z.ZodString>;
+        scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        audience: z.ZodOptional<z.ZodString>;
+        clientAuth: z.ZodDefault<z.ZodEnum<{
+            basic: "basic";
+            body: "body";
+        }>>;
+        pkce: z.ZodDefault<z.ZodBoolean>;
+        refreshTokenRef: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>]>>;
+    settings: z.ZodDefault<z.ZodObject<{
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+        followRedirects: z.ZodOptional<z.ZodBoolean>;
+        maxRedirects: z.ZodOptional<z.ZodNumber>;
+        keepBodyOnRedirect: z.ZodOptional<z.ZodBoolean>;
+        encodeUrl: z.ZodOptional<z.ZodBoolean>;
+        trustInvalid: z.ZodOptional<z.ZodBoolean>;
+        sslKeystoreRef: z.ZodOptional<z.ZodString>;
+        bindAddress: z.ZodOptional<z.ZodString>;
+        maxSizeBytes: z.ZodOptional<z.ZodNumber>;
+        sendCookies: z.ZodOptional<z.ZodBoolean>;
+        escapeProperties: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>;
+    assertions: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"status">;
+        equals: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodNumber, z.ZodNumber, z.ZodString, z.ZodEnum<{
+            [x: string]: string;
+        }>]>, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodNumber, z.ZodString, z.ZodEnum<{
+            [x: string]: string;
+        }>]>>]>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"soap-fault">;
+        expect: z.ZodDefault<z.ZodEnum<{
+            none: "none";
+            present: "present";
+        }>>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"match">;
+        language: z.ZodEnum<{
+            xpath: "xpath";
+            xquery: "xquery";
+            jsonpath: "jsonpath";
+        }>;
+        expression: z.ZodString;
+        namespaces: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        equals: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        matches: z.ZodOptional<z.ZodString>;
+        exists: z.ZodOptional<z.ZodBoolean>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"schema">;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"sla">;
+        maxMs: z.ZodNumber;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"callback">;
+        catchUrl: z.ZodString;
+        withinMs: z.ZodDefault<z.ZodNumber>;
+        match: z.ZodDefault<z.ZodObject<{
+            method: z.ZodOptional<z.ZodString>;
+            path: z.ZodOptional<z.ZodString>;
+            pathMatches: z.ZodOptional<z.ZodString>;
+            headers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                equals: z.ZodOptional<z.ZodString>;
+                matches: z.ZodOptional<z.ZodString>;
+                exists: z.ZodOptional<z.ZodBoolean>;
+                name: z.ZodString;
+            }, z.core.$loose>>>;
+            body: z.ZodOptional<z.ZodObject<{
+                equals: z.ZodOptional<z.ZodString>;
+                matches: z.ZodOptional<z.ZodString>;
+                exists: z.ZodOptional<z.ZodBoolean>;
+                language: z.ZodEnum<{
+                    xpath: "xpath";
+                    jsonpath: "jsonpath";
+                }>;
+                path: z.ZodString;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
+        expect: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            body: z.ZodOptional<z.ZodObject<{
+                equals: z.ZodOptional<z.ZodString>;
+                matches: z.ZodOptional<z.ZodString>;
+                exists: z.ZodOptional<z.ZodBoolean>;
+                language: z.ZodEnum<{
+                    xpath: "xpath";
+                    jsonpath: "jsonpath";
+                }>;
+                path: z.ZodString;
+            }, z.core.$loose>>;
+            header: z.ZodOptional<z.ZodObject<{
+                equals: z.ZodOptional<z.ZodString>;
+                matches: z.ZodOptional<z.ZodString>;
+                exists: z.ZodOptional<z.ZodBoolean>;
+                name: z.ZodString;
+            }, z.core.$loose>>;
+            signature: z.ZodOptional<z.ZodLiteral<"verified">>;
+        }, z.core.$loose>>>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>], "type">>>;
+    orphaned: z.ZodOptional<z.ZodBoolean>;
+    contract: z.ZodOptional<z.ZodObject<{
+        method: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$loose>>;
+    hook: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"webhook">;
+        name: z.ZodString;
+    }, z.core.$loose>, z.ZodObject<{
+        kind: z.ZodLiteral<"callback">;
+        operation: z.ZodString;
+        name: z.ZodString;
+        expression: z.ZodString;
+    }, z.core.$loose>], "kind">>;
+    signing: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        mode: z.ZodLiteral<"none">;
+    }, z.core.$loose>, z.ZodObject<{
+        mode: z.ZodLiteral<"sign">;
+        scheme: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"hmac">;
+            algorithm: z.ZodEnum<{
+                sha256: "sha256";
+                sha1: "sha1";
+                sha512: "sha512";
+            }>;
+            encoding: z.ZodEnum<{
+                base64: "base64";
+                hex: "hex";
+            }>;
+            header: z.ZodString;
+            prefix: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"timestamped">;
+            header: z.ZodString;
+            toleranceSec: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"standard">;
+            toleranceSec: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>], "kind">;
+        secretRef: z.ZodOptional<z.ZodString>;
+        secretEnv: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>]>>;
+    scripts: z.ZodOptional<z.ZodObject<{
+        pre: z.ZodOptional<z.ZodString>;
+        post: z.ZodOptional<z.ZodString>;
+        api: z.ZodDefault<z.ZodEnum<{
+            wirebench: "wirebench";
+            postman: "postman";
+        }>>;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        secrets: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/** `apis/<slug>/api.yaml`. */
+export declare const apiFileSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"rest">;
+    id: z.ZodString;
+    name: z.ZodString;
+    order: z.ZodNumber;
+    description: z.ZodOptional<z.ZodString>;
+    baseUrl: z.ZodString;
+    servers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    auth: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        type: z.ZodEnum<{
+            none: "none";
+            basic: "basic";
+            ntlm: "ntlm";
+        }>;
+        username: z.ZodOptional<z.ZodString>;
+        passwordRef: z.ZodOptional<z.ZodString>;
+        passwordEnv: z.ZodOptional<z.ZodString>;
+        domain: z.ZodOptional<z.ZodString>;
+        workstation: z.ZodOptional<z.ZodString>;
+        preemptive: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"inherit">;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"bearer">;
+        tokenRef: z.ZodOptional<z.ZodString>;
+        tokenEnv: z.ZodOptional<z.ZodString>;
+        scheme: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"api-key">;
+        name: z.ZodString;
+        valueRef: z.ZodOptional<z.ZodString>;
+        valueEnv: z.ZodOptional<z.ZodString>;
+        in: z.ZodEnum<{
+            header: "header";
+            query: "query";
+        }>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"oauth2">;
+        grant: z.ZodEnum<{
+            "client-credentials": "client-credentials";
+            "authorization-code": "authorization-code";
+        }>;
+        tokenUrl: z.ZodString;
+        authorizationUrl: z.ZodOptional<z.ZodString>;
+        clientId: z.ZodString;
+        clientSecretRef: z.ZodOptional<z.ZodString>;
+        clientSecretEnv: z.ZodOptional<z.ZodString>;
+        scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        audience: z.ZodOptional<z.ZodString>;
+        clientAuth: z.ZodDefault<z.ZodEnum<{
+            basic: "basic";
+            body: "body";
+        }>>;
+        pkce: z.ZodDefault<z.ZodBoolean>;
+        refreshTokenRef: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>]>>;
+    definition: z.ZodOptional<z.ZodObject<{
+        source: z.ZodString;
+        cache: z.ZodDefault<z.ZodBoolean>;
+        version: z.ZodDefault<z.ZodString>;
+        auth: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            type: z.ZodEnum<{
+                none: "none";
+                basic: "basic";
+                ntlm: "ntlm";
+            }>;
+            username: z.ZodOptional<z.ZodString>;
+            passwordRef: z.ZodOptional<z.ZodString>;
+            passwordEnv: z.ZodOptional<z.ZodString>;
+            domain: z.ZodOptional<z.ZodString>;
+            workstation: z.ZodOptional<z.ZodString>;
+            preemptive: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>, z.ZodObject<{
+            type: z.ZodLiteral<"bearer">;
+            tokenRef: z.ZodOptional<z.ZodString>;
+            tokenEnv: z.ZodOptional<z.ZodString>;
+            scheme: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>, z.ZodObject<{
+            type: z.ZodLiteral<"api-key">;
+            name: z.ZodString;
+            valueRef: z.ZodOptional<z.ZodString>;
+            valueEnv: z.ZodOptional<z.ZodString>;
+            in: z.ZodEnum<{
+                header: "header";
+                query: "query";
+            }>;
+        }, z.core.$loose>]>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/** An API document as persisted. */
+export type ApiFile = z.infer<typeof apiFileSchema>;
+/** A REST request document as persisted (a raw body's text excluded). */
+export type RestRequestFile = z.infer<typeof restRequestFileSchema>;

package/dist/rest/files.js

@@ -0,0 +1,107 @@
+/**
+ * The REST files of a project folder: `apis/<slug>/api.yaml` with `kind: rest`, and each
+ * `*.request.yaml` of its request tree (spec §3.2). The same request schema reads the items of the
+ * project's webhook collection, which is REST requests in a tree of its own.
+ */
+import { z } from 'zod';
+import { assertionsSchema } from '../assert/schema.js';
+import { attachmentSourceSchema, authConfigSchema, definitionAuthSchema, hookLinkSchema, keyValueEntrySchema, nonEmpty, scriptsSchema, webhookSigningSchema, } from '../project/schema-parts.js';
+/**
+ * An HTTP method: any RFC 9110 token, not just the seven the editor names. A service that speaks
+ * `PURGE` or `REPORT` is not a malformed project.
+ */
+const methodSchema = z
+    .string()
+    .min(1)
+    .regex(/^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/, 'a method must be an HTTP token');
+const multipartPartSchema = z.union([
+    z.looseObject({
+        kind: z.literal('text'),
+        name: z.string(),
+        value: z.string(),
+        enabled: z.boolean().default(true),
+        contentType: z.string().optional(),
+    }),
+    z.looseObject({
+        kind: z.literal('file'),
+        name: z.string(),
+        source: attachmentSourceSchema,
+        enabled: z.boolean().default(true),
+        fileName: z.string().optional(),
+        contentType: z.string().optional(),
+    }),
+]);
+/**
+ * A request body as persisted. A raw body names its sibling file rather than carrying its text:
+ * `file` is a bare file name in the request's own directory, validated as a path segment before
+ * anything is read or written (ADR-0005).
+ */
+export const restBodySchema = z.union([
+    z.looseObject({ kind: z.literal('none') }),
+    z.looseObject({
+        kind: z.literal('raw'),
+        language: z.enum(['json', 'xml', 'text', 'html', 'javascript']),
+        contentType: z.string().optional(),
+        file: nonEmpty,
+    }),
+    z.looseObject({ kind: z.literal('form'), fields: z.array(keyValueEntrySchema).default([]) }),
+    z.looseObject({ kind: z.literal('multipart'), parts: z.array(multipartPartSchema).default([]) }),
+    z.looseObject({ kind: z.literal('binary'), source: attachmentSourceSchema, contentType: z.string() }),
+]);
+const restSettingsSchema = z.looseObject({
+    timeoutMs: z.number().int().nonnegative().optional(),
+    followRedirects: z.boolean().optional(),
+    maxRedirects: z.number().int().nonnegative().optional(),
+    keepBodyOnRedirect: z.boolean().optional(),
+    encodeUrl: z.boolean().optional(),
+    trustInvalid: z.boolean().optional(),
+    sslKeystoreRef: z.string().optional(),
+    bindAddress: z.string().optional(),
+    maxSizeBytes: z.number().int().nonnegative().optional(),
+    sendCookies: z.boolean().optional(),
+    escapeProperties: z.boolean().optional(),
+});
+/** `apis/<slug>/requests/[<folder>/…]<name>.request.yaml`. */
+export const restRequestFileSchema = z.looseObject({
+    kind: z.literal('rest'),
+    id: nonEmpty,
+    name: z.string(),
+    order: z.number().int(),
+    description: z.string().optional(),
+    method: methodSchema,
+    url: z.string(),
+    pathParams: z.array(keyValueEntrySchema).default([]),
+    query: z.array(keyValueEntrySchema).default([]),
+    headers: z.array(keyValueEntrySchema).default([]),
+    body: restBodySchema.default({ kind: 'none' }),
+    auth: authConfigSchema.default({ type: 'inherit' }),
+    settings: restSettingsSchema.default({}),
+    assertions: assertionsSchema.default([]),
+    orphaned: z.boolean().optional(),
+    /** The operation of the API's definition this request calls. */
+    contract: z.looseObject({ method: nonEmpty, path: nonEmpty }).optional(),
+    /** Only under `webhooks/`: the imported `webhooks`/`callbacks` entry; refused elsewhere by the loader. */
+    hook: hookLinkSchema.optional(),
+    /** Only under `webhooks/`; refused elsewhere by the loader. */
+    signing: webhookSigningSchema.optional(),
+    scripts: scriptsSchema.optional(),
+});
+/** `apis/<slug>/api.yaml`. */
+export const apiFileSchema = z.looseObject({
+    kind: z.literal('rest'),
+    id: nonEmpty,
+    name: z.string(),
+    order: z.number().int(),
+    description: z.string().optional(),
+    baseUrl: z.string(),
+    servers: z.array(z.looseObject({ url: z.string(), description: z.string().optional() })).default([]),
+    auth: authConfigSchema.optional(),
+    definition: z
+        .looseObject({
+        source: nonEmpty,
+        cache: z.boolean().default(true),
+        version: z.string().default(''),
+        auth: definitionAuthSchema.optional(),
+    })
+        .optional(),
+});