@greatwait/contracts 0.1.0-alpha.1

package/dist/endpoints.js

@@ -0,0 +1,179 @@
+import { z } from "zod";
+import { environmentKindSchema } from "./authority.js";
+import { evaluateCallbackUrl } from "./callback-safety.js";
+import { callbackSigningKeyIdSchema, endpointIdSchema, projectIdSchema, } from "./identifiers.js";
+import { pageSchema } from "./protocol.js";
+import { timestampSchema } from "./time.js";
+/**
+ * Reusable callback endpoints.
+ *
+ * The URL belongs to one verified authority tuple for its whole life. The
+ * public resource deliberately has no organization or environment identifier
+ * a caller can use to widen that tuple: `project` and `environmentKind` are
+ * display metadata, while every lookup is scoped by the verified principal.
+ */
+export const CALLBACK_ENDPOINT_STATUSES = [
+    "pending",
+    "verified",
+    "disabled",
+];
+export const callbackEndpointStatusSchema = z.enum(CALLBACK_ENDPOINT_STATUSES);
+export const CALLBACK_VERIFICATION_FAILURES = [
+    "address_forbidden",
+    "challenge_failed",
+    "connection_failed",
+    "dns_unresolved",
+    "rate_limited",
+    "redirect_refused",
+    "response_too_large",
+    "timed_out",
+    "unexpected_status",
+];
+export const callbackVerificationFailureSchema = z.enum(CALLBACK_VERIFICATION_FAILURES);
+/**
+ * A safety ceiling on retained endpoint records, independent of later
+ * commercial plan limits. Disabled records remain readable for audit and count
+ * toward it; changing that lifetime semantic needs a product decision.
+ */
+export const CALLBACK_ENDPOINT_LIMIT_PER_ENVIRONMENT = 50;
+/** Verification egress is admitted through both buckets before DNS or fetch. */
+export const CALLBACK_VERIFICATION_RATE_LIMITS = {
+    destinationPerMinute: 5,
+    projectPerMinute: 20,
+    windowSeconds: 60,
+};
+/** Total bytes a verification response may return before it is refused. */
+export const CALLBACK_VERIFICATION_RESPONSE_BYTES = 1_024;
+/** Total DNS + connect + response bound for one verification attempt. */
+export const CALLBACK_VERIFICATION_TIMEOUT_MILLISECONDS = 5_000;
+/** Longest period during which a receiver may accept current and next keys. */
+export const CALLBACK_SIGNING_KEY_ROTATION_OVERLAP_SECONDS = 86_400;
+export const callbackSigningKeysSchema = z.object({
+    current: callbackSigningKeyIdSchema,
+    next: z
+        .object({
+        id: callbackSigningKeyIdSchema,
+        overlapEndsAt: timestampSchema,
+    })
+        .optional(),
+});
+/**
+ * A metadata-only endpoint shape. The sealed signing secret has no public
+ * field, so list/get/update/verify/disable cannot accidentally recover it.
+ */
+export const callbackEndpointSchema = z.object({
+    createdAt: timestampSchema,
+    disabledAt: timestampSchema.optional(),
+    environmentKind: environmentKindSchema,
+    id: endpointIdSchema,
+    lastVerificationAttemptAt: timestampSchema.optional(),
+    lastVerificationFailure: callbackVerificationFailureSchema.optional(),
+    project: projectIdSchema,
+    signingKeys: callbackSigningKeysSchema,
+    status: callbackEndpointStatusSchema,
+    updatedAt: timestampSchema,
+    url: z.string().url(),
+    verifiedAt: timestampSchema.optional(),
+    version: z.number().int().positive(),
+});
+export const callbackEndpointPageSchema = pageSchema(callbackEndpointSchema);
+/** The one response that carries the per-endpoint secret. */
+export const callbackEndpointCreatedSchema = callbackEndpointSchema.extend({
+    keyId: callbackSigningKeyIdSchema,
+    secret: z.string().min(1),
+    shownOnce: z.literal(true),
+});
+export const callbackSigningKeyRotationRequestSchema = z.object({
+    overlapSeconds: z
+        .number()
+        .int()
+        .min(0)
+        .max(CALLBACK_SIGNING_KEY_ROTATION_OVERLAP_SECONDS, "must not exceed the maximum endpoint-key overlap")
+        .optional(),
+});
+export const callbackEndpointRotatedSchema = z.object({
+    endpoint: callbackEndpointSchema,
+    keyId: callbackSigningKeyIdSchema,
+    secret: z.string().min(1),
+    shownOnce: z.literal(true),
+});
+function callbackUrlSchema() {
+    return z
+        .string()
+        .url()
+        .max(2_048)
+        .superRefine((value, context) => {
+        const verdict = evaluateCallbackUrl(value);
+        if (!verdict.ok) {
+            context.addIssue({
+                code: "custom",
+                message: verdict.reason,
+            });
+        }
+    });
+}
+export const callbackEndpointRequestSchema = z.object({
+    url: callbackUrlSchema(),
+});
+export const CALLBACK_VERIFICATION_PROTOCOL_VERSION = "2026-08-05";
+export const CALLBACK_VERIFICATION_TYPE = "callback.endpoint.verification";
+/**
+ * Exact verification bytes sent to the receiver. The receiver validates the
+ * request signature and proves possession of the one-time secret by returning
+ * an HMAC of `challenge` in `Callback-Verification-Response`.
+ */
+export const callbackVerificationChallengeSchema = z.object({
+    challenge: z.string().regex(/^cvc_[A-Za-z0-9_-]{43}$/u),
+    endpointId: endpointIdSchema,
+    type: z.literal(CALLBACK_VERIFICATION_TYPE),
+    version: z.literal(CALLBACK_VERIFICATION_PROTOCOL_VERSION),
+});
+export const CALLBACK_VERIFICATION_HEADERS = {
+    challenge: "Callback-Verification-Challenge",
+    requestSignature: "Callback-Verification-Signature",
+    responseSignature: "Callback-Verification-Response",
+};
+/**
+ * Machine-readable receiver contract for endpoint ownership verification.
+ *
+ * This is deliberately separate from W3-02's occurrence-delivery signature:
+ * the request proves control of a receiver before the endpoint may be used,
+ * while a delivery signature authenticates an occurrence body later. The
+ * generator publishes this object beside OpenAPI and the JSON Schema.
+ */
+export const CALLBACK_VERIFICATION_PROTOCOL = {
+    purpose: "Prove that the receiver possesses the one-time endpoint secret before Greatwait marks the endpoint verified.",
+    request: {
+        bodyEncoding: "UTF-8 bytes of the compact JSON object in schema property order: challenge, endpointId, type, version.",
+        contentType: "application/json",
+        method: "POST",
+        redirectPolicy: "manual; every 3xx response is refused",
+        signature: {
+            algorithm: "HMAC-SHA-256",
+            format: "v1=<64 lowercase hexadecimal characters>",
+            header: CALLBACK_VERIFICATION_HEADERS.requestSignature,
+            input: "the exact request body bytes",
+            key: "the one-time endpoint secret returned by REST endpoint creation",
+        },
+    },
+    response: {
+        body: "ignored after enforcing the 1024-byte response limit; return an empty body",
+        proof: {
+            algorithm: "HMAC-SHA-256",
+            format: "v1=<64 lowercase hexadecimal characters>",
+            header: CALLBACK_VERIFICATION_HEADERS.responseSignature,
+            input: "the UTF-8 bytes of the challenge string",
+            key: "the same endpoint secret",
+        },
+        status: "any 2xx status",
+    },
+    testVector: {
+        challenge: "cvc_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
+        endpointId: "ep_00000000000000000000000000",
+        exactBodyBase64: "eyJjaGFsbGVuZ2UiOiJjdmNfQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQSIsImVuZHBvaW50SWQiOiJlcF8wMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMCIsInR5cGUiOiJjYWxsYmFjay5lbmRwb2ludC52ZXJpZmljYXRpb24iLCJ2ZXJzaW9uIjoiMjAyNi0wOC0wNSJ9",
+        requestSignature: "v1=0d24c7fed4d752411b88025a9923627b329e0eb9d53978a6ebcf92c0678c731e",
+        responseSignature: "v1=efc690a23f1870930ff3388313162c0e06406902a7a4d3f9273ffe0abcef86bd",
+        secret: "verification-vector-secret",
+    },
+    version: CALLBACK_VERIFICATION_PROTOCOL_VERSION,
+};

