@greatwait/contracts 0.1.0-alpha.1

package/generated/v1/first-value-journey.json

@@ -0,0 +1,436 @@
+{
+  "contractVersion": "2026-08-22",
+  "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"
+    }
+  ],
+  "steps": [
+    {
+      "capture": [],
+      "key": "check-service",
+      "method": "GET",
+      "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",
+      "path": "/__greatwait/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"
+        }
+      ],
+      "problems": ["rate_limited", "service_unavailable"],
+      "scopes": [],
+      "successStatus": 200,
+      "title": "Check which service and environment you reached",
+      "variables": []
+    },
+    {
+      "capture": [],
+      "key": "check-credential",
+      "method": "GET",
+      "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",
+      "path": "/v1/schedules",
+      "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"
+        }
+      ],
+      "problems": [
+        "authentication_required",
+        "credential_expired",
+        "credential_revoked",
+        "invalid_request",
+        "rate_limited",
+        "scope_missing",
+        "service_unavailable"
+      ],
+      "scopes": ["schedules:read"],
+      "successStatus": 200,
+      "title": "Check the credential",
+      "variables": []
+    },
+    {
+      "capture": [
+        {
+          "from": "id",
+          "kind": "body",
+          "secret": false,
+          "variable": "GREATWAIT_ENDPOINTID"
+        },
+        {
+          "from": "secret",
+          "kind": "body",
+          "secret": true,
+          "variable": "GREATWAIT_ENDPOINT_SECRET"
+        }
+      ],
+      "key": "create-destination",
+      "method": "POST",
+      "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",
+      "path": "/v1/endpoints",
+      "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}}"
+      },
+      "problems": [
+        "authentication_required",
+        "credential_expired",
+        "credential_revoked",
+        "invalid_request",
+        "plan_limit_reached",
+        "rate_limited",
+        "scope_missing",
+        "service_unavailable"
+      ],
+      "scopes": ["endpoints:write"],
+      "successStatus": 201,
+      "title": "Create the destination",
+      "variables": ["GREATWAIT_RECEIVER_URL"]
+    },
+    {
+      "capture": [
+        {
+          "from": "schedule.id",
+          "kind": "body",
+          "secret": false,
+          "variable": "GREATWAIT_SCHEDULEID"
+        },
+        {
+          "from": "occurrence.id",
+          "kind": "body",
+          "secret": false,
+          "variable": "GREATWAIT_OCCURRENCEID"
+        }
+      ],
+      "key": "create-one-shot",
+      "method": "POST",
+      "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",
+      "path": "/v1/schedules",
+      "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}}"
+      },
+      "problems": [
+        "authentication_required",
+        "credential_expired",
+        "credential_revoked",
+        "endpoint_unverified",
+        "idempotency_key_reused",
+        "invalid_request",
+        "not_found",
+        "plan_limit_reached",
+        "rate_limited",
+        "scope_missing",
+        "service_unavailable"
+      ],
+      "scopes": ["schedules:write"],
+      "successStatus": 201,
+      "title": "Create the one-shot",
+      "variables": ["GREATWAIT_ENDPOINTID", "GREATWAIT_IDEMPOTENCY_KEY"]
+    },
+    {
+      "capture": [
+        {
+          "from": "Idempotency-Replayed",
+          "kind": "header",
+          "secret": false,
+          "variable": "GREATWAIT_REPLAYED"
+        },
+        {
+          "from": "schedule.id",
+          "kind": "body",
+          "secret": false,
+          "variable": "GREATWAIT_REPLAYED_SCHEDULEID"
+        }
+      ],
+      "key": "replay-one-shot",
+      "method": "POST",
+      "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",
+      "path": "/v1/schedules",
+      "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}}"
+      },
+      "problems": [
+        "authentication_required",
+        "credential_expired",
+        "credential_revoked",
+        "endpoint_unverified",
+        "idempotency_key_reused",
+        "invalid_request",
+        "not_found",
+        "plan_limit_reached",
+        "rate_limited",
+        "scope_missing",
+        "service_unavailable"
+      ],
+      "scopes": ["schedules:write"],
+      "successStatus": 201,
+      "title": "Retry it safely",
+      "variables": ["GREATWAIT_ENDPOINTID", "GREATWAIT_IDEMPOTENCY_KEY"]
+    },
+    {
+      "capture": [],
+      "key": "read-schedule",
+      "method": "GET",
+      "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",
+      "path": "/v1/schedules/{scheduleId}",
+      "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"
+        }
+      ],
+      "problems": [
+        "authentication_required",
+        "credential_expired",
+        "credential_revoked",
+        "invalid_request",
+        "not_found",
+        "rate_limited",
+        "scope_missing",
+        "service_unavailable"
+      ],
+      "scopes": ["schedules:read"],
+      "successStatus": 200,
+      "title": "Read the schedule back",
+      "variables": ["GREATWAIT_SCHEDULEID"]
+    },
+    {
+      "capture": [],
+      "key": "await-occurrence",
+      "method": "GET",
+      "observe": "The occurrence reaching `succeeded`. `terminal_failed` is also a settled answer, and the attempt in the next step says why.",
+      "operationId": "occurrences.read",
+      "path": "/v1/schedules/{scheduleId}/occurrences/{occurrenceId}",
+      "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"
+        }
+      ],
+      "problems": [
+        "authentication_required",
+        "credential_expired",
+        "credential_revoked",
+        "invalid_request",
+        "not_found",
+        "rate_limited",
+        "scope_missing",
+        "service_unavailable"
+      ],
+      "scopes": ["occurrences:read"],
+      "successStatus": 200,
+      "title": "Wait for the occurrence to settle",
+      "variables": ["GREATWAIT_SCHEDULEID", "GREATWAIT_OCCURRENCEID"]
+    },
+    {
+      "capture": [],
+      "key": "read-attempt",
+      "method": "GET",
+      "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",
+      "path": "/v1/schedules/{scheduleId}/occurrences/{occurrenceId}/attempts",
+      "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"
+        }
+      ],
+      "problems": [
+        "authentication_required",
+        "credential_expired",
+        "credential_revoked",
+        "invalid_request",
+        "not_found",
+        "rate_limited",
+        "scope_missing",
+        "service_unavailable"
+      ],
+      "scopes": ["occurrences:read"],
+      "successStatus": 200,
+      "title": "Read the delivery attempt",
+      "variables": ["GREATWAIT_SCHEDULEID", "GREATWAIT_OCCURRENCEID"]
+    },
+    {
+      "capture": [],
+      "key": "clean-up",
+      "method": "DELETE",
+      "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",
+      "path": "/v1/endpoints/{endpointId}",
+      "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"
+        }
+      ],
+      "problems": [
+        "authentication_required",
+        "credential_expired",
+        "credential_revoked",
+        "invalid_request",
+        "not_found",
+        "rate_limited",
+        "scope_missing",
+        "service_unavailable"
+      ],
+      "scopes": ["endpoints:write"],
+      "successStatus": 200,
+      "title": "Clean up",
+      "variables": ["GREATWAIT_ENDPOINTID"]
+    }
+  ],
+  "tools": [
+    {
+      "name": "curl",
+      "version": "8.3.0"
+    },
+    {
+      "name": "jq",
+      "version": "1.6"
+    }
+  ],
+  "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"
+    },
+    {
+      "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"
+    }
+  ]
+}