@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/spec/tags/query.js

@@ -0,0 +1,113 @@
+/** `x-query`, as `docs/api/tags.md` documents it. */
+import { isQueryEnvelopeRole, QUERY_ENVELOPE_ROLES } from "../conventions/envelope-names.js";
+import { isQueryParamRole, QUERY_PARAM_ROLES } from "../conventions/query-params.js";
+import { parseFilterGrammar } from "../render/filter-parse.js";
+import { parseSortGrammar } from "../render/sort-parse.js";
+import { checkAxis, checkShape, flag, integer, isObject, oneOf, text, textMap, texts, } from "./checks.js";
+const HARVEST = { operationId: text, path: text, typeMap: textMap, typePath: text };
+const harvest = (value) => checkShape(value, HARVEST, ["operationId", "path"]);
+const FIELD_ROW = { field: text };
+const FILTERABLE_ROW = { field: text, ops: texts, type: text };
+const SORTABLE_ROW = { field: text, nulls: texts, type: text };
+function filterGrammar(value) {
+    if (!isObject(value))
+        return oneOf(value, ["postgrest", "colon", "equality"]);
+    const parsed = parseFilterGrammar(value);
+    return parsed.ok ? null : `is a template the API tester cannot read: ${parsed.error}`;
+}
+function sortGrammar(value) {
+    if (!isObject(value))
+        return oneOf(value, ["dotted", "prefixed", "colon", "spaced"]);
+    const parsed = parseSortGrammar(value);
+    return parsed.ok ? null : `is a template the API tester cannot read: ${parsed.error}`;
+}
+/** A parameter name per role: `{ filter: "filter_by" }`. */
+function params(value) {
+    if (!isObject(value))
+        return "must be an object of role names";
+    for (const [role, name] of Object.entries(value)) {
+        if (!isQueryParamRole(role)) {
+            return `names an unknown role "${role}"; the roles are ${QUERY_PARAM_ROLES.join(", ")}`;
+        }
+        if (text(name) !== null)
+            return `"${role}" must be a parameter name`;
+    }
+    return null;
+}
+/** A response field name per paging fact: `{ nextCursor: "next_before" }`. */
+function envelope(value) {
+    if (!isObject(value))
+        return "must be an object of role names";
+    for (const [role, name] of Object.entries(value)) {
+        if (!isQueryEnvelopeRole(role)) {
+            return `names an unknown role "${role}"; the roles are ${QUERY_ENVELOPE_ROLES.join(", ")}`;
+        }
+        if (text(name) !== null)
+            return `"${role}" must be a field name`;
+    }
+    return null;
+}
+const SORT_BLOCK = {
+    collation: (value) => oneOf(value, ["binary", "case-insensitive", "locale"]),
+    defaultNulls: (value) => oneOf(value, ["first", "last"]),
+    defaultOrder: text,
+    maxKeys: integer,
+    nulls: texts,
+    stableTiebreak: text,
+};
+const RELATION = { fields: texts, name: text };
+function relations(value) {
+    if (!Array.isArray(value))
+        return "must be an array of { name, fields } rows";
+    for (const row of value) {
+        const problem = checkShape(row, RELATION, ["name", "fields"]);
+        if (problem !== null)
+            return `has a row that ${problem}`;
+    }
+    return null;
+}
+const SELECT_BLOCK = {
+    nested: flag,
+    relations,
+    unknown: (value) => oneOf(value, ["reject", "ignore"]),
+};
+const X_QUERY = {
+    aliases: textMap,
+    defaultOrder: text,
+    emptyIn: (value) => oneOf(value, ["reject", "match-none"]),
+    limitOutOfRange: (value) => oneOf(value, ["reject", "clamp"]),
+    filterable: (value) => checkAxis(value, FILTERABLE_ROW),
+    filterableFrom: harvest,
+    grammar: filterGrammar,
+    identityFilter: text,
+    sortGrammar,
+    maxFilterConditions: integer,
+    maxInValues: integer,
+    maxLimit: integer,
+    maxSortKeys: integer,
+    operators: texts,
+    params,
+    envelope,
+    operatorsByType: (value) => isObject(value) && Object.values(value).every((ops) => texts(ops) === null)
+        ? null
+        : "must map type names to arrays of operators",
+    searchable: (value) => checkAxis(value, FIELD_ROW),
+    searchableFrom: harvest,
+    searchCase: (value) => oneOf(value, ["sensitive", "insensitive"]),
+    searchEmpty: (value) => oneOf(value, ["ignore", "match-all", "reject"]),
+    searchModes: texts,
+    selectable: (value) => checkAxis(value, FIELD_ROW),
+    selectableFrom: harvest,
+    select: (value) => checkShape(value, SELECT_BLOCK),
+    selectNested: flag,
+    selectUnknown: (value) => oneOf(value, ["reject", "ignore"]),
+    sort: (value) => checkShape(value, SORT_BLOCK),
+    sortable: (value) => checkAxis(value, SORTABLE_ROW),
+    sortableFrom: harvest,
+    sortCollation: (value) => oneOf(value, ["binary", "case-insensitive", "locale"]),
+    sortDefaultNulls: (value) => oneOf(value, ["first", "last"]),
+    sortNulls: texts,
+    stableTiebreak: text,
+};
+export const xQuery = (value) => checkShape(value, X_QUERY);
+//# sourceMappingURL=query.js.map