package/dist/events.d.ts

@@ -0,0 +1,62 @@
+import { z } from "zod";
+/**
+ * Product events.
+ *
+ * One envelope for every event the product emits, whether it reaches a customer
+ * or only an internal projection. Delivery is at-least-once everywhere, so
+ * `id` is the deduplication key and consumers must be idempotent on it.
+ *
+ * `occurredAt` is when the thing happened; `recordedAt` is when we learned. A
+ * projection that lags can be reasoned about only if both are present, and
+ * collapsing them is how "why is this event from the future" bugs start.
+ */
+export declare const EVENT_TYPES: readonly ["endpoint.verified", "occurrence.attempt.recorded", "occurrence.due", "occurrence.succeeded", "occurrence.terminal_failed", "schedule.cancelled", "schedule.completed", "schedule.created", "schedule.replaced"];
+export declare const eventTypeSchema: z.ZodEnum<{
+    "endpoint.verified": "endpoint.verified";
+    "occurrence.attempt.recorded": "occurrence.attempt.recorded";
+    "occurrence.due": "occurrence.due";
+    "occurrence.succeeded": "occurrence.succeeded";
+    "occurrence.terminal_failed": "occurrence.terminal_failed";
+    "schedule.cancelled": "schedule.cancelled";
+    "schedule.completed": "schedule.completed";
+    "schedule.created": "schedule.created";
+    "schedule.replaced": "schedule.replaced";
+}>;
+export type EventType = z.infer<typeof eventTypeSchema>;
+export declare function eventEnvelopeSchema<TData extends z.ZodTypeAny>(data: TData): z.ZodObject<{
+    data: TData;
+    id: z.ZodString;
+    occurredAt: z.ZodString;
+    recordedAt: z.ZodString;
+    schemaVersion: z.ZodNumber;
+    type: z.ZodEnum<{
+        "endpoint.verified": "endpoint.verified";
+        "occurrence.attempt.recorded": "occurrence.attempt.recorded";
+        "occurrence.due": "occurrence.due";
+        "occurrence.succeeded": "occurrence.succeeded";
+        "occurrence.terminal_failed": "occurrence.terminal_failed";
+        "schedule.cancelled": "schedule.cancelled";
+        "schedule.completed": "schedule.completed";
+        "schedule.created": "schedule.created";
+        "schedule.replaced": "schedule.replaced";
+    }>;
+}, z.core.$strip>;
+export declare const genericEventSchema: z.ZodObject<{
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    id: z.ZodString;
+    occurredAt: z.ZodString;
+    recordedAt: z.ZodString;
+    schemaVersion: z.ZodNumber;
+    type: z.ZodEnum<{
+        "endpoint.verified": "endpoint.verified";
+        "occurrence.attempt.recorded": "occurrence.attempt.recorded";
+        "occurrence.due": "occurrence.due";
+        "occurrence.succeeded": "occurrence.succeeded";
+        "occurrence.terminal_failed": "occurrence.terminal_failed";
+        "schedule.cancelled": "schedule.cancelled";
+        "schedule.completed": "schedule.completed";
+        "schedule.created": "schedule.created";
+        "schedule.replaced": "schedule.replaced";
+    }>;
+}, z.core.$strip>;
+export type GenericEvent = z.infer<typeof genericEventSchema>;

