@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/rest/response.d.ts

@@ -47,26 +47,5 @@ export interface PrettyBody {
  * broken body *is* the interesting thing when an API misbehaves, and hiding it would hide the bug.
  */
 export declare function prettyBody(text: string, language: BodyLanguage, indent?: number): PrettyBody;
-/** One cookie a response set, with the attributes it declared. */
-export interface Cookie {
-    readonly name: string;
-    readonly value: string;
-    readonly domain?: string;
-    readonly path?: string;
-    /** As declared, in ISO form when it could be parsed; absent for a session cookie. */
-    readonly expires?: string;
-    readonly maxAge?: number;
-    readonly secure?: boolean;
-    readonly httpOnly?: boolean;
-    readonly sameSite?: 'Strict' | 'Lax' | 'None';
-    /** Set when the header could not be parsed as a cookie; `name` then holds the whole line. */
-    readonly malformed?: boolean;
-}
-/**
- * Parses every `Set-Cookie` header of a response (RFC 6265 §5.2).
- *
- * `rawHeaders` rather than the merged map, because several cookies arrive as several headers and
- * joining them with `, ` — which is what merging does — makes them unparseable. A line that is not
- * a cookie at all is kept as `malformed` instead of dropped: it is evidence about the server.
- */
-export declare function parseSetCookie(rawHeaders: readonly (readonly [string, string])[]): Cookie[];
+export { parseSetCookie } from '../http/cookies.js';
+export type { Cookie } from '../http/cookies.js';

package/dist/rest/response.js

@@ -7,8 +7,8 @@
  * promised, a `Set-Cookie` with an attribute in the wrong order — and none of that may throw,
  * because the user still has to be able to look at it.
  */
-import { decodeBody } from '../soap/charset.js';
-import { mediaTypeOf } from '../soap/mime/multipart.js';
+import { decodeBody } from '../http/charset.js';
+import { mediaTypeOf } from '../http/media-type.js';
 import { formatXml } from '../xml/pretty.js';
 /**
  * The language of a response body.
@@ -146,76 +146,4 @@ function formatHtml(text, indent) {
     }
     return lines.join('\n');
 }
-/**
- * Parses every `Set-Cookie` header of a response (RFC 6265 §5.2).
- *
- * `rawHeaders` rather than the merged map, because several cookies arrive as several headers and
- * joining them with `, ` — which is what merging does — makes them unparseable. A line that is not
- * a cookie at all is kept as `malformed` instead of dropped: it is evidence about the server.
- */
-export function parseSetCookie(rawHeaders) {
-    const cookies = [];
-    for (const [name, value] of rawHeaders) {
-        if (name.toLowerCase() !== 'set-cookie') {
-            continue;
-        }
-        cookies.push(parseOne(value));
-    }
-    return cookies;
-}
-function parseOne(header) {
-    const parts = header.split(';');
-    const pair = parts[0] ?? '';
-    const equals = pair.indexOf('=');
-    if (equals <= 0) {
-        return { name: header.trim(), value: '', malformed: true };
-    }
-    const cookie = {
-        name: pair.slice(0, equals).trim(),
-        value: unquote(pair.slice(equals + 1).trim()),
-    };
-    for (const attribute of parts.slice(1)) {
-        const split = attribute.indexOf('=');
-        const key = (split === -1 ? attribute : attribute.slice(0, split)).trim().toLowerCase();
-        const attributeValue = split === -1 ? '' : attribute.slice(split + 1).trim();
-        switch (key) {
-            case 'domain':
-                // A leading dot is legal and means the same as its absence (RFC 6265 §5.2.3).
-                cookie.domain = attributeValue.replace(/^\./, '').toLowerCase();
-                break;
-            case 'path':
-                cookie.path = attributeValue;
-                break;
-            case 'expires': {
-                const date = new Date(attributeValue);
-                cookie.expires = Number.isNaN(date.getTime()) ? attributeValue : date.toISOString();
-                break;
-            }
-            case 'max-age': {
-                const seconds = Number.parseInt(attributeValue, 10);
-                if (!Number.isNaN(seconds)) {
-                    cookie.maxAge = seconds;
-                }
-                break;
-            }
-            case 'secure':
-                cookie.secure = true;
-                break;
-            case 'httponly':
-                cookie.httpOnly = true;
-                break;
-            case 'samesite': {
-                const normalized = attributeValue.toLowerCase();
-                cookie.sameSite = normalized === 'strict' ? 'Strict' : normalized === 'none' ? 'None' : 'Lax';
-                break;
-            }
-            default:
-                break;
-        }
-    }
-    return cookie;
-}
-/** Strips one layer of double quotes from a cookie value, which some servers add. */
-function unquote(value) {
-    return value.length > 1 && value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
-}
+export { parseSetCookie } from '../http/cookies.js';

package/dist/rest/run.d.ts

@@ -0,0 +1,56 @@
+import type { AssertionSubject } from '../assert/model.js';
+import type { AuthConfig, Project } from '../project/model.js';
+import type { ProtocolRun } from '../protocol/module.js';
+import type { RunContext } from '../run/context.js';
+import type { Resolved } from '../run/send-helpers.js';
+import type { EffectiveSigning } from '../webhooks/model.js';
+import type { RestApi, RestFolder, RestRequestDef } from './model.js';
+import type { RestExchange, RestSendInput } from './send.js';
+/** One saved REST request, or one webhook item, selected for a run. */
+export interface RestSelected {
+    readonly kind: 'rest';
+    readonly path: string;
+    readonly group: string;
+    readonly api: RestApi;
+    readonly chain: readonly RestFolder[];
+    readonly request: RestRequestDef;
+    /** A webhook item's effective signing (webhook-signatures §5.2); absent for an API request. */
+    readonly signing?: EffectiveSigning;
+}
+/** Innermost first, as the app's `authChainFor` builds it: request, its folders inside-out, the API. */
+export declare function restEffectiveAuth(selected: RestSelected): AuthConfig;
+/**
+ * One REST request resolved (spec §3.4): its properties and secret tokens expanded (the secrets
+ * behind `context.secretPlaceholders` when given), nothing connected and the credentials still as
+ * configured, so the input holds no `auth`. A reference nothing resolves is reported in
+ * `unresolved`, not thrown: the send refuses it, a preview shows it.
+ *
+ * A webhook item goes to its callback URL when the host names one: that URL is the whole
+ * destination, taken literally (ADR-0015), with no base. Otherwise it goes to its target, which
+ * must expand to an `http(s)` URL.
+ *
+ * @throws WirebenchError `secret-missing` | `rest-file-outside-project` | `webhook-target-missing` |
+ * `webhook-target-invalid`
+ */
+export declare function resolveRest(selected: RestSelected, context: RunContext): Promise<Resolved<RestSendInput>>;
+/**
+ * TLS, signing, credentials (an OAuth2 token included) and the proxy, over a resolved input: what
+ * a send does after its pre-request script, so the script never sees a credential (spec §7).
+ *
+ * @throws WirebenchError `secret-missing` | `auth-grant-unsupported` | `keystore-missing` |
+ * `webhook-signing-secret`
+ */
+export declare function connectRest(selected: RestSelected, context: RunContext, input: RestSendInput): Promise<RestSendInput>;
+/**
+ * A REST response as assertions and sequence transfers see it. A buffered event stream is the data
+ * of its events, in order, as a JSON array (spec §5.2).
+ */
+export declare function restSubject(exchange: RestExchange): AssertionSubject;
+/**
+ * The REST item for `requestId`, an API request or a webhook item, built as a run builds it — and
+ * found even when its contract no longer has it (`orphaned`), which a run skips and a person may
+ * still send. Undefined when no REST request has that id.
+ */
+export declare function restItemFor(project: Project, requestId: string): RestSelected | undefined;
+/** REST's run facet. */
+export declare const restRun: ProtocolRun<RestSelected>;

package/dist/rest/run.js

@@ -0,0 +1,395 @@
+/**
+ * REST's run facet (spec §3.3): the requests of every API, and the project's webhook items as a
+ * group a run sends only when a selector names it. A send resolves the request (its properties and
+ * secret tokens), runs its pre-request script, connects (its TLS identity, a webhook item's signing
+ * secret, its credentials with an OAuth2 token, the proxy), then goes on the wire (spec §3.4). A
+ * send that is not live reads an event stream to its end or the timeout (spec §5.2).
+ */
+import { readFile } from 'node:fs/promises';
+import { readAttachment } from '../project/attachments-cache.js';
+import { REQUESTS_DIR, WEBHOOKS_DIR } from '../project/paths.js';
+import { scopesFor } from '../run/context.js';
+import { exchangeController } from '../run/exchange.js';
+import { authFor, baseUrlFor, dropRefusedToken, insideProject, keystoreNeeds, originOf, tlsFor, unresolvedError, withSecrets, } from '../run/send-helpers.js';
+import { ORPHANED_STEP_REASON, byOrder, findInTree, walkTree } from '../run/tree.js';
+import { applyRestSnapshot, restRequestSnapshot, restResponseSnapshot } from './scripting.js';
+import { createSseParser, isEventStream } from './sse.js';
+import { loadOpenApiDocument, restOperationFor, restScriptTypes } from './script-types.js';
+import { secretNeedsOfAuth } from '../secrets/env-names.js';
+import { toRestSendInput } from './send-input.js';
+import { assertWebhookTarget, effectiveSigning, effectiveTarget, signingSecretMissing, signingSecretRef, signingSourceLabel, } from '../webhooks/model.js';
+import { resolveAuthChain } from '../http/auth/apply-auth.js';
+import { expandRestSendInput } from './expand.js';
+import { createApi } from './model.js';
+import { sendRest } from './send.js';
+import { joinBase } from './url.js';
+/** Innermost first, as the app's `authChainFor` builds it: request, its folders inside-out, the API. */
+export function restEffectiveAuth(selected) {
+    const { api, chain, request } = selected;
+    return resolveAuthChain([request.auth, ...[...chain].reverse().map((folder) => folder.auth), api.auth]);
+}
+/** A REST multipart file part or binary body, read from inside the project folder. */
+function restFileResolver(context) {
+    return async (source) => source.kind === 'cache'
+        ? readAttachment(context.projectDir, source.sha256)
+        : new Uint8Array(await readFile(await insideProject(context, source.path, 'rest-file-outside-project', source.path)));
+}
+/**
+ * A webhook item's signing with its secret, or `undefined` when it signs nothing. The secret is
+ * read through the run's `GetSecret` (the CLI: `WIREBENCH_SECRET_<secretEnv>`), so it is masked
+ * like every other secret the run hands out.
+ *
+ * @throws WirebenchError `webhook-signing-secret` when signing is set and the secret is not given
+ */
+async function signFor(selected, context) {
+    const effective = selected.signing;
+    if (effective === undefined || effective.signing.mode !== 'sign')
+        return undefined;
+    const ref = signingSecretRef(effective.signing);
+    const secret = ref === undefined ? undefined : await context.host.getSecret(ref);
+    if (secret === undefined || secret === '')
+        throw signingSecretMissing(effective, ref);
+    return { scheme: effective.signing.scheme, secret };
+}
+/**
+ * One REST request resolved (spec §3.4): its properties and secret tokens expanded (the secrets
+ * behind `context.secretPlaceholders` when given), nothing connected and the credentials still as
+ * configured, so the input holds no `auth`. A reference nothing resolves is reported in
+ * `unresolved`, not thrown: the send refuses it, a preview shows it.
+ *
+ * A webhook item goes to its callback URL when the host names one: that URL is the whole
+ * destination, taken literally (ADR-0015), with no base. Otherwise it goes to its target, which
+ * must expand to an `http(s)` URL.
+ *
+ * @throws WirebenchError `secret-missing` | `rest-file-outside-project` | `webhook-target-missing` |
+ * `webhook-target-invalid`
+ */
+export async function resolveRest(selected, context) {
+    const { api, request } = selected;
+    const scopes = scopesFor(context);
+    const callbackUrl = isWebhookItem(selected) ? await context.host.callbackUrlFor?.(selected) : undefined;
+    const unexpanded = toRestSendInput({
+        request: {
+            method: request.method,
+            url: callbackUrl ?? request.url,
+            pathParams: request.pathParams,
+            query: request.query,
+            headers: request.headers,
+            body: request.body,
+            settings: request.settings,
+        },
+        baseUrl: callbackUrl !== undefined ? '' : baseUrlFor(context, api),
+        projectSettings: context.project.settings,
+        ...(context.host.preferences !== undefined ? { preferences: context.host.preferences } : {}),
+        resolveFile: restFileResolver(context),
+        ...(context.signal !== undefined ? { signal: context.signal } : {}),
+    });
+    const withTokens = await withSecrets(unexpanded, scopes, context.host.getSecret, context.secretPlaceholders);
+    const { input, unresolved } = expandRestSendInput(unexpanded, withTokens, {
+        escape: request.settings.escapeProperties === true,
+        ...(callbackUrl !== undefined ? { literalUrl: true } : {}),
+    });
+    // A target holding a secret still behind its placeholder is checked by nothing: its value is not in.
+    if (isWebhookItem(selected) &&
+        callbackUrl === undefined &&
+        context.secretPlaceholders?.holds(input.baseUrl) !== true) {
+        assertWebhookTarget(input.baseUrl, input.request.url, unresolved.length > 0);
+    }
+    return {
+        input: {
+            ...input,
+            ...(context.timeoutMs !== undefined ? { settings: { ...input.settings, timeoutMs: context.timeoutMs } } : {}),
+        },
+        unresolved,
+    };
+}
+/**
+ * TLS, signing, credentials (an OAuth2 token included) and the proxy, over a resolved input: what
+ * a send does after its pre-request script, so the script never sees a credential (spec §7).
+ *
+ * @throws WirebenchError `secret-missing` | `auth-grant-unsupported` | `keystore-missing` |
+ * `webhook-signing-secret`
+ */
+export async function connectRest(selected, context, input) {
+    const { request } = selected;
+    const tls = await tlsFor(context, request.settings.sslKeystoreRef, request.settings.trustInvalid === true);
+    // As the app does: a webhook item's signing secret is read before any OAuth2 token is fetched.
+    const sign = await signFor(selected, context);
+    const auth = await authFor(restEffectiveAuth(selected), selected.path, context, tls);
+    // As the app does: the proxy is chosen for the base URL, or the request's own URL when there is none.
+    const proxy = await context.host.proxyFor?.(input.baseUrl === '' ? input.request.url : input.baseUrl);
+    return {
+        ...input,
+        ...(auth !== undefined ? { auth } : {}),
+        ...(tls !== undefined ? { tls: { ...input.tls, ...tls } } : {}),
+        ...(proxy !== undefined ? { proxy } : {}),
+        ...(sign !== undefined ? { sign } : {}),
+    };
+}
+/**
+ * The data of every event in a buffered event stream, in order: what a run read of the stream, to
+ * its end or the timeout. Undefined for any other response, and for one a live send streamed.
+ */
+function bufferedEvents(exchange) {
+    if (exchange.stream !== undefined || !isEventStream(exchange.headers['content-type']))
+        return undefined;
+    const events = [];
+    const parser = createSseParser((row) => {
+        if (row.kind === 'event')
+            events.push(row.data);
+    });
+    parser.push(exchange.body, 0);
+    parser.end();
+    return events;
+}
+/**
+ * A REST response as assertions and sequence transfers see it. A buffered event stream is the data
+ * of its events, in order, as a JSON array (spec §5.2).
+ */
+export function restSubject(exchange) {
+    const events = bufferedEvents(exchange);
+    return {
+        protocol: 'rest',
+        status: exchange.status,
+        durationMs: exchange.durationMs,
+        bodyText: events !== undefined ? JSON.stringify(events) : exchange.text,
+        bodyKind: events !== undefined || exchange.language === 'json' ? 'json' : exchange.language === 'xml' ? 'xml' : 'other',
+        headers: exchange.rawHeaders,
+    };
+}
+/** A webhook item's signing secret, read from `WIREBENCH_SECRET_<secretEnv>` (§5.2). */
+function signingNeeds(selected) {
+    const effective = selected.signing;
+    if (effective === undefined || effective.signing.mode !== 'sign')
+        return [];
+    const ref = signingSecretRef(effective.signing);
+    if (ref === undefined)
+        return [];
+    return [
+        {
+            ref,
+            ...(effective.signing.secretEnv !== undefined ? { envName: effective.signing.secretEnv } : {}),
+            purpose: `webhook signing secret (${signingSourceLabel(effective)})`,
+        },
+    ];
+}
+/**
+ * An API's requests in explorer order, without the ones its contract no longer has unless
+ * `orphaned` asks for them too.
+ */
+function apiCandidates(api, orphaned = false) {
+    const out = [];
+    walkTree(api, [], api.name, `apis/${api.slug}/requests`, (request, chain, group) => request.orphaned === true && !orphaned
+        ? undefined
+        : { kind: 'rest', path: `${group}/${request.name}`, group, api, chain, request }, out);
+    return out;
+}
+/** True for a webhook item, which `webhookCandidates` builds against the synthetic `webhooks` API. */
+function isWebhookItem(selected) {
+    return selected.api.id === 'webhooks';
+}
+/**
+ * The project's webhook items, as REST items against a synthetic API whose base URL is each item's
+ * effective target. A run has no history, so a callback uses the target.
+ */
+function webhookCandidates(collection, orphaned = false) {
+    const out = [];
+    const visit = (folders, requests, chain) => {
+        const group = ['Webhooks', ...chain.map((folder) => folder.name)].join('/');
+        const dir = [WEBHOOKS_DIR, REQUESTS_DIR, ...chain.map((folder) => folder.slug)].join('/');
+        const api = createApi('Webhooks', {
+            id: 'webhooks',
+            slug: 'webhooks',
+            baseUrl: effectiveTarget(collection, chain),
+            ...(collection.auth !== undefined ? { auth: collection.auth } : {}),
+        });
+        for (const request of [...requests].sort(byOrder)) {
+            if (request.orphaned === true && !orphaned)
+                continue;
+            out.push({
+                item: {
+                    kind: 'rest',
+                    path: `${group}/${request.name}`,
+                    group,
+                    api,
+                    chain,
+                    request,
+                    signing: effectiveSigning(collection, request.id),
+                },
+                diskPath: `${dir}/${request.slug}`,
+            });
+        }
+        for (const folder of [...folders].sort(byOrder))
+            visit(folder.folders, folder.requests, [...chain, folder]);
+    };
+    visit(collection.folders, collection.requests, []);
+    return out;
+}
+/**
+ * The REST item for `requestId`, an API request or a webhook item, built as a run builds it — and
+ * found even when its contract no longer has it (`orphaned`), which a run skips and a person may
+ * still send. Undefined when no REST request has that id.
+ */
+export function restItemFor(project, requestId) {
+    const candidates = [
+        ...project.apis.flatMap((api) => apiCandidates(api, true)),
+        ...(project.webhooks !== undefined ? webhookCandidates(project.webhooks, true) : []),
+    ];
+    return candidates.find((candidate) => candidate.item.request.id === requestId)?.item;
+}
+/** What a failed send was about to put on the wire: the resolved URL, the method, the enabled headers. */
+function attemptedOf(input) {
+    return {
+        url: joinBase(input.baseUrl, input.request.url),
+        method: input.request.method,
+        headers: Object.fromEntries(input.request.headers.filter((header) => header.enabled).map((header) => [header.name, header.value])),
+    };
+}
+/**
+ * Resolves, connects and sends one request, telling the host when either stage fails, then hands
+ * the response's cookies and its contract result to the host. A reference nothing resolves is
+ * refused in the prepare stage, with what would have been sent; a failure before resolve has an
+ * input is reported with nothing attempted.
+ */
+async function connectAndSend(selected, context, resolve, controller, live, 
+/** The pre-request script's step, inside the prepare stage so its failure is reported with it. */
+script) {
+    let startedAt = Date.now();
+    // Never masks the send's own error: a row that cannot be built, or a host that throws, is dropped.
+    const failed = (stage, error, attempted) => {
+        try {
+            context.host.events?.onFailed?.(selected, {
+                stage,
+                error,
+                startedAt,
+                durationMs: Date.now() - startedAt,
+                ...(attempted !== undefined ? { attempted: attemptedOf(attempted), input: attempted } : {}),
+            });
+        }
+        catch {
+            // Deliberately ignored — see above.
+        }
+    };
+    let input;
+    let connected;
+    try {
+        const resolved = await resolve();
+        input = resolved.input;
+        if (resolved.unresolved.length > 0) {
+            throw unresolvedError('rest-unresolved-properties', selected.path, resolved.unresolved);
+        }
+        connected = await connectRest(selected, context, script !== undefined ? await script(input) : input);
+    }
+    catch (error) {
+        failed('prepare', error, input);
+        throw error;
+    }
+    // The send stage's own clock: a send-stage failure never counts resolve, the script, the token or the proxy.
+    startedAt = Date.now();
+    let exchange;
+    try {
+        exchange = await sendRest({
+            ...connected,
+            signal: controller.signal,
+            // Not part of `connected`, which History and the log keep: the jar is the host's, per send.
+            ...(context.host.cookies !== undefined
+                ? { jar: { host: context.host.cookies, send: selected.request.settings.sendCookies === true } }
+                : {}),
+            // Only a live send parses an event stream; any other keeps the buffered body.
+            ...(live
+                ? {
+                    onStream: {
+                        onOpen: (status, headers) => controller.queue.push({ protocol: 'rest', kind: 'open', status, headers }),
+                        onRow: (row) => controller.queue.push({ protocol: 'rest', kind: 'row', row }),
+                    },
+                }
+                : {}),
+        });
+    }
+    catch (error) {
+        failed('send', error, connected);
+        throw error;
+    }
+    dropRefusedToken(context, connected.auth, exchange.status === 401);
+    // The request has gone out: a contract check that rejects checked nothing, and fails nothing.
+    const contract = await context.host.contractFor?.(selected, exchange, connected).catch(() => undefined);
+    return {
+        connected,
+        sent: {
+            subject: restSubject(exchange),
+            raw: exchange,
+            exchange: { kind: 'rest', rest: exchange, input: connected, ...(contract !== undefined ? { contract } : {}) },
+            ...originOf(exchange.request.url),
+        },
+    };
+}
+/**
+ * One REST request as a run sends it (spec §3.4): resolve, run its pre-request script when
+ * `scripts` is given, connect, send, then its post-response script.
+ */
+async function sendRestItem(selected, context, scripts, controller, live) {
+    if (scripts === undefined) {
+        return (await connectAndSend(selected, context, () => resolveRest(selected, context), controller, live)).sent;
+    }
+    // Resolved with its secrets behind placeholders; the URL is rebuilt only when the script changed it.
+    const resolve = () => resolveRest(selected, { ...context, secretPlaceholders: scripts.placeholders });
+    let sent;
+    const result = await connectAndSend(selected, context, resolve, controller, live, async (input) => {
+        const before = restRequestSnapshot(input);
+        sent = await scripts.session.pre(before);
+        const changed = applyRestSnapshot(input, before, sent);
+        const restored = await scripts.placeholders.restore({ baseUrl: changed.baseUrl, request: changed.request }, context.host.getSecret);
+        return { ...changed, ...restored };
+    });
+    const exchange = result.sent.raw;
+    return {
+        ...result.sent,
+        script: await scripts.session.post(sent, restResponseSnapshot(exchange)),
+    };
+}
+/** REST's run facet. */
+export const restRun = {
+    groups(project) {
+        const apis = project.apis.map((api) => ({
+            order: api.order,
+            name: api.name,
+            candidates: apiCandidates(api),
+        }));
+        // Webhook items deliver to a receiver rather than test an API: sent only when a selector names one.
+        return project.webhooks === undefined
+            ? apis
+            : [...apis, { order: 0, name: 'Webhooks', candidates: webhookCandidates(project.webhooks), explicitOnly: true }];
+    },
+    whyNotRunnable(project, requestId) {
+        if (project.webhooks !== undefined && findInTree(project.webhooks, requestId) !== undefined) {
+            return 'A webhook cannot be a sequence step';
+        }
+        for (const api of project.apis) {
+            const request = findInTree(api, requestId);
+            if (request !== undefined) {
+                return request.orphaned === true ? ORPHANED_STEP_REASON : undefined;
+            }
+        }
+        return undefined;
+    },
+    open(selected, scope, host, options) {
+        const controller = exchangeController('rest', options);
+        const context = { ...scope.context, host, signal: controller.signal };
+        return controller.handle(() => sendRestItem(selected, context, options.scripts, controller, options.live === true));
+    },
+    resolve(selected, scope, host) {
+        return resolveRest(selected, { ...scope.context, host });
+    },
+    async scriptTypes(selected, scope) {
+        const { api } = selected;
+        const openApi = await scope.memo(`rest:${api.id}:openapi`, () => loadOpenApiDocument(scope.context.projectDir, api.slug));
+        return { generated: restScriptTypes(restOperationFor(openApi, selected.request.contract)) };
+    },
+    secretNeeds(selected, project) {
+        return [
+            ...secretNeedsOfAuth(restEffectiveAuth(selected)),
+            ...keystoreNeeds(project, selected.request.settings.sslKeystoreRef),
+            ...signingNeeds(selected),
+        ];
+    },
+};

package/dist/rest/script-types.d.ts

@@ -0,0 +1,7 @@
+import type { RestContractLink } from './model.js';
+import type { OpenApiDocument, OpenApiOperation } from './openapi/model.js';
+export declare function restScriptTypes(operation: OpenApiOperation | undefined): string;
+/** The operation a REST request is linked to, by its method and templated path. */
+export declare function restOperationFor(document: OpenApiDocument | undefined, contract: RestContractLink | undefined): OpenApiOperation | undefined;
+/** An API's cached OpenAPI document, read offline; `undefined` when it has none or it cannot be read. */
+export declare function loadOpenApiDocument(projectDir: string, apiSlug: string): Promise<OpenApiDocument | undefined>;

package/dist/rest/script-types.js

@@ -0,0 +1,83 @@
+/**
+ * A REST request's script types, from the OpenAPI operation it is linked to (spec §Types, REST).
+ *
+ * `WbRequestBody` is the JSON request body's type. `WbResponse` is a union with one arm per declared
+ * status. Each arm's `status` is a set of literals — one code, a range less the codes declared on
+ * their own, or everything left for `default` — so `response.status === 200` narrows `json()` exactly,
+ * and a status the contract does not declare falls into a last arm whose body is `unknown`.
+ */
+import { ProjectError } from '../errors.js';
+import { apiDefinitionDir } from '../project/paths.js';
+import { JsonSchemaTypes } from '../script/types/json-schema.js';
+import { createCachedApiFetch, readApiDefinitionCache } from './openapi/cache.js';
+import { parseOpenApi } from './openapi/import.js';
+/** The JSON media type among a content map's keys, if any. */
+function jsonMedia(content) {
+    if (content === undefined) {
+        return undefined;
+    }
+    const key = Object.keys(content).find((k) => /^application\/json\b/i.test(k)) ??
+        Object.keys(content).find((k) => /\+json\b/i.test(k));
+    return key === undefined ? undefined : content[key];
+}
+export function restScriptTypes(operation) {
+    if (operation === undefined) {
+        return [
+            '// This request is not linked to an operation of its API, so its bodies are untyped.',
+            'type WbRequestBody = unknown;',
+            'type WbResponse = WbResponseArm<WbStatus, unknown>;',
+            '',
+        ].join('\n');
+    }
+    const types = new JsonSchemaTypes();
+    const requestMedia = jsonMedia(operation.requestBody?.content);
+    const requestBody = requestMedia?.schema !== undefined ? types.typeOf(requestMedia.schema) : 'unknown';
+    const responses = operation.responses ?? {};
+    const exact = Object.keys(responses).filter((key) => /^[1-5]\d\d$/.test(key));
+    const ranges = Object.keys(responses).filter((key) => /^[1-5]XX$/i.test(key));
+    const exactUnion = exact.length > 0 ? exact.join(' | ') : 'never';
+    const rangeTypes = ranges.map((key) => `WbRange${key[0]}`);
+    const arms = [];
+    const bodyOf = (key) => {
+        const media = jsonMedia(responses[key]?.content);
+        return media?.schema !== undefined ? types.typeOf(media.schema) : 'unknown';
+    };
+    for (const key of exact) {
+        arms.push(`WbResponseArm<${key}, ${bodyOf(key)}>`);
+    }
+    for (const key of ranges) {
+        arms.push(`WbResponseArm<Exclude<WbRange${key[0]}, ${exactUnion}>, ${bodyOf(key)}>`);
+    }
+    const covered = [exactUnion, ...rangeTypes].filter((t) => t !== 'never').join(' | ') || 'never';
+    const rest = `Exclude<WbStatus, ${covered}>`;
+    arms.push(`WbResponseArm<${rest}, ${responses['default'] !== undefined ? bodyOf('default') : 'unknown'}>`);
+    const where = `${operation.method.toUpperCase()} ${operation.path}`.replace(/\*\//g, '*\\/');
+    return [
+        `// Types from the contract's ${where}.`,
+        types.declarations(),
+        `type WbRequestBody = ${requestBody};`,
+        `type WbResponse =\n  | ${arms.join('\n  | ')};`,
+        '',
+    ].join('\n');
+}
+/** The operation a REST request is linked to, by its method and templated path. */
+export function restOperationFor(document, contract) {
+    if (document === undefined || contract === undefined)
+        return undefined;
+    return document.operations.find((op) => op.method.toLowerCase() === contract.method.toLowerCase() && op.path === contract.path);
+}
+/** An API's cached OpenAPI document, read offline; `undefined` when it has none or it cannot be read. */
+export async function loadOpenApiDocument(projectDir, apiSlug) {
+    const dir = apiDefinitionDir(projectDir, apiSlug);
+    try {
+        const cached = await readApiDefinitionCache(dir);
+        const offline = createCachedApiFetch(cached.manifest, dir, (location) => Promise.reject(new ProjectError('definition-cache-missing', `"${location}" is not in this API's definition cache`, {
+            details: { location },
+        })));
+        const parsed = await parseOpenApi({ kind: 'url', url: cached.manifest.rootLocation }, { fetchDocument: offline });
+        return parsed.document;
+    }
+    catch {
+        return undefined;
+    }
+}