package/dist/api/spec/tags/validate.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Every the API tester tag, checked against its shape.
+ *
+ * Readers stay defensive — a tag they cannot use is ignored — but ignoring it silently meant a
+ * typo read as an absence: `x-destructive: yes` was simply not destructive. A tag that is present
+ * and malformed is a gap naming the tag and what is wrong with it, so `doctor` shows it.
+ */
+import type { GapCollector } from "../extensions/gaps.ts";
+import type { OperationObject } from "../types.ts";
+/** Records a gap for every the API tester tag on `op` (and its parameters) that is present but malformed. */
+export declare function validateTags(op: OperationObject, operationId: string, gaps: GapCollector): void;
+//# sourceMappingURL=validate.d.ts.map

package/dist/api/spec/tags/validate.js

@@ -0,0 +1,117 @@
+/**
+ * Every the API tester tag, checked against its shape.
+ *
+ * Readers stay defensive — a tag they cannot use is ignored — but ignoring it silently meant a
+ * typo read as an absence: `x-destructive: yes` was simply not destructive. A tag that is present
+ * and malformed is a gap naming the tag and what is wrong with it, so `doctor` shows it.
+ */
+import { rowsOf } from "../collection/shape.js";
+import { readBypass, readStaleness } from "../extensions/consistency.js";
+import { ENTITY_ACTIONS } from "../extensions/entity.js";
+import { checkShape, flag, oneOf, positive, route, text, textMap, texts, } from "./checks.js";
+import { xQuery } from "./query.js";
+const CONSISTENCY = {
+    bypass: (value) => (readBypass(value) === null ? 'must be a header like "x-fresh: 1"' : null),
+    staleness: (value) => (readStaleness(value) === null ? 'must be whole seconds like "30s"' : null),
+};
+const ASYNC = {
+    idFrom: text,
+    poll: text,
+    pollIntervalMs: positive,
+    successWhen: text,
+    timeoutMs: positive,
+    until: text,
+};
+/* A record's path is any path the API tester reads; `[*]` fans out over a list's rows, so it may stand only
+ * where rows are: right after a top-level key (`$.hits[*].document`). */
+const recordPath = (value) => {
+    const problem = text(value);
+    if (problem !== null || !value.includes("[*]") || rowsOf(value) !== null)
+        return problem;
+    return 'may hold [*] only right after a top-level key, as in "$.hits[*].document"';
+};
+const ENTITY = {
+    action: (value) => oneOf(value, ENTITY_ACTIONS),
+    createdIdFrom: text,
+    identity: text,
+    name: text,
+    recordPath,
+};
+const INVITE = {
+    accept: text,
+    acceptFrom: (value) => oneOf(value, ["link"]),
+    credentialFrom: text,
+    grantPointer: text,
+    granteeField: text,
+    grants: text,
+    invite: text,
+    revoke: text,
+    tokenFrom: (value) => oneOf(value, ["response", "outOfBand"]),
+    tokenKind: text,
+    tokenPointer: text,
+};
+const BIND = { body: textMap, path: textMap, query: textMap };
+const RATE_LIMIT = { category: text, rps: positive };
+const WAIT = {
+    operationId: text,
+    pollIntervalMs: positive,
+    timeoutMs: positive,
+    until: text,
+};
+function entity(value) {
+    const problem = checkShape(value, ENTITY);
+    if (problem !== null)
+        return problem;
+    /* Where the answer keeps the record or its id may be declared alone; naming the entity
+     * still takes both its name and the operation's action. */
+    const tag = value;
+    const located = tag.createdIdFrom !== undefined || tag.recordPath !== undefined;
+    if (tag.name === undefined && (tag.action !== undefined || !located))
+        return 'needs "name"';
+    if (tag.action === undefined && (tag.name !== undefined || !located))
+        return 'needs "action"';
+    return null;
+}
+/* In the order their gaps are reported. */
+const OPERATION_TAGS = {
+    "x-before": text,
+    "x-bind": (value) => checkShape(value, BIND),
+    "x-async": (value) => checkShape(value, ASYNC, ["poll"]),
+    "x-cleanup": route,
+    "x-consistency": (value) => checkShape(value, CONSISTENCY),
+    "x-cost": (value) => oneOf(value, ["low", "medium", "high"]),
+    "x-destructive": flag,
+    "x-entity": entity,
+    "x-feature-gate": text,
+    "x-fresh-principal": flag,
+    "x-generated": texts,
+    "x-idempotent": flag,
+    "x-immutable": texts,
+    "x-invalidate": (value) => Array.isArray(value) && value.every((item) => route(item) === null)
+        ? null
+        : 'must be an array of routes like "GET /path"',
+    "x-invite": (value) => checkShape(value, INVITE, ["invite", "accept", "revoke"]),
+    "x-query": xQuery,
+    "x-rate-limit": (value) => checkShape(value, RATE_LIMIT, ["category"]),
+    "x-soft-delete": text,
+    "x-tenant": (value) => value === false || (typeof value === "string" && value !== "") ? null : "must be a path parameter name or false",
+    "x-wait": (value) => checkShape(value, WAIT, ["operationId"]),
+};
+/** Records a gap for every the API tester tag on `op` (and its parameters) that is present but malformed. */
+export function validateTags(op, operationId, gaps) {
+    const record = op;
+    for (const [tag, check] of Object.entries(OPERATION_TAGS)) {
+        if (record[tag] === undefined)
+            continue;
+        const problem = check(record[tag]);
+        if (problem !== null)
+            gaps.record(operationId, tag, `${tag} ${problem}; the API tester cannot use it`);
+    }
+    for (const parameter of (op.parameters ?? [])) {
+        const root = parameter["x-root"];
+        if (root !== undefined && typeof root !== "boolean") {
+            gaps.record(operationId, "x-root", `x-root on "${parameter.name}" must be true or false; the API tester cannot use it`);
+        }
+    }
+}
+//# sourceMappingURL=validate.js.map