package/dist/events.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { eventIdSchema } from "./identifiers.js";
+import { timestampSchema } from "./time.js";
+/**
+ * Product events.
+ *
+ * One envelope for every event the product emits, whether it reaches a customer
+ * or only an internal projection. Delivery is at-least-once everywhere, so
+ * `id` is the deduplication key and consumers must be idempotent on it.
+ *
+ * `occurredAt` is when the thing happened; `recordedAt` is when we learned. A
+ * projection that lags can be reasoned about only if both are present, and
+ * collapsing them is how "why is this event from the future" bugs start.
+ */
+export const EVENT_TYPES = [
+    "endpoint.verified",
+    "occurrence.attempt.recorded",
+    "occurrence.due",
+    "occurrence.succeeded",
+    "occurrence.terminal_failed",
+    "schedule.cancelled",
+    "schedule.completed",
+    "schedule.created",
+    "schedule.replaced",
+];
+export const eventTypeSchema = z.enum(EVENT_TYPES);
+export function eventEnvelopeSchema(data) {
+    return z.object({
+        data,
+        id: eventIdSchema,
+        occurredAt: timestampSchema,
+        recordedAt: timestampSchema,
+        /** Bumped only when this event's `data` changes incompatibly. */
+        schemaVersion: z.number().int().positive(),
+        type: eventTypeSchema,
+    });
+}
+export const genericEventSchema = eventEnvelopeSchema(z.record(z.string(), z.unknown()));

package/dist/first-value-journey.d.ts

