@greatwait/contracts 0.1.0-alpha.4 → 0.1.0-alpha.6

package/dist/usage.js

@@ -1,4 +1,5 @@
 import { z } from "./zod.js";
+import { MAX_USAGE_WINDOW_DAYS } from "./configuration-bounds.js";
 import { timestampSchema } from "./time.js";
 /**
  * A legacy operational aggregate of terminal occurrences.
@@ -67,7 +68,7 @@ export const USAGE_BOUNDS = {
      * never older than that. It is a contract ceiling rather than a plan one: a
      * plan may bring it closer and may never push it out.
      */
-    maxWindowDays: 366,
+    maxWindowDays: MAX_USAGE_WINDOW_DAYS,
 };
 /** How a terminal occurrence ended. The four retained terminal states. */
 export const BILLABLE_TERMINAL_STATES = [
@@ -202,26 +203,10 @@ export const usageSchema = z
      */
     freshness: z.object({ kind: z.literal("authoritative") }),
     /**
-     * How much of this deployment's daily attempt allowance has been spent.
-     *
-     * **Because nothing else could say it, and something had to.** The runtime
-     * refuses admission once an organization has made
-     * `dailyAttemptCeiling` attempts in a UTC day, and defers every schedule to
-     * the next day boundary rather than failing them. Nothing lost, nothing
-     * failed — and nothing running either, for up to a day, on a product whose
-     * whole job is to run things. The operator found his own account in that
-     * state during the W4-10 walk and no screen anywhere named it: the runs
-     * read "Delivering", the dashboard had no action waiting, and the only
-     * visible trace was an unremarkable number on the billing panel.
-     *
-     * The disposition, the ceiling and the count all lived inside
-     * `DialerWorker` and `EntitlementPolicy`; neither ever left
-     * `packages/application`, and `days` above counts settled *occurrences*
-     * rather than attempts, so it could not be derived either.
-     *
-     * Absent when this deployment sets no ceiling, which is the honest shape
-     * for "there is no allowance to be near the end of" — a surface must not
-     * render a limit nobody has.
+     * Legacy daily-allowance projection, retained for installed clients and
+     * mixed-version responses. W0-15 retires the daily quota; current authority
+     * readers omit this optional object rather than querying an obsolete count.
+     * Older servers can still explain parked work to compatible dashboards.
      */
     plan: z
         .object({

package/dist/zod-values.d.ts

@@ -1,3 +1,3 @@
 /** The exact Zod constructors used by delivery-runtime contract modules. */
-export { ZodError, ZodIssueCode, array, boolean, discriminatedUnion, enum, int, json, literal, number, object, partialRecord, record, strictObject, string, toJSONSchema, tuple, union, unknown, url, } from "zod";
-export type { RefinementCtx, ZodType, ZodTypeAny, infer } from "zod";
+export { ZodError, ZodIssueCode, array, boolean, discriminatedUnion, enum, int, json, literal, number, never, object, partialRecord, record, strictObject, string, toJSONSchema, tuple, union, unknown, url, } from "zod";
+export type { RefinementCtx, ZodType, ZodTypeAny, infer, input } from "zod";

package/dist/zod-values.js

@@ -1,2 +1,2 @@
 /** The exact Zod constructors used by delivery-runtime contract modules. */
-export { ZodError, ZodIssueCode, array, boolean, discriminatedUnion, enum, int, json, literal, number, object, partialRecord, record, strictObject, string, toJSONSchema, tuple, union, unknown, url, } from "zod";
+export { ZodError, ZodIssueCode, array, boolean, discriminatedUnion, enum, int, json, literal, number, never, object, partialRecord, record, strictObject, string, toJSONSchema, tuple, union, unknown, url, } from "zod";

package/generated/v1/examples/attempts.list.response.json

@@ -5,12 +5,14 @@
       "classifiedAt": "2026-07-28T15:00:00.071Z",
       "delivery": "dlv_01h8xyz9k2m4n6p8r0t2v4w6y8",
       "diagnostic": "http_retryable",
+      "dispatchRecoveries": 0,
       "durationMs": 71,
       "firstAttemptLatenessMs": 0,
       "firstAttemptStartedAt": "2026-07-28T15:00:00.000Z",
       "timingEligibility": "eligible",
       "timingPolicyVersion": "payg-v1",
       "id": "att_01h8xyz9k2m4n6p8r0t2v4w6y8",
+      "localReceiptRecoveries": 0,
       "occurrence": "occ_01h8xyz9k2m4n6p8r0t2v4w6y8",
       "remediation": "review_retry_policy",
       "responseStatus": 503,

package/generated/v1/examples/attempts.read.response.json

@@ -4,12 +4,14 @@
     "classifiedAt": "2026-07-28T15:02:00.000Z",
     "delivery": "dlv_11h8xyz9k2m4n6p8r0t2v4w6y8",
     "diagnostic": "network_ambiguous",
+    "dispatchRecoveries": 2,
     "durationMs": 10000,
     "firstAttemptLatenessMs": 0,
     "firstAttemptStartedAt": "2026-07-28T15:00:00.000Z",
     "timingEligibility": "eligible",
     "timingPolicyVersion": "payg-v1",
     "id": "att_11h8xyz9k2m4n6p8r0t2v4w6y8",
+    "localReceiptRecoveries": 1,
     "occurrence": "occ_01h8xyz9k2m4n6p8r0t2v4w6y8",
     "remediation": "review_before_redelivery",
     "startedAt": "2026-07-28T15:01:50.000Z",

package/generated/v1/examples/billing.fundingconfirm.response.json

@@ -0,0 +1,120 @@
+{
+  "automaticExecutionTopUp": {
+    "ceiling": {
+      "currency": "USD",
+      "microdollars": "50000000",
+      "scale": 6
+    },
+    "currentPeriod": {
+      "end": "2026-10-01T00:00:00.000Z",
+      "pending": {
+        "currency": "USD",
+        "microdollars": "10830000",
+        "scale": 6
+      },
+      "remaining": {
+        "currency": "USD",
+        "microdollars": "29170000",
+        "scale": 6
+      },
+      "settled": {
+        "currency": "USD",
+        "microdollars": "10000000",
+        "scale": 6
+      },
+      "start": "2026-09-01T00:00:00.000Z"
+    },
+    "rule": {
+      "cooldownUntil": null,
+      "desired": {
+        "ceiling": {
+          "currency": "USD",
+          "microdollars": "50000000",
+          "scale": 6
+        },
+        "credit": {
+          "currency": "USD",
+          "microdollars": "10000000",
+          "scale": 6
+        },
+        "triggerBelow": {
+          "currency": "USD",
+          "microdollars": "2000000",
+          "scale": 6
+        }
+      },
+      "effective": {
+        "ceiling": {
+          "currency": "USD",
+          "microdollars": "50000000",
+          "scale": 6
+        },
+        "credit": {
+          "currency": "USD",
+          "microdollars": "10000000",
+          "scale": 6
+        },
+        "triggerBelow": {
+          "currency": "USD",
+          "microdollars": "2000000",
+          "scale": 6
+        }
+      },
+      "state": "ready",
+      "suspension": null
+    },
+    "revision": 3
+  },
+  "credit": {
+    "amountOwed": {
+      "currency": "USD",
+      "microdollars": "0",
+      "scale": 6
+    },
+    "available": {
+      "currency": "USD",
+      "microdollars": "9000000",
+      "scale": 6
+    },
+    "reserved": {
+      "currency": "USD",
+      "microdollars": "10",
+      "scale": 6
+    }
+  },
+  "freshness": {
+    "kind": "authoritative"
+  },
+  "paymentOperations": [
+    {
+      "createdAt": "2026-09-10T12:00:00.000Z",
+      "credit": {
+        "currency": "USD",
+        "microdollars": "10000000",
+        "scale": 6
+      },
+      "gross": {
+        "currency": "USD",
+        "microdollars": "10830000",
+        "scale": 6
+      },
+      "id": "funding-operation-example",
+      "kind": "automatic",
+      "paymentUrl": "https://pay.stripe.com/receipts/acct_example/example",
+      "reason": "payment-required",
+      "state": "pending",
+      "tax": {
+        "currency": "USD",
+        "microdollars": "830000",
+        "scale": 6
+      },
+      "taxStatus": "confirmed",
+      "updatedAt": "2026-09-10T12:00:01.000Z"
+    }
+  ],
+  "subscribedProjectFees": {
+    "currency": "USD",
+    "microdollars": "5000000",
+    "scale": 6
+  }
+}

package/generated/v1/examples/billing.invoicehistory.response.json

@@ -0,0 +1,6 @@
+{
+  "data": [],
+  "freshness": {
+    "kind": "authoritative"
+  }
+}

package/generated/v1/examples/billing.invoices.response.json

@@ -0,0 +1,15 @@
+{
+  "data": [
+    {
+      "id": "in_example_project_charge",
+      "createdAt": "2026-09-01T12:00:00.000Z",
+      "amount": {
+        "currency": "USD",
+        "microdollars": "5000000",
+        "scale": 6
+      },
+      "state": "paid",
+      "receiptUrl": "https://invoice.stripe.com/i/acct_example/example"
+    }
+  ]
+}

package/generated/v1/examples/billing.paymenthistory.response.json

@@ -0,0 +1,6 @@
+{
+  "data": [],
+  "freshness": {
+    "kind": "authoritative"
+  }
+}

package/generated/v1/examples/billing.paymentmethod.response.json

@@ -0,0 +1,16 @@
+{
+  "card": {
+    "brand": "visa",
+    "last4": "4242",
+    "expMonth": 12,
+    "expYear": 2030
+  },
+  "method": {
+    "brand": "visa",
+    "last4": "4242",
+    "expMonth": 12,
+    "expYear": 2030,
+    "type": "card",
+    "label": "Visa ending in 4242"
+  }
+}

package/generated/v1/examples/billing.paymentmethodconfirm.request.json

@@ -0,0 +1,3 @@
+{
+  "checkoutSession": "cs_example_card_setup"
+}

package/generated/v1/examples/billing.paymentmethodconfirm.response.json

@@ -0,0 +1,16 @@
+{
+  "card": {
+    "brand": "visa",
+    "last4": "4242",
+    "expMonth": 12,
+    "expYear": 2030
+  },
+  "method": {
+    "brand": "visa",
+    "last4": "4242",
+    "expMonth": 12,
+    "expYear": 2030,
+    "type": "card",
+    "label": "Visa ending in 4242"
+  }
+}

package/generated/v1/examples/billing.paymentmethodremove.request.json

@@ -0,0 +1,3 @@
+{
+  "confirmed": true
+}

package/generated/v1/examples/billing.paymentmethodremove.response.json

@@ -0,0 +1,4 @@
+{
+  "card": null,
+  "method": null
+}

package/generated/v1/examples/billing.paymentmethodsetup.request.json

@@ -0,0 +1 @@
+{}

package/generated/v1/examples/billing.paymentmethodsetup.response.json

@@ -0,0 +1,3 @@
+{
+  "url": "https://checkout.stripe.com/c/pay/example-card-setup"
+}

package/generated/v1/examples/endpoints.ensure.request.json

@@ -0,0 +1,3 @@
+{
+  "url": "https://hooks.example.com/greatwait"
+}

package/generated/v1/examples/endpoints.ensure.response.json

@@ -0,0 +1,20 @@
+{
+  "createdAt": "2026-08-05T15:00:00.000Z",
+  "environmentKind": "test",
+  "id": "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
+  "name": "https://hooks.example.com/greatwait",
+  "project": "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+  "signingKeys": {
+    "current": "csk_01h8xyz9k2m4n6p8r0t2v4w6y8"
+  },
+  "status": "active",
+  "updatedAt": "2026-08-05T15:00:00.000Z",
+  "url": "https://hooks.example.com/greatwait",
+  "version": 1,
+  "created": true,
+  "signingSecret": {
+    "guidance": "GreatWait signs every callback to this endpoint. The signing secret is never returned here; a signed-in member of the project reveals it on the endpoint's page in the GreatWait dashboard, and your receiver uses it to verify that a callback came from GreatWait.",
+    "returned": false,
+    "revealUrl": "https://app.greatwait.dev/o/org_2example0organization0id/p/proj_01h8xyz9k2m4n6p8r0t2v4w6y8/test/settings/endpoints/ep_01h8xyz9k2m4n6p8r0t2v4w6y8"
+  }
+}

package/generated/v1/examples/invitations.create.request.json

@@ -0,0 +1,5 @@
+{
+  "email": "teammate@example.com",
+  "role": "member",
+  "projects": ["proj_01h8xyz9k2m4n6p8r0t2v4w6y8"]
+}

package/generated/v1/examples/invitations.create.response.json

@@ -0,0 +1,7 @@
+{
+  "id": "inv_0123456789abcdef0123456789",
+  "email": "teammate@example.com",
+  "role": "member",
+  "projects": ["proj_01h8xyz9k2m4n6p8r0t2v4w6y8"],
+  "status": "pending"
+}

package/generated/v1/examples/invitations.list.response.json

@@ -0,0 +1,11 @@
+{
+  "data": [
+    {
+      "id": "inv_0123456789abcdef0123456789",
+      "email": "teammate@example.com",
+      "role": "member",
+      "projects": ["proj_01h8xyz9k2m4n6p8r0t2v4w6y8"],
+      "status": "pending"
+    }
+  ]
+}

package/generated/v1/examples/invitations.resend.request.json

@@ -0,0 +1 @@
+{}

package/generated/v1/examples/invitations.resend.response.json

@@ -0,0 +1,4 @@
+{
+  "completed": true,
+  "id": "inv_0123456789abcdef0123456789"
+}

package/generated/v1/examples/invitations.revoke.request.json

@@ -0,0 +1,3 @@
+{
+  "confirmed": true
+}

package/generated/v1/examples/invitations.revoke.response.json

@@ -0,0 +1,4 @@
+{
+  "completed": true,
+  "id": "inv_0123456789abcdef0123456789"
+}

package/generated/v1/examples/limits.read.response.json

@@ -0,0 +1,16 @@
+{
+  "limits": {
+    "inlinePayloadBytes": 65536,
+    "forecastHorizonSeconds": 90000,
+    "usageWindowDays": 366
+  },
+  "provenance": {
+    "inlinePayloadBytes": "default",
+    "forecastHorizonSeconds": "default",
+    "usageWindowDays": "default"
+  },
+  "revision": {
+    "global": 0,
+    "organization": 0
+  }
+}

package/generated/v1/examples/members.list.response.json

@@ -0,0 +1,13 @@
+{
+  "data": [
+    {
+      "id": "mem_0123456789abcdef0123456789",
+      "email": "teammate@example.com",
+      "name": "Teammate",
+      "role": "member",
+      "projects": ["proj_01h8xyz9k2m4n6p8r0t2v4w6y8"],
+      "allProjects": false,
+      "self": false
+    }
+  ]
+}

package/generated/v1/examples/members.remove.request.json

@@ -0,0 +1,3 @@
+{
+  "confirmed": true
+}

package/generated/v1/examples/members.remove.response.json

@@ -0,0 +1,4 @@
+{
+  "completed": true,
+  "id": "mem_0123456789abcdef0123456789"
+}

package/generated/v1/examples/members.role.request.json

@@ -0,0 +1,3 @@
+{
+  "role": "member"
+}

package/generated/v1/examples/members.role.response.json

@@ -0,0 +1,4 @@
+{
+  "completed": true,
+  "id": "mem_0123456789abcdef0123456789"
+}

package/generated/v1/examples/occurrences.redeliver.response.json

@@ -2,7 +2,9 @@
   "attempt": {
     "attemptNumber": 3,
     "delivery": "dlv_21h8xyz9k2m4n6p8r0t2v4w6y8",
+    "dispatchRecoveries": 0,
     "id": "att_21h8xyz9k2m4n6p8r0t2v4w6y8",
+    "localReceiptRecoveries": 0,
     "occurrence": "occ_01h8xyz9k2m4n6p8r0t2v4w6y8",
     "startedAt": "2026-07-28T15:05:00.000Z",
     "trigger": {

package/generated/v1/examples/projectmembers.add.request.json

@@ -0,0 +1 @@
+{}

package/generated/v1/examples/projectmembers.add.response.json

@@ -0,0 +1,4 @@
+{
+  "completed": true,
+  "id": "mem_0123456789abcdef0123456789"
+}

package/generated/v1/examples/projectmembers.remove.request.json

@@ -0,0 +1,3 @@
+{
+  "confirmed": true
+}

package/generated/v1/examples/projectmembers.remove.response.json

@@ -0,0 +1,4 @@
+{
+  "completed": true,
+  "id": "mem_0123456789abcdef0123456789"
+}

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

@@ -2,20 +2,20 @@
   "contractVersion": "2026-08-22",
   "prerequisites": [
     {
-      "action": "Accept your Greatwait invitation, sign in, and create a project in the dashboard.",
+      "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.",
+      "action": "In that project, create an API credential with endpoints:write, occurrences:read, schedules:read and schedules:write, and copy the secret it shows once. The key picker starts with nothing selected and refuses an empty one, so those four are the boxes to tick.",
       "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.",
+      "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"
     }
@@ -28,7 +28,7 @@
       "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'.",
+      "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.",
@@ -39,7 +39,11 @@
           "when": "no-response"
         }
       ],
-      "problems": ["rate_limited", "service_unavailable"],
+      "problems": [
+        "capability_not_configured",
+        "rate_limited",
+        "service_unavailable"
+      ],
       "scopes": [],
       "successStatus": 200,
       "title": "Check which service and environment you reached",
@@ -76,6 +80,7 @@
       ],
       "problems": [
         "authentication_required",
+        "capability_not_configured",
         "credential_expired",
         "credential_revoked",
         "invalid_request",
@@ -106,7 +111,7 @@
       ],
       "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.",
+      "observe": "An endpoint identifier, and a signing secret. Store it now: this is the only call that returns it, and reading the endpoint back shows a redacted prefix instead. It is not gone if you lose it — a signed-in member can read it again on the endpoint's own page in the dashboard, which is the one caller `endpoints.revealSigningSecret` accepts.",
       "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.",
@@ -118,6 +123,10 @@
         {
           "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"
+        },
+        {
+          "nextMove": "An active destination already delivers to this address in this project — usually one a previous run of this journey created. Reuse that destination, disable it first, or give the new one a name of its own.",
+          "when": "state_conflict"
         }
       ],
       "request": {
@@ -125,6 +134,7 @@
       },
       "problems": [
         "authentication_required",
+        "capability_not_configured",
         "credential_expired",
         "credential_revoked",
         "invalid_request",
@@ -179,7 +189,7 @@
           "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.",
+          "nextMove": "This organization is at a plan ceiling — the payload is larger than its plan carries, or the schedule names a new partition key when the organization's keys are full. Nothing was created; send a smaller payload or reuse a partition key that is already live, and retry.",
           "when": "plan_limit_reached"
         },
         {
@@ -199,6 +209,7 @@
       },
       "problems": [
         "authentication_required",
+        "capability_not_configured",
         "credential_expired",
         "credential_revoked",
         "idempotency_key_reused",
@@ -255,6 +266,7 @@
       },
       "problems": [
         "authentication_required",
+        "capability_not_configured",
         "credential_expired",
         "credential_revoked",
         "idempotency_key_reused",
@@ -288,6 +300,7 @@
       ],
       "problems": [
         "authentication_required",
+        "capability_not_configured",
         "credential_expired",
         "credential_revoked",
         "invalid_request",
@@ -323,6 +336,7 @@
       ],
       "problems": [
         "authentication_required",
+        "capability_not_configured",
         "credential_expired",
         "credential_revoked",
         "invalid_request",
@@ -351,12 +365,13 @@
           "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.",
+          "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",
+        "capability_not_configured",
         "credential_expired",
         "credential_revoked",
         "invalid_request",
@@ -387,6 +402,7 @@
       ],
       "problems": [
         "authentication_required",
+        "capability_not_configured",
         "credential_expired",
         "credential_revoked",
         "invalid_request",