@greatwait/contracts 0.1.0-alpha.1

package/dist/first-value-journey.js

@@ -0,0 +1,466 @@
+import { z } from "zod";
+/**
+ * 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 const JOURNEY_CONDITIONS = [
+    "attempt-failed",
+    "no-response",
+    "not-settled",
+    "receiver-unreachable",
+    "unexpected-answer",
+];
+const identifier = z
+    .string()
+    .min(1)
+    .regex(/^[a-z][a-z0-9-]*$/u, "must be lower-case kebab-case");
+const sentence = z.string().min(12);
+/**
+ * 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 const journeyVariableSchema = z.object({
+    defaultExpression: z
+        .object({ javascript: z.string().min(1), shell: z.string().min(1) })
+        .optional(),
+    detail: sentence,
+    name: z
+        .string()
+        .regex(/^GREATWAIT_[A-Z0-9_]+$/u, "must be a GREATWAIT_ environment name"),
+    placeholder: z
+        .string()
+        .min(1)
+        .refine((value) => !/(?:^|[^A-Za-z0-9_-])(?:pt|ptsk|oat|ort|oac)_(?:live|test)_[A-Za-z0-9_-]{8,}/u.test(value), "must not look like a credential"),
+    secret: z.boolean(),
+    title: z.string().min(3),
+    // Not annotated `z.ZodType<JourneyVariable>`: under
+    // `exactOptionalPropertyTypes` an optional Zod property produces
+    // `T | undefined`, which is not assignable to an optional interface field,
+    // and the annotation would have to be widened until it stopped describing
+    // the interface. `journeyVariable` below is what holds the two together —
+    // it returns the declared type, so a schema that drifted from the interface
+    // fails to compile there instead.
+});
+export const journeyStepSchema = z.object({
+    capture: z
+        .array(z.object({
+        from: z.string().min(1),
+        header: z.boolean().optional(),
+        secret: z.boolean().optional(),
+        variable: z.string().regex(/^GREATWAIT_[A-Z0-9_]+$/u),
+    }))
+        .optional(),
+    expect: z
+        .array(z.object({
+        equals: z.string().min(1),
+        message: sentence,
+        subject: z.string().regex(/^GREATWAIT_[A-Z0-9_]+$/u),
+    }))
+        .optional(),
+    key: identifier,
+    observe: sentence,
+    operationId: z.string().min(1),
+    poll: z
+        .object({
+        describe: sentence,
+        intervalSeconds: z.number().int().positive(),
+        timeoutSeconds: z.number().int().positive(),
+    })
+        .optional(),
+    purpose: sentence,
+    query: z.record(z.string(), z.string()).optional(),
+    recovery: z
+        .array(z.object({ nextMove: sentence, when: z.string().min(1) }))
+        .min(1, "every step names at least one next move"),
+    request: z.unknown().optional(),
+    requestHeaders: z.record(z.string(), z.string()).optional(),
+    title: z.string().min(3),
+});
+/**
+ * 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 const MINIMUM_CURL_VERSION = "8.3.0";
+/** The tools the shell rendering of the journey needs on the reader's PATH. */
+export const CURL_JOURNEY_TOOLS = [
+    { name: "curl", version: MINIMUM_CURL_VERSION },
+    { name: "jq", version: "1.6" },
+];
+export const FIRST_VALUE_PREREQUISITES = [
+    {
+        action: "Accept your Greatwait invitation, sign in, and create a project in the dashboard.",
+        because: "projects.create accepts only a signed-in member, so a project is created by a person rather than by an API credential.",
+        id: "project",
+        title: "A project",
+    },
+    {
+        action: "In that project, create an API credential and copy the secret it shows once.",
+        because: "credentials.create accepts only a signed-in member: a credential that could mint another credential would make revoking one meaningless.",
+        id: "credential",
+        title: "An API credential",
+    },
+    {
+        action: "Have an HTTPS URL of your own that answers POST with a 2xx status, and can be reached from the public internet.",
+        because: "Greatwait delivers your callback to an address you control. It does not offer a shared receiver to try, and it will not send your payload to a third-party inspection service on your behalf.",
+        id: "receiver",
+        title: "An HTTPS receiver you control",
+    },
+];
+export const FIRST_VALUE_VARIABLES = [
+    {
+        detail: "The API origin for the environment you are working against, with no trailing slash.",
+        name: "GREATWAIT_API_URL",
+        placeholder: "https://api.greatwait.dev",
+        secret: false,
+        title: "API origin",
+    },
+    {
+        detail: "The API credential secret, shown once when you created it. Export it in your shell; do not paste it into a command, a URL, or a file you commit.",
+        name: "GREATWAIT_API_KEY",
+        placeholder: "<the credential secret, shown once at creation>",
+        secret: true,
+        title: "API credential",
+    },
+    {
+        detail: "Your own HTTPS receiver. Every callback in this journey is delivered here and nowhere else.",
+        name: "GREATWAIT_RECEIVER_URL",
+        placeholder: "https://receiver.example.com/greatwait",
+        secret: false,
+        title: "Receiver URL",
+    },
+    {
+        // A fresh key per run, because the same key with the same body is a replay
+        // rather than a new schedule — which is the property step five proves, and
+        // would make a second run of the whole journey return the first run's
+        // schedule and never fire anything.
+        defaultExpression: {
+            javascript: "`first-value-${crypto.randomUUID()}`",
+            // `date` and `$$` rather than `uuidgen`, which is not on every minimal
+            // Linux image and would make the quickstart fail at line four for a
+            // reason that has nothing to do with Greatwait.
+            shell: "first-value-$(date +%s)-$$",
+        },
+        detail: "A value you choose, at least 16 printable ASCII characters, that makes the create call safe to retry. Use a fresh one for each schedule you mean to create; these quickstarts generate one if you do not set it.",
+        name: "GREATWAIT_IDEMPOTENCY_KEY",
+        placeholder: "first-value-0000000000000000",
+        secret: false,
+        title: "Idempotency key",
+    },
+];
+/**
+ * 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 const FIRST_VALUE_STEPS = [
+    {
+        key: "check-service",
+        observe: "The service name and the environment you meant to work in. If the environment is not the one you expect, stop and fix GREATWAIT_API_URL before creating anything.",
+        operationId: "meta.version",
+        purpose: "Confirms the origin you are pointed at is a Greatwait API and says which environment it serves. It needs no credential, so it separates 'wrong URL' from 'wrong key'.",
+        recovery: [
+            {
+                nextMove: "Something answered, but not this service. Check GREATWAIT_API_URL — a 404 here comes from a proxy in front of the API rather than from the API, so it carries no problem document to read.",
+                when: "unexpected-answer",
+            },
+            {
+                nextMove: "The origin did not answer. Check the hostname and that you can reach it from this network before going further.",
+                when: "no-response",
+            },
+        ],
+        title: "Check which service and environment you reached",
+    },
+    {
+        key: "check-credential",
+        observe: "An empty page on a new project, or your existing schedules. Either way the credential is accepted and carries the scopes this journey needs.",
+        operationId: "schedules.list",
+        purpose: "Proves the credential works and is bound to the project you think it is, before you create anything with it. A credential names exactly one project, and this is the cheapest call that says so.",
+        query: { limit: "1" },
+        recovery: [
+            {
+                nextMove: "No credential reached the service. Export GREATWAIT_API_KEY in this shell and try again.",
+                when: "authentication_required",
+            },
+            {
+                nextMove: "The credential was revoked. Create a new one in the dashboard; a revoked credential never comes back.",
+                when: "credential_revoked",
+            },
+            {
+                nextMove: "The credential expired. Rotate it in the dashboard and export the new secret.",
+                when: "credential_expired",
+            },
+            {
+                nextMove: "The credential is missing schedules:read. Create one with the scopes this journey needs rather than widening this one.",
+                when: "scope_missing",
+            },
+        ],
+        title: "Check the credential",
+    },
+    {
+        key: "create-destination",
+        capture: [
+            { from: "id", variable: "GREATWAIT_ENDPOINTID" },
+            { from: "secret", secret: true, variable: "GREATWAIT_ENDPOINT_SECRET" },
+        ],
+        observe: "An endpoint identifier, and a signing secret returned by this call and by no other. Store the secret now: reading the endpoint back later will not show it again.",
+        operationId: "endpoints.create",
+        purpose: "Registers the address every occurrence of this schedule is delivered to, and mints the per-endpoint signing key your receiver verifies callbacks with.",
+        recovery: [
+            {
+                nextMove: "The URL was refused. It must be HTTPS on port 443, carry no credentials or fragment, and resolve to a public address — a localhost or private-range host cannot be reached from the service.",
+                when: "invalid_request",
+            },
+            {
+                nextMove: "This project is at its destination ceiling. Disable a destination you no longer deliver to; disabled ones still count, because they stay readable for audit.",
+                when: "plan_limit_reached",
+            },
+        ],
+        request: { url: "{{GREATWAIT_RECEIVER_URL}}" },
+        title: "Create the destination",
+    },
+    {
+        key: "create-one-shot",
+        capture: [
+            { from: "schedule.id", variable: "GREATWAIT_SCHEDULEID" },
+            { from: "occurrence.id", variable: "GREATWAIT_OCCURRENCEID" },
+        ],
+        observe: "A schedule whose recurrence kind is `at`, and its first occurrence in state `planned` with the instant your delay resolved to.",
+        operationId: "schedules.create",
+        purpose: "Creates the one-shot. The delay is converted to an absolute instant when the request is accepted, so the schedule reads back the same afterwards however it was expressed.",
+        recovery: [
+            {
+                nextMove: "This deployment requires a destination to answer its ownership challenge before anything is delivered there, and yours has not. Answer the challenge with the secret the create call returned, then create the schedule.",
+                when: "endpoint_unverified",
+            },
+            {
+                nextMove: "The endpoint identifier is not one this credential's project can deliver to — it belongs to another project, or it has been disabled. Disabling is terminal, so create a new destination rather than trying to re-enable that one.",
+                when: "not_found",
+            },
+            {
+                nextMove: "The same idempotency key was used for a different request. Use a new key, or send the byte-identical body the key was first used with.",
+                when: "idempotency_key_reused",
+            },
+            {
+                nextMove: "Give exactly one of at, delaySeconds, everySeconds and cron, and make sure the endpoint identifier is one this credential's project owns.",
+                when: "invalid_request",
+            },
+            {
+                nextMove: "This organization is at a plan ceiling — live schedules, distinct partition keys, or payload size. Nothing was created; reduce the payload or archive a schedule and retry.",
+                when: "plan_limit_reached",
+            },
+            {
+                nextMove: "The service could not accept the schedule right now. This is safe to retry with the same idempotency key, which is what the key is for.",
+                when: "service_unavailable",
+            },
+        ],
+        request: {
+            data: { greeting: "first value" },
+            delaySeconds: 30,
+            endpoint: "{{GREATWAIT_ENDPOINTID}}",
+        },
+        requestHeaders: { "Idempotency-Key": "{{GREATWAIT_IDEMPOTENCY_KEY}}" },
+        title: "Create the one-shot",
+    },
+    {
+        key: "replay-one-shot",
+        capture: [
+            {
+                from: "Idempotency-Replayed",
+                header: true,
+                variable: "GREATWAIT_REPLAYED",
+            },
+            { from: "schedule.id", variable: "GREATWAIT_REPLAYED_SCHEDULEID" },
+        ],
+        expect: [
+            {
+                equals: "true",
+                message: "the second create was not reported as a replay, which means it may have created a second schedule — read your schedule listing before creating anything else",
+                subject: "GREATWAIT_REPLAYED",
+            },
+            {
+                equals: "{{GREATWAIT_SCHEDULEID}}",
+                message: "the replay returned a different schedule from the one the first call created",
+                subject: "GREATWAIT_REPLAYED_SCHEDULEID",
+            },
+        ],
+        observe: "The identical schedule identifier and an `Idempotency-Replayed: true` response header. Nothing was created the second time, and no second callback will be delivered.",
+        operationId: "schedules.create",
+        purpose: "Repeats the previous call byte for byte, with the same key. This is the retry a network failure would have made for you, and it is the reason a create is safe to retry at all.",
+        recovery: [
+            {
+                nextMove: "The body differed from the first call. A replay must be byte-identical; a changed body with a used key is a conflict rather than a second write.",
+                when: "idempotency_key_reused",
+            },
+        ],
+        request: {
+            data: { greeting: "first value" },
+            delaySeconds: 30,
+            endpoint: "{{GREATWAIT_ENDPOINTID}}",
+        },
+        requestHeaders: { "Idempotency-Key": "{{GREATWAIT_IDEMPOTENCY_KEY}}" },
+        title: "Retry it safely",
+    },
+    {
+        key: "read-schedule",
+        observe: "The same schedule, with a strong ETag in the response. Send that value back in `If-Match` to make a later pause, replace or cancel conditional on nothing having changed in between.",
+        operationId: "schedules.read",
+        purpose: "Reads the schedule back from the partition that owns it, which is also where the version you need for a conditional write comes from.",
+        recovery: [
+            {
+                nextMove: "A schedule in another organization, project or environment answers not_found rather than a refusal. Check that this credential belongs to the project that created it.",
+                when: "not_found",
+            },
+        ],
+        title: "Read the schedule back",
+    },
+    {
+        key: "await-occurrence",
+        observe: "The occurrence reaching `succeeded`. `terminal_failed` is also a settled answer, and the attempt in the next step says why.",
+        operationId: "occurrences.read",
+        poll: {
+            describe: "Poll until the occurrence reaches a terminal state, or until the deadline passes.",
+            intervalSeconds: 5,
+            timeoutSeconds: 180,
+        },
+        purpose: "Waits for the occurrence to settle. Delivery is at-least-once and a failing attempt is retried, so the state moves through `due` and `dispatching` before it settles.",
+        recovery: [
+            {
+                nextMove: "The occurrence never settled inside the deadline. It is not lost: read it again later, and read its attempts to see how far delivery got.",
+                when: "not-settled",
+            },
+        ],
+        title: "Wait for the occurrence to settle",
+    },
+    {
+        key: "read-attempt",
+        observe: "At least one attempt. `state: succeeded` with the status your receiver returned is first value: the callback was made, your receiver answered, and the outcome is recorded.",
+        operationId: "attempts.list",
+        purpose: "Reads the immutable delivery history. This is the point the journey exists for — the customer-readable outcome of a real call to their own address.",
+        recovery: [
+            {
+                nextMove: "The attempt failed. Read `diagnostic` and `remediation`: they name the classified cause and the next action, and `failureSnippet` carries what your receiver said.",
+                when: "attempt-failed",
+            },
+            {
+                nextMove: "Nothing reached your receiver. Confirm the URL answers a POST from the public internet, and that it is not behind an allowlist Greatwait is not on.",
+                when: "receiver-unreachable",
+            },
+        ],
+        title: "Read the delivery attempt",
+    },
+    {
+        key: "clean-up",
+        observe: "The endpoint in status `disabled`. Nothing further is delivered to it, and it stays readable so the attempts above keep their context.",
+        operationId: "endpoints.disable",
+        purpose: "Stops delivery to the destination you registered for this walkthrough. Disabling is terminal and deliberate: it leaves the history intact rather than deleting evidence of what happened.",
+        recovery: [
+            {
+                nextMove: "Already gone, or never in this project. Nothing to clean up.",
+                when: "not_found",
+            },
+        ],
+        title: "Clean up",
+    },
+];
+export const FIRST_VALUE_JOURNEY = {
+    prerequisites: FIRST_VALUE_PREREQUISITES,
+    steps: FIRST_VALUE_STEPS,
+    variables: FIRST_VALUE_VARIABLES,
+};
+/** The declared variable of that name, or `undefined`. */
+export function journeyVariable(name) {
+    return FIRST_VALUE_VARIABLES.find((variable) => variable.name === name);
+}
+/** Every `{{VARIABLE}}` reference inside a value, in first-appearance order. */
+export function journeyReferences(value) {
+    const found = [];
+    const walk = (node) => {
+        if (typeof node === "string") {
+            for (const match of node.matchAll(/\{\{([A-Z0-9_]+)\}\}/gu)) {
+                const name = match[1];
+                if (!found.includes(name)) {
+                    found.push(name);
+                }
+            }
+            return;
+        }
+        if (Array.isArray(node)) {
+            for (const entry of node)
+                walk(entry);
+            return;
+        }
+        if (node !== null && typeof node === "object") {
+            for (const entry of Object.values(node))
+                walk(entry);
+        }
+    };
+    walk(value);
+    return found;
+}
+/**
+ * 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 function resolveJourneyReferences(value, resolve) {
+    const substitute = (text) => text.replace(/\{\{([A-Z0-9_]+)\}\}/gu, (_match, name) => {
+        const resolved = resolve(name);
+        if (resolved === undefined) {
+            throw new Error(`journey references undeclared variable ${name}`);
+        }
+        return resolved;
+    });
+    const walk = (node) => {
+        if (typeof node === "string")
+            return substitute(node);
+        if (Array.isArray(node))
+            return node.map(walk);
+        if (node !== null && typeof node === "object") {
+            return Object.fromEntries(Object.entries(node).map(([key, entry]) => [key, walk(entry)]));
+        }
+        return node;
+    };
+    return walk(value);
+}
+/**
+ * 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 function journeyCapturedVariables() {
+    return FIRST_VALUE_STEPS.flatMap((step) => (step.capture ?? []).map((capture) => capture.variable));
+}