@@ -0,0 +1,305 @@
+import { z } from "zod";
+import type { ProblemCode } from "./problems.js";
+/**
+ * The one bounded sequence that takes a developer from a credential to an
+ * observed callback.
+ *
+ * **Declared once, here, because W9-03 is not the only story that has to tell
+ * it.** The curl quickstart, the JavaScript quickstart, the website journey
+ * W9-01 owns, the DocsAlot pages W9-04 publishes, and the command-line
+ * ergonomics W10 owns are all the *same* sequence rendered for a different
+ * reader. Written separately they diverge silently — the legacy scheduler's
+ * hand-maintained client and documentation are the worked example, and the
+ * thing that made them wrong was never a typo but a step somebody added in one
+ * place.
+ *
+ * So a step names an operation in `OPERATIONS` and nothing else. The method,
+ * the path, the scopes, the refusals, the request shape and the response shape
+ * come from the registry, and `scripts/contract-projection.ts` renders them.
+ * What lives here is the part that genuinely is not derivable from a single
+ * operation: **what order the calls go in, why each one is there, what a reader
+ * should see, and what to do when they do not see it.**
+ *
+ * The three things it deliberately does *not* contain:
+ *
+ * - **A wire shape.** `request` bodies here are validated against the owning
+ *   operation's `request` schema when artifacts are generated, so a body that
+ *   the service would refuse cannot be published.
+ * - **A credential.** Every value a reader supplies is a declared variable with
+ *   a placeholder, and `journeyVariable` refuses one whose placeholder looks
+ *   like a real credential.
+ * - **A receiver we chose for them.** `GREATWAIT_RECEIVER_URL` is a
+ *   prerequisite the reader brings. See {@link FIRST_VALUE_PREREQUISITES}.
+ */
+/**
+ * Something a reader must already have, that no API call in this journey can
+ * produce for them.
+ *
+ * **This list exists because the alternative is an invented shortcut.** Two of
+ * the three entries name a step that legitimately requires a signed-in human:
+ * a project and an API credential are created through the dashboard, because
+ * `projects.create` and `credentials.create` accept only a session principal.
+ * A quickstart that papered over that would either publish a call nobody can
+ * make or quietly hand out a privileged path. The third is the receiver, and
+ * the reason it is the reader's is recorded in
+ * `docs/projects/w9-invited-alpha-journeys/implementation-guide.md`: until
+ * FXO-1746 delivers an accepted first-party receiver, sending a sample payload
+ * to an arbitrary third party is not something this product does on somebody's
+ * behalf.
+ */
+export interface JourneyPrerequisite {
+    /** What the reader has to do, in one imperative sentence. */
+    readonly action: string;
+    /** Why an API call cannot do it for them. */
+    readonly because: string;
+    readonly id: string;
+    readonly title: string;
+}
+/**
+ * A value the reader supplies, named identically for curl and for JavaScript.
+ *
+ * One derivation for both surfaces, so a reader who exported the shell
+ * variables can see at a glance which `process.env` name is the same value.
+ * Before W9-03 the two disagreed — curl read `$API` and `$TEST_KEY` while the
+ * JavaScript read `GREATWAIT_API_URL` and `GREATWAIT_TEST_KEY` — and one of
+ * those four named a *test* credential in examples published for a product
+ * whose test environment is not offered to customers.
+ */
+export interface JourneyVariable {
+    /**
+     * How a rendering invents a value when the reader supplies none.
+     *
+     * Declared for exactly one variable and deliberately not for the others.
+     * An idempotency key is a value the *caller* chooses and nothing else can
+     * choose for them, so it has to be nameable — but a quickstart that demanded
+     * one before the reader had learned what it was for would be asking them to
+     * make a decision they cannot yet make. The API origin, the credential and
+     * the receiver have no honest default at all: inventing one is how a
+     * quickstart ends up sending somebody's payload somewhere they did not
+     * choose.
+     */
+    readonly defaultExpression?: {
+        readonly javascript: string;
+        readonly shell: string;
+    };
+    /** Why it is needed, and where the reader gets it. */
+    readonly detail: string;
+    readonly name: string;
+    /**
+     * What to show in place of a value.
+     *
+     * Never a credential, and `journeyVariableSchema` refuses one that looks
+     * like it might be: a placeholder is copied into generated pages, and a
+     * generated page is exactly where a real credential must never appear.
+     */
+    readonly placeholder: string;
+    /** Whether the value is a secret, which decides how it is handled and shown. */
+    readonly secret: boolean;
+    readonly title: string;
+}
+/**
+ * One thing that can go wrong at a step, and the next move.
+ *
+ * `when` is a `ProblemCode` when the service refuses, and one of the named
+ * conditions below when the failure has no problem document — a timeout, a
+ * receiver that answered badly, an outcome that never settled. Both kinds
+ * exist because an integrator hits both, and a recovery table that only covers
+ * refusals leaves the reader alone at exactly the point they are stuck.
+ */
+export declare const JOURNEY_CONDITIONS: readonly ["attempt-failed", "no-response", "not-settled", "receiver-unreachable", "unexpected-answer"];
+export type JourneyCondition = (typeof JOURNEY_CONDITIONS)[number];
+export interface JourneyRecovery {
+    /** What the reader does next. Imperative, and specific enough to act on. */
+    readonly nextMove: string;
+    readonly when: JourneyCondition | ProblemCode;
+}
+/**
+ * A value carried from one step's response into a later step's request.
+ *
+ * `from` is a dotted path into the parsed response body, so the same
+ * declaration drives `jq` in the shell rendering and property access in the
+ * JavaScript one. `header` reads a response header instead, which is how the
+ * replay step observes `Idempotency-Replayed`.
+ */
+export interface JourneyCapture {
+    readonly from: string;
+    /** True when `from` names a response header rather than a body path. */
+    readonly header?: boolean;
+    /** Whether the captured value is a secret, and must never be printed. */
+    readonly secret?: boolean;
+    /** The variable it becomes, which a later step may reference. */
+    readonly variable: string;
+}
+/**
+ * Something a step checks about what it captured.
+ *
+ * **Added because a linter noticed the gap the step was written to close.**
+ * The replay step captured `Idempotency-Replayed` and then did nothing with
+ * it, so the published quickstart *demonstrated* idempotency without ever
+ * *checking* it: a service that quietly created a second schedule would have
+ * produced a transcript that read exactly the same, and a reader following the
+ * page would have two schedules and two callbacks.
+ *
+ * `equals` may name another variable with `{{…}}`, which is how the replay
+ * proves it got the same schedule back rather than merely a schedule.
+ */
+export interface JourneyExpectation {
+    /** The value it must have — a literal, or a `{{VARIABLE}}` reference. */
+    readonly equals: string;
+    /** What it means when it does not, in the reader's terms. */
+    readonly message: string;
+    /** The captured variable being checked. */
+    readonly subject: string;
+}
+/** A bounded wait, for the one step whose answer arrives when it arrives. */
+export interface JourneyPoll {
+    /** Human sentence describing the condition, for the generated prose. */
+    readonly describe: string;
+    readonly intervalSeconds: number;
+    readonly timeoutSeconds: number;
+}
+export interface JourneyStep {
+    readonly capture?: readonly JourneyCapture[];
+    /** What this step checks about what it captured. */
+    readonly expect?: readonly JourneyExpectation[];
+    /** Stable machine name for this step, used by every consumer. */
+    readonly key: string;
+    /** The operation this step calls, by registry id. */
+    readonly operationId: string;
+    /** What the reader should see when it worked. */
+    readonly observe: string;
+    readonly poll?: JourneyPoll;
+    /** Why this step is in the journey at all. */
+    readonly purpose: string;
+    /**
+     * Query parameters, as literal strings. Values may carry `{{VARIABLE}}`.
+     */
+    readonly query?: Readonly<Record<string, string>>;
+    readonly recovery: readonly JourneyRecovery[];
+    /**
+     * The request body. String values may carry `{{VARIABLE}}` references, which
+     * are resolved against the declared placeholders before the body is
+     * validated against the operation's own request schema.
+     */
+    readonly request?: unknown;
+    /** Request headers this step sends, with the same `{{VARIABLE}}` support. */
+    readonly requestHeaders?: Readonly<Record<string, string>>;
+    readonly title: string;
+}
+/**
+ * A variable name, and a placeholder that is provably not a credential.
+ *
+ * The three patterns are the product's own credential shapes, taken from
+ * `scripts/secret-patterns.ts` in spirit rather than by import — this package
+ * is the contract and may not depend on a repository script. A generated page
+ * carrying a real one would be a leak that no reviewer reads carefully enough
+ * to catch, so the refusal is here rather than in a convention.
+ */
+export declare const journeyVariableSchema: z.ZodObject<{
+    defaultExpression: z.ZodOptional<z.ZodObject<{
+        javascript: z.ZodString;
+        shell: z.ZodString;
+    }, z.core.$strip>>;
+    detail: z.ZodString;
+    name: z.ZodString;
+    placeholder: z.ZodString;
+    secret: z.ZodBoolean;
+    title: z.ZodString;
+}, z.core.$strip>;
+export declare const journeyStepSchema: z.ZodObject<{
+    capture: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        from: z.ZodString;
+        header: z.ZodOptional<z.ZodBoolean>;
+        secret: z.ZodOptional<z.ZodBoolean>;
+        variable: z.ZodString;
+    }, z.core.$strip>>>;
+    expect: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        equals: z.ZodString;
+        message: z.ZodString;
+        subject: z.ZodString;
+    }, z.core.$strip>>>;
+    key: z.ZodString;
+    observe: z.ZodString;
+    operationId: z.ZodString;
+    poll: z.ZodOptional<z.ZodObject<{
+        describe: z.ZodString;
+        intervalSeconds: z.ZodNumber;
+        timeoutSeconds: z.ZodNumber;
+    }, z.core.$strip>>;
+    purpose: z.ZodString;
+    query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    recovery: z.ZodArray<z.ZodObject<{
+        nextMove: z.ZodString;
+        when: z.ZodString;
+    }, z.core.$strip>>;
+    request: z.ZodOptional<z.ZodUnknown>;
+    requestHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    title: z.ZodString;
+}, z.core.$strip>;
+/**
+ * The lowest curl that runs the generated commands.
+ *
+ * `--variable` and `--expand-header` arrived in curl 8.3.0, and they are what
+ * keeps the credential out of the process arguments: the command line names
+ * `%GREATWAIT_API_KEY`, and curl reads the value out of its own environment.
+ * The ordinary `-H "Authorization: Bearer $GREATWAIT_API_KEY"` spelling puts
+ * the secret in `argv`, where any other user on the machine can read it out of
+ * `ps`.
+ *
+ * Stated as a constant because the requirement is published in three places —
+ * both quickstarts and the journey artifact — and a version number written
+ * three times is a version number that will disagree with itself.
+ */
+export declare const MINIMUM_CURL_VERSION = "8.3.0";
+/** The tools the shell rendering of the journey needs on the reader's PATH. */
+export declare const CURL_JOURNEY_TOOLS: readonly [{
+    readonly name: "curl";
+    readonly version: "8.3.0";
+}, {
+    readonly name: "jq";
+    readonly version: "1.6";
+}];
+export declare const FIRST_VALUE_PREREQUISITES: readonly JourneyPrerequisite[];
+export declare const FIRST_VALUE_VARIABLES: readonly JourneyVariable[];
+/**
+ * The sequence.
+ *
+ * Nine steps, and the shape of them is the acceptance criterion: verify the
+ * context and the credential, create a destination, create an idempotent
+ * one-shot, prove the idempotency, read the schedule back, wait for the
+ * occurrence to settle, read the delivery attempt, and clean up. Creating a
+ * resource is not first value; **step `read-attempt` is**, because it is the
+ * first point at which the customer can read what happened at their own
+ * receiver.
+ *
+ * `delaySeconds` rather than `at`, deliberately. An absolute instant published
+ * in an example is stale the day after it is written, and a reader who pastes
+ * it is refused for a reason that has nothing to do with what they were
+ * learning. A delay is converted to an instant when the request is accepted,
+ * so the schedule reads back afterwards exactly as an `at` schedule would.
+ */
+export declare const FIRST_VALUE_STEPS: readonly JourneyStep[];
+export interface FirstValueJourney {
+    readonly prerequisites: readonly JourneyPrerequisite[];
+    readonly steps: readonly JourneyStep[];
+    readonly variables: readonly JourneyVariable[];
+}
+export declare const FIRST_VALUE_JOURNEY: FirstValueJourney;
+/** The declared variable of that name, or `undefined`. */
+export declare function journeyVariable(name: string): JourneyVariable | undefined;
+/** Every `{{VARIABLE}}` reference inside a value, in first-appearance order. */
+export declare function journeyReferences(value: unknown): readonly string[];
+/**
+ * Replaces every `{{VARIABLE}}` reference using `resolve`.
+ *
+ * A whole-string reference becomes the resolved value; an embedded one is
+ * substituted in place. An unresolved name throws rather than leaving the
+ * braces behind, because a `{{…}}` that reached a published page is a page
+ * that teaches a reader to send a literal brace.
+ */
+export declare function resolveJourneyReferences<T>(value: T, resolve: (name: string) => string | undefined): T;
+/**
+ * The variables a step's own capture list produces, so a consumer can tell a
+ * value the reader supplies from one an earlier call handed them.
+ */
+export declare function journeyCapturedVariables(): readonly string[];