package/dist/api/spec/types.d.ts

@@ -0,0 +1,120 @@
+/** Minimal structural view of an OpenAPI 3.x document — only what the API tester reads. */
+import type { HttpMethod } from "./methods.ts";
+export type { HttpMethod } from "./methods.ts";
+/**
+ * A JSON Schema node as a spec states it: the keywords the API tester reads, each still untrusted and checked
+ * where it is read. Extensions (`x-*`) and keywords the API tester ignores sit behind the index signature.
+ */
+export interface JsonSchema {
+    $ref?: unknown;
+    $id?: unknown;
+    $schema?: unknown;
+    $anchor?: unknown;
+    $comment?: unknown;
+    $defs?: unknown;
+    definitions?: unknown;
+    type?: unknown;
+    enum?: unknown;
+    const?: unknown;
+    format?: unknown;
+    pattern?: unknown;
+    minLength?: unknown;
+    maxLength?: unknown;
+    minimum?: unknown;
+    maximum?: unknown;
+    exclusiveMinimum?: unknown;
+    exclusiveMaximum?: unknown;
+    multipleOf?: unknown;
+    properties?: unknown;
+    required?: unknown;
+    additionalProperties?: unknown;
+    patternProperties?: unknown;
+    propertyNames?: unknown;
+    unevaluatedProperties?: unknown;
+    dependentSchemas?: unknown;
+    items?: unknown;
+    prefixItems?: unknown;
+    additionalItems?: unknown;
+    unevaluatedItems?: unknown;
+    contains?: unknown;
+    minItems?: unknown;
+    maxItems?: unknown;
+    uniqueItems?: unknown;
+    allOf?: unknown;
+    anyOf?: unknown;
+    oneOf?: unknown;
+    not?: unknown;
+    if?: unknown;
+    then?: unknown;
+    else?: unknown;
+    title?: unknown;
+    description?: unknown;
+    default?: unknown;
+    examples?: unknown;
+    deprecated?: unknown;
+    readOnly?: unknown;
+    writeOnly?: unknown;
+    contentEncoding?: unknown;
+    contentMediaType?: unknown;
+    nullable?: unknown;
+    example?: unknown;
+    discriminator?: unknown;
+    xml?: unknown;
+    externalDocs?: unknown;
+    filename?: unknown;
+    [extension: string]: unknown;
+}
+export interface ParameterObject {
+    name: string;
+    in: "path" | "query" | "header" | "cookie";
+    required?: boolean;
+    schema?: JsonSchema;
+    description?: string;
+    [k: string]: unknown;
+}
+export interface MediaTypeObject {
+    schema?: JsonSchema;
+    encoding?: Record<string, {
+        contentType?: string;
+    }>;
+}
+export interface ResponseObject {
+    description?: string;
+    content?: Record<string, MediaTypeObject>;
+}
+export interface OperationObject {
+    operationId?: string;
+    summary?: string;
+    tags?: string[];
+    parameters?: ParameterObject[];
+    requestBody?: {
+        required?: boolean;
+        content?: Record<string, MediaTypeObject>;
+    };
+    responses?: Record<string, ResponseObject>;
+    security?: Array<Record<string, string[]>>;
+    [k: `x-${string}`]: unknown;
+}
+export type PathItemObject = Record<string, OperationObject | unknown>;
+export interface OpenApiDocument {
+    openapi?: string;
+    info?: Record<string, unknown>;
+    servers?: Array<{
+        url: string;
+    }>;
+    paths?: Record<string, PathItemObject>;
+    components?: {
+        schemas?: Record<string, JsonSchema>;
+        securitySchemes?: Record<string, unknown>;
+    };
+    security?: Array<Record<string, string[]>>;
+    [k: `x-${string}`]: unknown;
+}
+/** An operation lifted out of the document with its location attached. */
+export interface Endpoint {
+    operationId: string;
+    method: HttpMethod;
+    path: string;
+    op: OperationObject;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/api/spec/types.js

@@ -0,0 +1,3 @@
+/** Minimal structural view of an OpenAPI 3.x document — only what the API tester reads. */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/api/steps/external.d.ts

@@ -0,0 +1,31 @@
+import type { ExternalStep } from "../config/types/steps.ts";
+import type { BuiltStep } from "./types.ts";
+/** An external step that still needs the scope name its answer binds to. */
+export interface ExternalDraft {
+    as(name: string): BuiltStep & {
+        toStep(): ExternalStep;
+    };
+}
+/** Something only a person or a browser can do, answered by `hooks.external(name, input)`. */
+export declare function external(name: string, input?: Record<string, unknown>): ExternalDraft;
+/** What answers one external: a resolver over its input and the run's context, plus the caller's metadata. */
+export type ExternalEntry<Ctx, Meta extends object> = Meta & {
+    resolve(input: never, ctx: Ctx): string | null | Promise<string | null>;
+};
+/**
+ * Declares the externals a config answers, one typed entry each, so the scenario side and the hook
+ * side read one source. Curried so `Ctx` and `Meta` are given while the entries are inferred.
+ */
+export declare function defineExternals<Ctx, Meta extends object = object>(): <E extends Record<string, ExternalEntry<Ctx, Meta>>>(entries: E) => E;
+/** Each entry's `kind`, by name, for `config.externals.kinds`; an entry with no string `kind` is left out. */
+export declare function externalKinds(entries: Readonly<Record<string, {
+    kind?: unknown;
+    resolve: unknown;
+}>>): Record<string, string>;
+/** External name → the input its resolver takes (`undefined` for none), for `StepTypes.externals`. */
+export type ExternalInputs<E extends Record<string, {
+    resolve: (...args: never[]) => unknown;
+}>> = {
+    [N in keyof E]: Parameters<E[N]["resolve"]> extends [infer I, ...unknown[]] ? I : undefined;
+};
+//# sourceMappingURL=external.d.ts.map

package/dist/api/steps/external.js

@@ -0,0 +1,17 @@
+/** Something only a person or a browser can do, answered by `hooks.external(name, input)`. */
+export function external(name, input) {
+    const step = (as) => input === undefined ? { as, external: name } : { as, external: name, input };
+    return { as: (as) => ({ toStep: () => step(as) }) };
+}
+/**
+ * Declares the externals a config answers, one typed entry each, so the scenario side and the hook
+ * side read one source. Curried so `Ctx` and `Meta` are given while the entries are inferred.
+ */
+export function defineExternals() {
+    return (entries) => entries;
+}
+/** Each entry's `kind`, by name, for `config.externals.kinds`; an entry with no string `kind` is left out. */
+export function externalKinds(entries) {
+    return Object.fromEntries(Object.entries(entries).flatMap(([name, entry]) => (typeof entry.kind === "string" ? [[name, entry.kind]] : [])));
+}
+//# sourceMappingURL=external.js.map

package/dist/api/steps/index.d.ts

@@ -0,0 +1,9 @@
+export { defineExternals, externalKinds, type ExternalDraft, type ExternalEntry, type ExternalInputs, } from "./external.ts";
+export type { MailDraft, MailStep } from "./out-of-band.ts";
+export type { RequestBuilder } from "./request.ts";
+export { scenario, type ScenarioInit, unchecked } from "./scenario.ts";
+export type { Sender } from "./sender.ts";
+export { type Builders, steps, type StepsOptions } from "./steps.ts";
+export type { BuiltStep, CallInit, Fillable, OpMap, OpShape, Placeholder, RawInit, Refusal, StepItem, StepTypes, Unchecked, } from "./types.ts";
+export { type ScenarioView, stepsOf } from "./view.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/api/steps/index.js

@@ -0,0 +1,5 @@
+export { defineExternals, externalKinds, } from "./external.js";
+export { scenario, unchecked } from "./scenario.js";
+export { steps } from "./steps.js";
+export { stepsOf } from "./view.js";
+//# sourceMappingURL=index.js.map

package/dist/api/steps/out-of-band.d.ts

@@ -0,0 +1,17 @@
+import type { OutOfBandStep } from "../config/types/steps.ts";
+import type { BuiltStep } from "./types.ts";
+/** A wait for a value that never travels over HTTP, bound to the scope as `as`. */
+export declare class MailStep implements BuiltStep {
+    #private;
+    constructor(step: OutOfBandStep);
+    /** The value was sent before this scenario began, so no step here triggered it. */
+    sentEarlier(): MailStep;
+    toStep(): OutOfBandStep;
+}
+/** An out-of-band wait that still needs the scope name its value binds to. */
+export interface MailDraft {
+    as(name: string): MailStep;
+}
+/** Waits for the `kind` of value sent to `address`: a mailed token, a magic link, an OTP. */
+export declare function mail(kind: string, address: string): MailDraft;
+//# sourceMappingURL=out-of-band.d.ts.map

package/dist/api/steps/out-of-band.js

@@ -0,0 +1,19 @@
+/** A wait for a value that never travels over HTTP, bound to the scope as `as`. */
+export class MailStep {
+    #step;
+    constructor(step) {
+        this.#step = step;
+    }
+    /** The value was sent before this scenario began, so no step here triggered it. */
+    sentEarlier() {
+        return new MailStep({ outOfBand: { ...this.#step.outOfBand, sentEarlier: true } });
+    }
+    toStep() {
+        return this.#step;
+    }
+}
+/** Waits for the `kind` of value sent to `address`: a mailed token, a magic link, an OTP. */
+export function mail(kind, address) {
+    return { as: (name) => new MailStep({ outOfBand: { address, as: name, kind } }) };
+}
+//# sourceMappingURL=out-of-band.js.map

package/dist/api/steps/request.d.ts

@@ -0,0 +1,30 @@
+import type { ScenarioAssert, ScenarioRequestStep } from "../config/types/steps.ts";
+import type { BuiltStep } from "./types.ts";
+/**
+ * One request step under construction: an operation call or a raw request, then what to save from
+ * its response and what that response must show. Each call returns a new builder, so a step shared
+ * by two branches of a chain stays as it was.
+ */
+export declare class RequestBuilder<Observed extends string> implements BuiltStep {
+    #private;
+    constructor(step: ScenarioRequestStep, asserts?: readonly ScenarioAssert[]);
+    /** Binds response parts into the scope (`saveAs`), merged with earlier saves. */
+    save(names: Record<string, string>): RequestBuilder<Observed>;
+    /** Binds claims out of the JWT at `token` (`saveClaimsFrom`). */
+    claims(token: string, bind: Record<string, string>): RequestBuilder<Observed>;
+    /** The statuses the response may have (`expect`). */
+    status(...codes: number[]): RequestBuilder<Observed>;
+    /** Re-sends until the asserts pass or `within` runs out. */
+    poll(within: string, everyMs?: number): RequestBuilder<Observed>;
+    /** Sends only this security scheme's credential. */
+    scheme(name: string): RequestBuilder<Observed>;
+    equals(from: string, text: string): RequestBuilder<Observed>;
+    contains(from: string, text: string): RequestBuilder<Observed>;
+    excludes(from: string, text: string): RequestBuilder<Observed>;
+    omits(from: string, text: string): RequestBuilder<Observed>;
+    atLeast(from: string, floor: number): RequestBuilder<Observed>;
+    /** Earlier operations the assert just before this proves; none writes an empty list. */
+    observes(...operationIds: Observed[]): RequestBuilder<Observed>;
+    toStep(): ScenarioRequestStep;
+}
+//# sourceMappingURL=request.d.ts.map

package/dist/api/steps/request.js

@@ -0,0 +1,72 @@
+var _a;
+const OBSERVES_FIRST = "observes() names what an assert proves: call it after equals, contains, excludes, omits or atLeast";
+/**
+ * One request step under construction: an operation call or a raw request, then what to save from
+ * its response and what that response must show. Each call returns a new builder, so a step shared
+ * by two branches of a chain stays as it was.
+ */
+export class RequestBuilder {
+    #step;
+    #asserts;
+    constructor(step, asserts = []) {
+        this.#step = step;
+        this.#asserts = asserts;
+    }
+    /** Binds response parts into the scope (`saveAs`), merged with earlier saves. */
+    save(names) {
+        return this.#with({ saveAs: { ...this.#step.saveAs, ...names } });
+    }
+    /** Binds claims out of the JWT at `token` (`saveClaimsFrom`). */
+    claims(token, bind) {
+        return this.#with({ saveClaimsFrom: { bind, token } });
+    }
+    /** The statuses the response may have (`expect`). */
+    status(...codes) {
+        return this.#with({ expect: codes });
+    }
+    /** Re-sends until the asserts pass or `within` runs out. */
+    poll(within, everyMs) {
+        return this.#with({ poll: everyMs === undefined ? { within } : { everyMs, within } });
+    }
+    /** Sends only this security scheme's credential. */
+    scheme(name) {
+        return this.#with({ scheme: name });
+    }
+    equals(from, text) {
+        return this.#assert({ equals: text, from });
+    }
+    contains(from, text) {
+        return this.#assert({ contains: text, from });
+    }
+    excludes(from, text) {
+        return this.#assert({ excludes: text, from });
+    }
+    omits(from, text) {
+        return this.#assert({ from, omits: text });
+    }
+    atLeast(from, floor) {
+        return this.#assert({ atLeast: floor, from });
+    }
+    /** Earlier operations the assert just before this proves; none writes an empty list. */
+    observes(...operationIds) {
+        const last = this.#asserts.at(-1);
+        if (last === undefined)
+            throw new Error(OBSERVES_FIRST);
+        const observes = [...(last.observes ?? []), ...operationIds];
+        return new _a(this.#step, [...this.#asserts.slice(0, -1), { ...last, observes }]);
+    }
+    toStep() {
+        const [only, ...more] = this.#asserts;
+        if (only === undefined)
+            return this.#step;
+        return { ...this.#step, assert: more.length === 0 ? only : [...this.#asserts] };
+    }
+    #with(part) {
+        return new _a({ ...this.#step, ...part }, this.#asserts);
+    }
+    #assert(assert) {
+        return new _a(this.#step, [...this.#asserts, assert]);
+    }
+}
+_a = RequestBuilder;
+//# sourceMappingURL=request.js.map

package/dist/api/steps/scenario.d.ts

@@ -0,0 +1,18 @@
+import type { Scenario } from "../config/types/steps.ts";
+import type { StepItem, Unchecked } from "./types.ts";
+/** A scenario as written with the builders: `covers` typed over the operations it may grade. */
+export interface ScenarioInit<Covered extends string = string> {
+    id: string;
+    /** The operations this scenario grades, an explicit list: each must be called by a step. */
+    covers: Covered[];
+    /** Config principal whose credential the steps send. Default: the writer (`writer`, else the first principal). */
+    principal?: string;
+    /** The configured origin the whole scenario belongs to. */
+    origin?: string;
+    steps: StepItem[];
+}
+/** The plain the API tester scenario the builders stand for: each builder becomes its step, plain steps stay as they are. */
+export declare function scenario<Covered extends string>(init: ScenarioInit<Covered>): Scenario;
+/** A deliberately invalid value, sent as written: the one way past an operation's body type. */
+export declare function unchecked<V>(value: V): V & Unchecked;
+//# sourceMappingURL=scenario.d.ts.map

package/dist/api/steps/scenario.js

@@ -0,0 +1,18 @@
+const isBuilt = (item) => "toStep" in item && typeof item.toStep === "function";
+/** The plain the API tester scenario the builders stand for: each builder becomes its step, plain steps stay as they are. */
+export function scenario(init) {
+    const { covers, id, origin, principal } = init;
+    const steps = init.steps.map((item) => (isBuilt(item) ? item.toStep() : item));
+    return {
+        covers,
+        id,
+        ...(origin === undefined ? {} : { origin }),
+        ...(principal === undefined ? {} : { principal }),
+        steps,
+    };
+}
+/** A deliberately invalid value, sent as written: the one way past an operation's body type. */
+export function unchecked(value) {
+    return value;
+}
+//# sourceMappingURL=scenario.js.map

package/dist/api/steps/sender.d.ts

@@ -0,0 +1,34 @@
+import { RequestBuilder } from "./request.ts";
+import type { CallInit, ErrorStatus, OpId, OpMap, OriginName, OriginOps, Refusal, RawInit, StepTypes } from "./types.ts";
+/** Who a step goes out as, and where: the keys a sender adds to every step it builds. */
+export interface Identity {
+    anonymous?: true;
+    headers?: Record<string, string>;
+    principal?: string;
+    origin?: string;
+}
+/** The scenario's own principal. */
+export declare const SELF: Identity;
+/** No credential at all. */
+export declare const ANON: Identity;
+/** A session held in the scope, sent with `headers` (which name it as `{name}`) in place of the principal's credential. */
+export declare function sessionIdentity(headers: Record<string, string>): Identity;
+/** Another config principal. */
+export declare function principalIdentity(name: string): Identity;
+/**
+ * Builds the request steps one identity sends. Typed over the operations `M` it may call and the
+ * caller's `T`, so an unknown operation, body field, path parameter or error key fails to compile.
+ */
+export declare class Sender<M extends OpMap, T extends StepTypes> {
+    #private;
+    constructor(identity: Identity);
+    /** Calls an operation the document names. */
+    call<K extends OpId<M>>(operationId: K, init?: CallInit<M[K]>): RequestBuilder<OpId<T["ops"]>>;
+    /** Calls an operation and expects it refused with `status` and the declared error `key`. */
+    refused<K extends OpId<M>, Status extends ErrorStatus<M[K]>>(operationId: K, refusal: Refusal<M[K], Status>): RequestBuilder<OpId<T["ops"]>>;
+    /** Sends a raw request, for a path the document does not describe. */
+    request(method: string, path: string, init?: RawInit): RequestBuilder<OpId<T["ops"]>>;
+    /** This sender, with every step it builds sent to the configured origin `name`. */
+    on<O extends OriginName<T>>(name: O): Sender<OriginOps<T, O>, T>;
+}
+//# sourceMappingURL=sender.d.ts.map