@sponson/adapters 0.4.0 → 0.5.0

package/dist/http-adapter-spec.js

@@ -0,0 +1,660 @@
+/**
+ * The generic `http` adapter's plan syntax, parsed and checked: the per-API provider block, the params of
+ * `http.resource` and `http.list_item`, JSON pointers and path placeholders. Pure: no I/O. Every malformed spec is
+ * a PARAM_INVALID (or PLAN_INVALID for the provider block) naming the field at fault. See ADR 0017 and
+ * docs/plan-format.md (`http.resource`, `http.list_item`).
+ */
+import { canonicalJson, markerKind, sha256 } from "@sponson/core";
+import { paramError } from "./common.js";
+import { isObject } from "./http.js";
+import { HEADER_NAME, envName, parseAuth, planError } from "./http-adapter-auth.js";
+import { parseGraphql, usesId } from "./http-adapter-graphql.js";
+import { expandRecipe, lineApi, resolveRecipeApi } from "./recipes.js";
+export const ADAPTER = "http";
+// ---------------------------------------------------------------------------
+// JSON pointers (RFC 6901) and field names
+// ---------------------------------------------------------------------------
+/** A JSON pointer's reference tokens. `""` is the whole document. */
+export function pointerTokens(pointer) {
+    if (pointer === "")
+        return [];
+    return pointer.slice(1).split("/").map((t) => t.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+/** A field as the plan writes it: `name` (a top-level field) or a JSON pointer `/config/url`. */
+export function fieldTokens(field) {
+    return field.startsWith("/") ? pointerTokens(field) : [field];
+}
+/** The value at `tokens` in `doc`, or undefined. */
+export function at(doc, tokens) {
+    let cur = doc;
+    for (const t of tokens) {
+        if (Array.isArray(cur) && /^\d+$/.test(t))
+            cur = cur[Number(t)];
+        else if (isObject(cur))
+            cur = cur[t];
+        else
+            return undefined;
+    }
+    return cur;
+}
+/** A copy of `doc` (an object) with `value` set at `tokens`, creating objects on the way. */
+export function setAt(doc, tokens, value) {
+    if (tokens.length === 0)
+        return isObject(value) ? { ...value } : doc;
+    const [head, ...rest] = tokens;
+    const child = isObject(doc[head]) ? doc[head] : {};
+    return { ...doc, [head]: rest.length === 0 ? value : setAt(child, rest, value) };
+}
+/** Objects merged recursively (`b` wins); anything else is replaced by `b`. */
+export function deepMerge(a, b) {
+    const out = { ...a };
+    for (const [k, v] of Object.entries(b))
+        out[k] = isObject(v) && isObject(out[k]) ? deepMerge(out[k], v) : v;
+    return out;
+}
+/** The request body that sets every field of `fields` (names or pointers), skipping `skip`. */
+export function bodyOf(fields, skip = () => false) {
+    let body = {};
+    for (const [f, v] of Object.entries(fields))
+        if (!skip(v))
+            body = setAt(body, fieldTokens(f), v);
+    return body;
+}
+/** `item` reduced to the declared fields, in the one canonical form both hashes and diffs use. Absent is null. */
+export function projection(item, fields) {
+    return Object.fromEntries(fields.map((f) => [f, at(item, fieldTokens(f)) ?? null]));
+}
+/** The hash of a resource's declared state: `sha256(canonicalJson(projection))`. */
+export function stateHash(state) {
+    return sha256(canonicalJson(state));
+}
+/** True when the value is `{ keep: true }`'s marker. */
+export function isKeep(v) {
+    return markerKind(v) === "keep";
+}
+/** The first pending or secret marker anywhere in `v`, if any. */
+export function firstMarker(v) {
+    const kind = markerKind(v);
+    if (kind === "pending" || kind === "secret")
+        return v;
+    if (Array.isArray(v))
+        return v.map(firstMarker).find((m) => m !== undefined);
+    if (isObject(v))
+        return Object.values(v).map(firstMarker).find((m) => m !== undefined);
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Param checks
+// ---------------------------------------------------------------------------
+function fail(message, param) {
+    return paramError(ADAPTER, message, param);
+}
+function optionalObject(v, param) {
+    if (v === undefined || v === null)
+        return undefined;
+    if (!isObject(v))
+        throw fail(`\`${param}\` must be a map`, param);
+    return v;
+}
+function requiredObject(v, param) {
+    const o = optionalObject(v, param);
+    if (!o)
+        throw fail(`\`${param}\` is required`, param);
+    return o;
+}
+/** A path: starts with `/`; pending markers are allowed in the `{name}` values only, not here. */
+function pathParam(v, param) {
+    if (typeof v !== "string" || !v.startsWith("/"))
+        throw fail(`\`${param}\` must be a path starting with "/" (relative to the API's base_url)`, param);
+    return v;
+}
+function pointerParam(v, param, fallback) {
+    if (v === undefined || v === null)
+        return fallback;
+    if (typeof v !== "string" || (v !== "" && !v.startsWith("/")))
+        throw fail(`\`${param}\` must be a JSON pointer: "" for the whole body, or "/field/sub"`, param);
+    return v;
+}
+function fieldParam(v, param) {
+    if (typeof v !== "string" || v === "")
+        throw fail(`\`${param}\` must be a field name or a JSON pointer such as "/config/url"`, param);
+    return v;
+}
+function methodParam(v, param, allowed, fallback) {
+    if (v === undefined || v === null)
+        return fallback;
+    const m = typeof v === "string" ? v.toUpperCase() : "";
+    if (!allowed.includes(m))
+        throw fail(`\`${param}\` must be one of ${allowed.join(", ")}`, param);
+    return m;
+}
+/** `{name}` (the value URI-encoded as one segment) or `{+name}` (reserved expansion, RFC 6570: `/` and `:` kept). */
+const PLACEHOLDER = /\{(\+?)([A-Za-z_][A-Za-z0-9_]*)\}/g;
+/** The `{name}` and `{+name}` placeholders of a path, by name. */
+export function placeholders(path) {
+    return [...path.matchAll(PLACEHOLDER)].map((m) => m[2]);
+}
+/**
+ * A value as a path placeholder: one segment, URI-encoded; or, for `{+name}`, a URL or path written as it is
+ * (QStash takes the destination URL raw in the path), with only what cannot stand in a path escaped.
+ */
+function encodeSegment(value, reserved) {
+    return reserved ? encodeURI(value).replace(/[?#]/g, (c) => encodeURIComponent(c)) : encodeURIComponent(value);
+}
+/** Every placeholder of `path` must be `{id}` (when `id` is allowed) or a key of `vars`. */
+function checkPlaceholders(path, param, vars, idAllowed) {
+    for (const name of placeholders(path)) {
+        if (name === "id" && idAllowed)
+            continue;
+        if (!(name in vars))
+            throw fail(`\`${param}\` uses \`{${name}}\`, which is ${name === "id" ? "not known here (the id exists only once the object does)" : "not declared in `vars`"}`, param);
+    }
+}
+/**
+ * `path` with `{id}` and every `{var}` substituted (URI-encoded; `{+var}` keeps `/` and `:`); undefined when a value
+ * is not known yet (a pending reference).
+ */
+export function fillPath(path, vars, id) {
+    const value = (name) => (name === "id" && id !== undefined ? id : vars[name]);
+    const known = (v) => markerKind(v) === null && v !== undefined && v !== null && typeof v !== "object";
+    if (!placeholders(path).every((name) => known(value(name))))
+        return undefined;
+    return path.replace(PLACEHOLDER, (_m, plus, name) => encodeSegment(String(value(name)), plus === "+"));
+}
+const API_KEYS = ["base_url", "base_url_env", "auth", "headers", "encoding", "media_type", "production", "refuse_credential"];
+function parseEncoding(v, where) {
+    if (v === undefined || v === "json" || v === "form" || v === "xml")
+        return v ?? "json";
+    throw planError("must be `json` (the default), `form` (application/x-www-form-urlencoded) or `xml` (S3-style XML documents)", where);
+}
+function parseHeaders(v, where) {
+    if (v === undefined)
+        return {};
+    if (!isObject(v))
+        throw planError("must be a map of header name to string value", where);
+    for (const [k, x] of Object.entries(v)) {
+        if (!HEADER_NAME.test(k) || typeof x !== "string")
+            throw planError(`\`${k}\` must be a header name with a string value`, where);
+        if (/^(authorization|accept|content-type)$/i.test(k))
+            throw planError(`\`${k}\` is set by Sponson; configure the credential under \`auth\` and a versioned media type under \`media_type\``, where);
+    }
+    return v;
+}
+function parseMediaType(v, where, encoding) {
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== "string" || !/^[\w.+-]+\/[\w.+-]+(\s*;.*)?$/.test(v))
+        throw planError("must be a media type such as application/vnd.atlas.2023-01-01+json", where);
+    if (encoding !== "json")
+        throw planError("applies to `encoding: json` only", where);
+    return v;
+}
+function parseProduction(v, where) {
+    if (v === undefined || typeof v === "boolean")
+        return v ?? false;
+    throw planError("must be true (lines through this API write production and need approval) or false", where);
+}
+/**
+ * `OpSpec.writesEnvironment` for both ops: `production` when the line's API block says `production: true` (a live
+ * Stripe account, a production tenant), so the run needs approval whatever its environment; otherwise not
+ * environment-specific. `provider` is the block `apiBlock` narrowed to, already checked.
+ */
+export function apiEnvironment(_params, _ctx, provider) {
+    return provider?.production === true ? "production" : null;
+}
+/**
+ * One API block, checked. `where` names it in messages (`providers.http.statsig`). `authOptional`: a block without
+ * `auth` sends no credential (the `manual` adapter's verify requests to public endpoints); the `http` adapter's
+ * blocks always need one.
+ */
+export function parseApi(block, where, opts = {}) {
+    const base = block.base_url;
+    if (typeof base !== "string" || !/^https?:\/\/[^\s]+$/.test(base))
+        throw planError("`base_url` must be an http(s) URL", where);
+    const unknown = Object.keys(block).filter((k) => !API_KEYS.includes(k));
+    if (unknown.length)
+        throw planError(`unknown key \`${unknown[0]}\` (known: ${API_KEYS.join(", ")})`, where);
+    const encoding = parseEncoding(block.encoding, `${where}.encoding`);
+    const mediaType = parseMediaType(block.media_type, `${where}.media_type`, encoding);
+    const cfg = {
+        baseUrl: base,
+        auth: block.auth === undefined && opts.authOptional ? { kind: "none" } : parseAuth(block.auth, `${where}.auth`, base),
+        headers: parseHeaders(block.headers, `${where}.headers`),
+        encoding,
+        ...(mediaType ? { mediaType } : {}),
+        production: parseProduction(block.production, `${where}.production`),
+    };
+    if (block.base_url_env !== undefined)
+        cfg.baseUrlEnv = envName(block.base_url_env, `${where}.base_url_env`, false);
+    if (block.refuse_credential !== undefined)
+        cfg.refuse = parseRefuse(block.refuse_credential, `${where}.refuse_credential`);
+    return cfg;
+}
+function parseRefuse(v, where) {
+    const prefixes = isObject(v) ? v.prefixes : undefined;
+    if (!isObject(v) || !Array.isArray(prefixes) || prefixes.length === 0 || !prefixes.every((p) => typeof p === "string" && p.length >= 3)) {
+        throw planError("must be `{ prefixes: [sk_live_, …], unless_env: NAME }`: credential prefixes to refuse, and the variable that allows them", where);
+    }
+    const extra = Object.keys(v).find((k) => k !== "prefixes" && k !== "unless_env");
+    if (extra)
+        throw planError(`unknown key \`${extra}\` (known: prefixes, unless_env)`, where);
+    return { prefixes: prefixes, unlessEnv: envName(v.unless_env, `${where}.unless_env`, false) };
+}
+/**
+ * `OpSpec.providerFor` for both ops: the `providers.http.<api>` block the line's `api` names, checked. Lines of
+ * different APIs therefore have independent ledger identities.
+ */
+export function apiBlock(block, params) {
+    const api = lineApi(params);
+    if (typeof api !== "string" || api === "")
+        throw fail("`api` is required: the name of an API configured under `providers.http`", "api");
+    const where = `providers.http.${api}`;
+    const recipe = typeof params.recipe === "string" ? params.recipe.split(".")[0] : undefined;
+    // A recipe line needs no block of its own: `api` defaults to the recipe's provider, and so does its block.
+    const raw = block[api] ?? (recipe === api ? { recipe } : undefined);
+    if (!isObject(raw)) {
+        const known = Object.keys(block);
+        throw planError(`no API \`${api}\` is configured (known: ${known.length ? known.join(", ") : "none"})`, where);
+    }
+    const cfg = resolveRecipeApi(raw, where);
+    if (raw.recipe !== undefined && recipe !== undefined && recipe !== raw.recipe)
+        throw planError(`uses recipe \`${String(raw.recipe)}\`, but the line's recipe is \`${String(params.recipe)}\``, where);
+    if (raw.recipe !== undefined && raw.refuse_credential !== undefined) {
+        // A recipe's refusal is a safety rule (Stripe: never live keys from a preview), not a default to tune per plan.
+        throw planError("`refuse_credential` comes from the recipe and cannot be overridden; its `unless_env` variable is the opt-out", `${where}.refuse_credential`);
+    }
+    if (raw.recipe !== undefined && cfg.base_url === undefined)
+        throw planError(`recipe \`${String(raw.recipe)}\` has no default \`base_url\` (each account has its own): set \`base_url\` in this block`, where);
+    lineCredentialFits(params, parseApi(cfg, where), where);
+    return cfg;
+}
+/** A line's `credential` replaces a single static credential's variable: the block must have one. */
+function lineCredentialFits(params, api, where) {
+    if (params.credential === undefined || api.auth.kind === "bearer" || api.auth.kind === "header")
+        return;
+    throw fail(`\`credential\` replaces the value of a single static credential (\`bearer_env\`, or \`header\` with \`value_env\`); ${where} authenticates with \`${api.auth.kind}\``, "credential");
+}
+/** A `credential` as the plan may write it: a reference (as written), its resolved value, or a marker. */
+function credentialShape(v) {
+    if (isKeep(v))
+        return false;
+    if (typeof v === "string" || markerKind(v) !== null)
+        return true;
+    return isObject(v) && Object.keys(v).length === 1 && (typeof v.from === "string" || typeof v.secret === "string");
+}
+/**
+ * A line's `credential` (ADR 0017, "Line credentials"): the value that replaces the API block's credential variable
+ * for this line, as resolved (a string, or a marker while it is pending), or the reference as written. Never part
+ * of identity. Destroy works from the ledger alone, which cannot reach it, so the line must say `destroy: keep`.
+ */
+function parseCredential(params, destroy) {
+    const v = params.credential;
+    if (v === undefined)
+        return {};
+    if (!credentialShape(v))
+        throw fail("`credential` must be `{ from: <line>.<output> }` (a sensitive output) or `{ secret: <reference> }`", "credential");
+    if (v === "")
+        throw fail("`credential` resolved to an empty value", "credential");
+    if (destroy !== "keep") {
+        throw fail("a line with `credential` must say `destroy: keep`: destroy works from the ledger alone, which never holds the credential, so what the line makes goes away with the object the credential belongs to (a Postmark server takes its webhooks with it)", "destroy");
+    }
+    return { credential: v };
+}
+function parseDestroy(v) {
+    if (v === undefined || v === "delete" || v === "keep")
+        return v ?? "delete";
+    throw fail("`destroy` must be `delete` (the default) or `keep` (leave it in place when the scope is destroyed)", "destroy");
+}
+function statusList(v, param) {
+    if (v === undefined)
+        return [];
+    const list = Array.isArray(v) ? v : [v];
+    if (!list.every((s) => Number.isInteger(s) && s >= 400 && s <= 599))
+        throw fail(`\`${param}\` must be a list of HTTP error statuses (400–599)`, param);
+    return list;
+}
+function contentTypeParam(v, param) {
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== "string" || !/^[\w.+-]+\/[\w.+-]+(\s*;.*)?$/.test(v))
+        throw fail(`\`${param}\` must be a media type such as application/merge-patch+json`, param);
+    return v;
+}
+function apiParam(params) {
+    const api = params.api;
+    if (typeof api !== "string" || api === "")
+        throw fail("`api` is required: the name of an API configured under `providers.http`", "api");
+    return api;
+}
+function noUnknownParams(params, known, op) {
+    const extra = Object.keys(params).find((k) => !known.includes(k));
+    if (extra)
+        throw fail(`\`${extra}\` is not a parameter of http.${op} (known: ${known.join(", ")})`, extra);
+}
+const RESOURCE_PARAMS = ["api", "credential", "vars", "create", "read", "find", "update", "delete", "destroy", "item_path", "id_path", "fields", "outputs", "exists_status", "gone_status"];
+/** Per-request headers: names Sponson does not set itself; values are checked once resolved (`requestHeaders`). */
+function requestHeadersParam(v, param) {
+    const o = optionalObject(v, param) ?? {};
+    for (const k of Object.keys(o)) {
+        if (!HEADER_NAME.test(k))
+            throw fail(`\`${param}.${k}\` is not a header name`, `${param}.${k}`);
+        if (/^(authorization|accept|content-type|idempotency-key)$/i.test(k))
+            throw fail(`\`${param}.${k}\` is set by Sponson or the API block`, `${param}.${k}`);
+    }
+    return o;
+}
+/** `{ graphql }` in place of a REST request: nothing else may be next to it. */
+function asGraphql(o, param, idAllowed) {
+    if (o.graphql === undefined)
+        return undefined;
+    const extra = Object.keys(o).find((k) => k !== "graphql");
+    if (extra)
+        throw fail(`\`${param}.${extra}\` does not apply to a GraphQL request (the query and its variables say everything)`, `${param}.${extra}`);
+    return { method: "POST", path: "", body: {}, headers: {}, sendFields: true, graphql: parseGraphql(o.graphql, `${param}.graphql`, idAllowed) };
+}
+function parseRequest(v, param, methods, fallback, vars, idAllowed, defaultPath) {
+    const o = requiredObject(v, param);
+    const gql = asGraphql(o, param, idAllowed);
+    if (gql)
+        return gql;
+    const path = o.path === undefined && defaultPath !== undefined ? defaultPath : pathParam(o.path, `${param}.path`);
+    checkPlaceholders(path, `${param}.path`, vars, idAllowed);
+    const contentType = contentTypeParam(o.content_type, `${param}.content_type`);
+    if (o.send_fields !== undefined && typeof o.send_fields !== "boolean")
+        throw fail(`\`${param}.send_fields\` must be true or false`, `${param}.send_fields`);
+    return {
+        method: methodParam(o.method, `${param}.method`, methods, fallback),
+        path,
+        body: optionalObject(o.body, `${param}.body`) ?? {},
+        ...(contentType ? { contentType } : {}),
+        headers: requestHeadersParam(o.headers, `${param}.headers`),
+        sendFields: o.send_fields !== false,
+    };
+}
+/** A request's headers with their resolved values, as strings; PARAM_INVALID for a value that is not a scalar. */
+export function requestHeaders(req, param) {
+    const out = {};
+    for (const [k, v] of Object.entries(req.headers)) {
+        if (typeof v !== "string" && typeof v !== "number" && typeof v !== "boolean")
+            throw fail(`\`${param}.headers.${k}\` must be a string, number or boolean`, `${param}.headers.${k}`);
+        out[k] = String(v);
+    }
+    return out;
+}
+function parseCreate(v, vars) {
+    const r = parseRequest(v, "create", ["POST", "PUT", "PATCH"], "POST", vars, false);
+    if (r.graphql)
+        return { ...r, idempotencyKey: false, locate: false };
+    const { idempotency_key: key, locate } = v;
+    if (key !== undefined && typeof key !== "boolean")
+        throw fail("`create.idempotency_key` must be true or false", "create.idempotency_key");
+    if (locate !== undefined && typeof locate !== "boolean")
+        throw fail("`create.locate` must be true or false", "create.locate");
+    return { ...r, idempotencyKey: key === true, locate: locate === true };
+}
+function parseFind(v, vars) {
+    const o = optionalObject(v, "find");
+    if (!o)
+        return undefined;
+    if (o.graphql !== undefined)
+        return parseGraphqlFind(o);
+    const path = pathParam(o.path, "find.path");
+    checkPlaceholders(path, "find.path", vars, false);
+    const match = requiredObject(o.match, "find.match");
+    if (Object.keys(match).length === 0)
+        throw fail("`find.match` must name at least one field", "find.match");
+    const spec = { path, listPath: pointerParam(o.list_path, "find.list_path", ""), match };
+    if (o.next !== undefined) {
+        const param = o.cursor_param === undefined ? "cursor" : o.cursor_param;
+        if (typeof param !== "string" || param === "")
+            throw fail("`find.cursor_param` must be a query parameter name", "find.cursor_param");
+        spec.next = { path: pointerParam(o.next, "find.next", ""), param };
+    }
+    return spec;
+}
+/** A find whose list comes from a GraphQL query: no path, no cursor pages. */
+function parseGraphqlFind(o) {
+    const extra = Object.keys(o).find((k) => !["graphql", "list_path", "match"].includes(k));
+    if (extra)
+        throw fail(`\`find.${extra}\` does not apply to a GraphQL find (known: graphql, list_path, match)`, `find.${extra}`);
+    const match = requiredObject(o.match, "find.match");
+    if (Object.keys(match).length === 0)
+        throw fail("`find.match` must name at least one field", "find.match");
+    return { path: "", graphql: parseGraphql(o.graphql, "find.graphql", false), listPath: pointerParam(o.list_path, "find.list_path", ""), match };
+}
+function parseRead(v, vars, find) {
+    const o = optionalObject(v, "read");
+    if (!o) {
+        if (!find)
+            throw fail("needs `read` (a path or a GraphQL query that names the object) or `find` (a list and the fields that identify it)", "read");
+        return undefined;
+    }
+    if (o.graphql !== undefined) {
+        const gql = asGraphql(o, "read", true).graphql;
+        if (usesId(gql.variables) && !find)
+            throw fail('`read.graphql.variables` uses "{id}", so the object can only be located with `find` (the id is not in the plan)', "read.graphql.variables");
+        return { path: "", graphql: gql };
+    }
+    const path = pathParam(o.path, "read.path");
+    if (placeholders(path).includes("id") && !find)
+        throw fail("`read.path` uses `{id}`, so the object can only be located with `find` (the id is not in the plan)", "read.path");
+    checkPlaceholders(path, "read.path", vars, true);
+    return { path };
+}
+/** Update and delete go to the read path by default: the object's own URL. */
+function parseDelete(v, vars, read) {
+    if (v === undefined && (read === undefined || read.graphql))
+        throw fail("`delete` is required: `{ path: /things/{id} }` or `{ graphql: { query: … } }` (no `read.path` to default to)", "delete");
+    const r = parseRequest(v ?? {}, "delete", ["DELETE", "POST"], "DELETE", vars, true, read?.graphql ? undefined : read?.path);
+    if (r.graphql)
+        return { method: r.method, path: r.path, graphql: r.graphql };
+    if (Object.keys(r.body).length === 0)
+        return { method: r.method, path: r.path };
+    if (r.method !== "POST")
+        throw fail("`delete.body` needs `method: POST` (an archive request such as `{ active: false }`)", "delete.body");
+    // The body travels in the record id, which the ledger keeps: plain values only, never a reference or a secret.
+    if (firstMarker(r.body) !== undefined || JSON.stringify(r.body).includes("${"))
+        throw fail("`delete.body` must hold literal values only", "delete.body");
+    return { method: r.method, path: r.path, body: r.body };
+}
+function parseOutputs(v) {
+    const o = optionalObject(v, "outputs") ?? {};
+    const out = {};
+    for (const [name, decl] of Object.entries(o)) {
+        const param = `outputs.${name}`;
+        if (name === "id")
+            throw fail("`outputs.id` is reserved: the object's id is always the output `id`", param);
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+            throw fail(`output name \`${name}\` must be letters, digits and _`, param);
+        if (typeof decl === "string")
+            out[name] = { path: pointerParam(decl, param, ""), sensitive: false, once: false };
+        else if (isObject(decl))
+            out[name] = outputDecl(decl, param);
+        else
+            throw fail(`\`${param}\` must be a JSON pointer, or \`{ path, sensitive: true, once?: true }\``, param);
+    }
+    return out;
+}
+/** `{ path, sensitive?, once? }`. A value shown only at creation is a credential, so `once` requires `sensitive`. */
+function outputDecl(decl, param) {
+    for (const flag of ["sensitive", "once"]) {
+        if (decl[flag] !== undefined && typeof decl[flag] !== "boolean")
+            throw fail(`\`${param}.${flag}\` must be true or false`, `${param}.${flag}`);
+    }
+    if (decl.once === true && decl.sensitive !== true)
+        throw fail(`\`${param}\` is \`once\` (shown only when the object is created), so it must be \`sensitive: true\` too`, `${param}.sensitive`);
+    return { path: pointerParam(decl.path, `${param}.path`, ""), sensitive: decl.sensitive === true, once: decl.once === true };
+}
+function parseFields(v, param) {
+    const o = optionalObject(v, param) ?? {};
+    for (const f of Object.keys(o))
+        fieldParam(f, `${param}.${f}`);
+    return o;
+}
+/** `http.resource` params, checked; PARAM_INVALID naming the field otherwise. */
+export function parseResource(line) {
+    const params = expandRecipe(line, "resource");
+    noUnknownParams(params, RESOURCE_PARAMS, "resource");
+    const api = apiParam(params);
+    const vars = optionalObject(params.vars, "vars") ?? {};
+    const find = parseFind(params.find, vars);
+    const read = parseRead(params.read, vars, find);
+    const destroy = parseDestroy(params.destroy);
+    const spec = {
+        api,
+        vars,
+        ...parseCredential(params, destroy),
+        create: parseCreate(params.create, vars),
+        ...(find ? { find } : {}),
+        ...(read ? { read } : {}),
+        delete: parseDelete(params.delete, vars, read),
+        destroy,
+        itemPath: pointerParam(params.item_path, "item_path", ""),
+        idPath: pointerParam(params.id_path, "id_path", "/id"),
+        fields: parseFields(params.fields, "fields"),
+        outputs: parseOutputs(params.outputs),
+        existsStatus: statusList(params.exists_status, "exists_status"),
+        goneStatus: statusList(params.gone_status, "gone_status"),
+    };
+    if (params.update !== undefined)
+        spec.update = parseRequest(params.update, "update", ["PATCH", "PUT", "POST"], "PATCH", vars, true, read?.graphql ? undefined : read?.path);
+    noSecretIn(find?.graphql?.variables, "find.graphql.variables");
+    noSecretIn(read?.graphql?.variables, "read.graphql.variables");
+    noSecretIn(spec.delete.graphql?.variables, "delete.graphql.variables");
+    return spec;
+}
+/**
+ * The variables of a locating or deleting GraphQL request become part of the resource key or the record id, which
+ * receipts keep: a `{ secret }` there is refused (it would be masked, and the key or the delete broken).
+ */
+function noSecretIn(v, param) {
+    if (v !== undefined && firstSecret(v))
+        throw fail(`\`${param}\` may not hold a \`{ secret }\`: it becomes part of the resource key or the delete request kept in receipts`, param);
+}
+function firstSecret(v) {
+    if (markerKind(v) === "secret")
+        return true;
+    if (Array.isArray(v))
+        return v.some(firstSecret);
+    return isObject(v) && Object.values(v).some(firstSecret);
+}
+/**
+ * `OpSpec.credentialInputs` for both ops: the line's `credential`, which the engine checks is a masked reference.
+ * Its own rules (its form, `destroy: keep`) are checked here too, so a wrong line fails before any request.
+ */
+export function credentialInputs(kind) {
+    return (line) => {
+        if (line.credential === undefined)
+            return [];
+        const params = expandRecipe(line, kind);
+        parseCredential(params, parseDestroy(params.destroy));
+        return ["credential"];
+    };
+}
+/** The outputs one `http.resource` line declares: always `id`, plus its `outputs` (`once` ones as in ADR 0018). */
+export function resourceOutputs(line) {
+    const params = expandRecipe(line, "resource");
+    const out = { id: { available: "immediate" } };
+    for (const [name, d] of Object.entries(parseOutputs(params.outputs)))
+        out[name] = { available: "immediate", ...(d.sensitive ? { sensitive: true } : {}), ...(d.once ? { once: true } : {}) };
+    return out;
+}
+const LIST_PARAMS = ["api", "credential", "vars", "parent", "list_path", "shape", "separator", "item", "key_field", "value", "destroy"];
+function parseParent(v, vars) {
+    const o = requiredObject(v, "parent");
+    const path = pathParam(o.path, "parent.path");
+    checkPlaceholders(path, "parent.path", vars, false);
+    const readPath = o.read_path === undefined ? path : pathParam(o.read_path, "parent.read_path");
+    checkPlaceholders(readPath, "parent.read_path", vars, false);
+    const ifMissing = oneOf(o.if_missing, ["error", "empty"], "parent.if_missing", "`error` (the default: a parent that is not there is an error) or `empty` (a 404 reads as an empty collection, S3 CORS)");
+    const whenEmpty = oneOf(o.when_empty, ["write", "delete"], "parent.when_empty", "`write` (the default: write the empty collection) or `delete` (DELETE `parent.path` instead, S3 CORS)");
+    const contentType = contentTypeParam(o.content_type, "parent.content_type");
+    const writeListPath = o.write_list_path === undefined ? undefined : pointerParam(o.write_list_path, "parent.write_list_path", "");
+    return {
+        path,
+        readPath,
+        readMethod: methodParam(o.read_method, "parent.read_method", ["GET", "POST"], "GET"),
+        method: methodParam(o.method, "parent.method", ["PATCH", "PUT", "POST"], "PATCH"),
+        send: parseSend(o.send),
+        itemPath: pointerParam(o.item_path, "parent.item_path", ""),
+        ifMissing,
+        whenEmpty,
+        ...(contentType ? { contentType } : {}),
+        ...(writeListPath !== undefined ? { writeListPath } : {}),
+    };
+}
+/** One of `allowed` (the first when absent); PARAM_INVALID saying what each means otherwise. */
+function oneOf(v, allowed, param, meaning) {
+    if (v === undefined)
+        return allowed[0];
+    if (typeof v === "string" && allowed.includes(v))
+        return v;
+    throw fail(`\`${param}\` must be ${meaning}`, param);
+}
+function parseSend(v) {
+    if (v === undefined || v === "field" || v === "parent" || v === "collection")
+        return v ?? "field";
+    if (Array.isArray(v) && v.length > 0 && v.every((f) => typeof f === "string" && f !== ""))
+        return v;
+    throw fail("`parent.send` must be `field` (send only the list; a map entry as a merge patch), `collection` (send only the list, a map whole), `parent` (send the whole object back) or a list of the object's fields to send back with it", "parent.send");
+}
+function scalarItem(v, what) {
+    if (isObject(v) || Array.isArray(v))
+        throw fail(`\`item\` must be ${what}`, "item");
+    if (isKeep(v))
+        throw fail("`item` cannot be `{ keep: true }`: it is the item's identity", "item");
+    return v;
+}
+function parseArrayItem(v, keyField) {
+    if (!isObject(v)) {
+        if (keyField !== undefined)
+            throw fail("`key_field` applies only when `item` is a map", "key_field");
+        return { item: scalarItem(v, "a single value or a map, not a list") };
+    }
+    const field = fieldParam(keyField, "key_field");
+    const key = at(v, fieldTokens(field));
+    if (key === undefined || isObject(key) || Array.isArray(key) || isKeep(key))
+        throw fail(`\`item\` must set \`${field}\` (its \`key_field\`) to a value`, `item.${field}`);
+    return { item: v, keyField: field };
+}
+function parseShape(v) {
+    if (v === undefined || v === "array" || v === "delimited" || v === "map")
+        return v ?? "array";
+    throw fail("`shape` must be `array` (the default), `delimited` or `map`", "shape");
+}
+/** The shape-specific params: what identifies the item, and what else the shape takes. */
+function parseShaped(params, shape) {
+    if (params.item === undefined || params.item === null)
+        throw fail("`item` is required: the value to keep in the list (for `shape: map`, the entry's name)", "item");
+    const only = (name, allowed) => {
+        if (!allowed && params[name] !== undefined)
+            throw fail(`\`${name}\` does not apply to \`shape: ${shape}\``, name);
+    };
+    only("key_field", shape === "array");
+    only("value", shape === "map");
+    only("separator", shape === "delimited");
+    if (shape === "array")
+        return { separator: ",", ...parseArrayItem(params.item, params.key_field) };
+    const sep = params.separator ?? ",";
+    if (typeof sep !== "string" || sep.trim() === "")
+        throw fail("`separator` must be a non-blank string, e.g. \",\"", "separator");
+    if (shape === "delimited")
+        return { separator: sep, item: scalarItem(params.item, "a single string for `shape: delimited`") };
+    if (params.value === undefined)
+        throw fail("`value` is required for `shape: map`: the entry's value (`null` is not a value: it deletes)", "value");
+    return { separator: sep, item: scalarItem(params.item, "the entry's name for `shape: map`"), value: params.value };
+}
+/** `http.list_item` params, checked; PARAM_INVALID naming the field otherwise. */
+export function parseListItem(line) {
+    const params = expandRecipe(line, "list_item");
+    noUnknownParams(params, LIST_PARAMS, "list_item");
+    const api = apiParam(params);
+    const vars = optionalObject(params.vars, "vars") ?? {};
+    const shape = parseShape(params.shape);
+    const listPath = pointerParam(params.list_path, "list_path", "");
+    if (listPath === "" && shape !== "map")
+        throw fail("`list_path` is required: the JSON pointer to the list in the parent, e.g. /allowed_origins", "list_path");
+    const destroy = parseDestroy(params.destroy);
+    return { api, vars, ...parseCredential(params, destroy), parent: parseParent(params.parent, vars), listPath, shape, ...parseShaped(params, shape), destroy };
+}
+//# sourceMappingURL=http-adapter-spec.js.map