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

package/dist/first-value-journey.js

@@ -1,4 +1,5 @@
-import { z } from "zod";
+import { z } from "./zod.js";
+import { findOperation } from "./operations.js";
 /**
  * One thing that can go wrong at a step, and the next move.
  *
@@ -261,12 +262,12 @@ export const FIRST_VALUE_STEPS = [
         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 there is no such endpoint. Create a destination in this project, or check the identifier.",
+                when: "not_found",
             },
             {
-                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 endpoint is disabled. Enable it with `endpoints.enable` and the schedule is accepted as sent, or point the schedule at another destination.",
+                when: "state_conflict",
             },
             {
                 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.",
@@ -384,7 +385,7 @@ export const FIRST_VALUE_STEPS = [
         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.",
+        purpose: "Stops delivery to the destination you registered for this walkthrough. Disabling is deliberate rather than final: it leaves the history intact rather than deleting evidence of what happened, and `endpoints.enable` turns the destination back on if you want it again.",
         recovery: [
             {
                 nextMove: "Already gone, or never in this project. Nothing to clean up.",
@@ -464,3 +465,208 @@ export function resolveJourneyReferences(value, resolve) {
 export function journeyCapturedVariables() {
     return FIRST_VALUE_STEPS.flatMap((step) => (step.capture ?? []).map((capture) => capture.variable));
 }
+/**
+ * The website's rendering of the same journey.
+ *
+ * **Declared here rather than in the dashboard, because it is the *binding*
+ * between two things that already exist and neither of them may own it.** The
+ * dashboard has a four-step onboarding flow derived from what a member's
+ * project contains; this file has a nine-step sequence derived from the
+ * operation registry. Left unrelated they answered the same question with
+ * different words and different examples, and the website's answer was the one
+ * that went stale: its "Schedule a one-shot" step rendered the registry's
+ * `schedules.create` example, which is a **recurring cron** — a live dashboard
+ * action showing a reader the one thing the step promises it is not.
+ *
+ * So a website step names journey steps, and never a body, a title or a
+ * sentence of its own. What the browser prints is what the curl page prints,
+ * because it is the same declaration rendered twice.
+ *
+ */
+export const WEBSITE_JOURNEY_STEP_KEYS = {
+    delivered: ["await-occurrence", "read-attempt"],
+    destination: ["create-destination"],
+    scheduled: ["create-one-shot"],
+};
+/** The journey steps a website step renders, resolved against the sequence. */
+export function websiteJourneySteps(step) {
+    const keys = WEBSITE_JOURNEY_STEP_KEYS[step] ?? [];
+    return keys.map((key) => {
+        const found = FIRST_VALUE_STEPS.find((entry) => entry.key === key);
+        if (found === undefined) {
+            // Not reachable from the constant above, and that is exactly why it
+            // throws: the map is hand-written and the sequence is not, so a step
+            // renamed in `FIRST_VALUE_STEPS` must fail loudly here rather than
+            // silently render one fewer call than the page promises.
+            throw new Error(`website journey names unknown step ${key}`);
+        }
+        return found;
+    });
+}
+/**
+ * The bounded wait the website inherits, rather than one it chose.
+ *
+ * W9-01's fourth criterion asks the browser to bound outcome polling and to
+ * leave a recovery action on timeout. The journey already declares both numbers
+ * on `await-occurrence`, and the curl and JavaScript quickstarts already wait
+ * exactly that long — so a browser that picked its own interval would be a
+ * third answer to a question with one published answer, and the reader who
+ * followed both would be told two different things about how long to wait.
+ */
+export function journeyPoll(key) {
+    const step = FIRST_VALUE_STEPS.find((entry) => entry.key === key);
+    if (step?.poll === undefined) {
+        throw new Error(`journey step ${key} declares no bounded wait`);
+    }
+    return step.poll;
+}
+/**
+ * What the reader has to bring, in the words the quickstarts already use.
+ *
+ * The website used to write its own: "anything that can take an HTTP POST. A
+ * webhook playground is fine for a first look." That sentence steered a new
+ * customer to paste their first callback into a third-party inspection service,
+ * which is the thing this project's receiver decision exists to refuse, and it
+ * disagreed with the curl page on the same screenful of product.
+ *
+ * The operator's decision on W9-01 was that the *invitation* says none of this
+ * — a prerequisite stated before somebody has any context is noise they cannot
+ * act on. It is said here instead, at the step that needs it.
+ */
+export function journeyPrerequisite(id) {
+    const found = FIRST_VALUE_PREREQUISITES.find((entry) => entry.id === id);
+    if (found === undefined) {
+        throw new Error(`journey declares no prerequisite ${id}`);
+    }
+    return found;
+}
+/**
+ * How long a website step took, as a bucket and never as a number.
+ *
+ * Coarser than `MCP_ACTIVATION_DURATIONS`, because these measure different
+ * things: a connection test is a handshake and finishes in seconds, and a
+ * person adding a destination and scheduling a callback is doing minutes of
+ * work. Reusing the millisecond buckets would put every website step in
+ * `over_30s` and record nothing.
+ */
+export const JOURNEY_ACTIVATION_DURATIONS = [
+    "under_1m",
+    "under_5m",
+    "under_15m",
+    "over_15m",
+];
+export function journeyActivationDuration(elapsedMs) {
+    if (elapsedMs < 60_000)
+        return "under_1m";
+    if (elapsedMs < 300_000)
+        return "under_5m";
+    if (elapsedMs < 900_000)
+        return "under_15m";
+    return "over_15m";
+}
+/** Every way a website step can end, drawn from a closed list. */
+export const JOURNEY_ACTIVATION_OUTCOMES = [
+    "reached",
+    "refused",
+    "timed_out",
+    "failed",
+];
+/** The website steps an activation fact may name. */
+export const WEBSITE_JOURNEY_STEPS = [
+    "destination",
+    "scheduled",
+    "delivered",
+];
+/**
+ * What is recorded when somebody moves through the website journey, and the
+ * only thing that is.
+ *
+ * **Modelled on `mcpActivationEventSchema` down to the `strictObject`, and for
+ * the same reason.** Every field is drawn from a closed set: there is no
+ * free-text field, no identifier, no address, no URL and no measurement finer
+ * than a bucket, so an event of this shape cannot carry an account, an
+ * organization, a project, an invitation link, a token, a destination or a
+ * payload however carelessly it is constructed.
+ *
+ * Strict rather than merely typed. An ordinary object schema *strips* what it
+ * does not know, so an emitter that added `project` would look like it was
+ * recording one while the field silently vanished — safe and dishonest at once.
+ * The MCP schema learned that from a test and this one inherits the lesson
+ * rather than rediscovering it.
+ */
+export const websiteActivationEventSchema = z.strictObject({
+    duration: z.enum(JOURNEY_ACTIVATION_DURATIONS),
+    outcome: z.enum(JOURNEY_ACTIVATION_OUTCOMES),
+    step: z.enum(WEBSITE_JOURNEY_STEPS),
+    type: z.literal("website.journey_step"),
+});
+/**
+ * Parses an activation fact before it leaves the browser.
+ *
+ * The parse is the control, exactly as it is on the MCP side: a caller hands
+ * this an object and the schema refuses anything the closed sets do not admit,
+ * so the mistake surfaces where it was made rather than as a field that quietly
+ * disappeared.
+ */
+export function parseWebsiteActivationEvent(value) {
+    return websiteActivationEventSchema.parse(value);
+}
+/**
+ * A path parameter's name, as the journey's variables spell it.
+ *
+ * **Published because a machine consumer cannot run the journey without it.**
+ * A step names its operation and the variables it needs — `read-schedule` says
+ * `/v1/schedules/{scheduleId}` and, separately, `GREATWAIT_SCHEDULEID` — and
+ * the rule joining the two lived in `scripts/first-value-projection.ts`, which
+ * is not published. A documentation page never notices: it renders both halves
+ * as text and a human joins them by eye. A command-line client has to *fill*
+ * the parameter, and had to re-derive the convention by guessing at it.
+ *
+ * The transformation is deliberately total and lossy in the safe direction:
+ * every non-alphanumeric character becomes `_`, so a parameter that differs
+ * from another only in punctuation would collide. `journeyPathVariables` is
+ * where that would surface, and `first-value-journey.test.ts` holds the
+ * journey's own parameters to distinct names.
+ */
+export function journeyVariableName(parameter) {
+    return `GREATWAIT_${parameter.toUpperCase().replace(/[^A-Z0-9]/gu, "_")}`;
+}
+/** Every `{parameter}` in a path, in the order the path names them. */
+export function pathParameterNames(path) {
+    return [...path.matchAll(/\{([^}]+)\}/gu)].map((match) => match[1]);
+}
+/**
+ * The variables a step's path parameters are filled from, in path order.
+ *
+ * Order is the contract: a client filling positional arguments — which is what
+ * the generated client takes — needs them in the order the path names them,
+ * and `attempts.list` has two.
+ */
+export function journeyPathVariables(step) {
+    const operation = findOperation(step.operationId);
+    if (operation === undefined) {
+        throw new Error(`the first-value journey names ${step.operationId}, which is not an operation`);
+    }
+    return pathParameterNames(operation.path).map(journeyVariableName);
+}
+/**
+ * Everything a step must be given before it can be performed.
+ *
+ * **Published because it is a join, and a join is where a second consumer
+ * invents its own copy.** A step's inputs come from three places — the
+ * operation's path parameters, the `{{…}}` references in its body, query and
+ * headers — and stitching them is the kind of two-line rule every consumer gets
+ * *nearly* right. The machine-readable artifact's own `variables` field is this
+ * function, so a client reading the artifact and a client reading this module
+ * cannot disagree about what a step needs.
+ */
+export function journeyStepVariables(step) {
+    return [
+        ...new Set([
+            ...journeyPathVariables(step),
+            ...journeyReferences(step.request),
+            ...journeyReferences(step.query),
+            ...journeyReferences(step.requestHeaders),
+        ]),
+    ];
+}

package/dist/forecast.d.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 import type { FieldError } from "./problems.js";
 import { type Freshness } from "./protocol.js";
 import type { ForecastPartitionBucket } from "./partition.js";
@@ -120,20 +120,20 @@ export declare const FORECAST_BOUNDS: {
  * the total and the latency split, which every answer carries.
  */
 export declare const FORECAST_BREAKDOWNS: readonly ["none", "partitionKey"];
-export declare const forecastBreakdownSchema: z.ZodEnum<{
+export declare const forecastBreakdownSchema: import("zod").ZodEnum<{
     none: "none";
     partitionKey: "partitionKey";
 }>;
 export type ForecastBreakdown = z.infer<typeof forecastBreakdownSchema>;
-export declare const forecastRequestSchema: z.ZodObject<{
-    breakdown: z.ZodDefault<z.ZodEnum<{
+export declare const forecastRequestSchema: import("zod").ZodObject<{
+    breakdown: import("zod").ZodDefault<import("zod").ZodEnum<{
         none: "none";
         partitionKey: "partitionKey";
     }>>;
-    bucketSeconds: z.ZodDefault<z.ZodNumber>;
-    from: z.ZodOptional<z.ZodString>;
-    to: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
+    bucketSeconds: import("zod").ZodDefault<import("zod").ZodNumber>;
+    from: import("zod").ZodOptional<import("zod").ZodString>;
+    to: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>;
 export type ForecastRequest = z.infer<typeof forecastRequestSchema>;
 export type ForecastRequestParse = {
     readonly errors: readonly FieldError[];
@@ -197,46 +197,46 @@ export declare function forecastBucketStartMs(instantMs: number, bucketSeconds:
  * third latency class fails a test here rather than silently vanishing from
  * every forecast.
  */
-export declare const forecastLatencyCountsSchema: z.ZodObject<{
-    bulk: z.ZodNumber;
-    realtime: z.ZodNumber;
-}, z.core.$strip>;
+export declare const forecastLatencyCountsSchema: import("zod").ZodObject<{
+    bulk: import("zod").ZodNumber;
+    realtime: import("zod").ZodNumber;
+}, import("zod/v4/core").$strip>;
 export type ForecastLatencyCounts = z.infer<typeof forecastLatencyCountsSchema>;
-export declare const forecastBucketSchema: z.ZodObject<{
-    byLatencyClass: z.ZodObject<{
-        bulk: z.ZodNumber;
-        realtime: z.ZodNumber;
-    }, z.core.$strip>;
-    byPartitionKey: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
-    count: z.ZodNumber;
-    nextFireCount: z.ZodNumber;
-    otherPartitionKeyCount: z.ZodOptional<z.ZodNumber>;
-    start: z.ZodString;
-}, z.core.$strip>;
+export declare const forecastBucketSchema: import("zod").ZodObject<{
+    byLatencyClass: import("zod").ZodObject<{
+        bulk: import("zod").ZodNumber;
+        realtime: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>;
+    byPartitionKey: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodNumber>>;
+    count: import("zod").ZodNumber;
+    nextFireCount: import("zod").ZodNumber;
+    otherPartitionKeyCount: import("zod").ZodOptional<import("zod").ZodNumber>;
+    start: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
 export type ForecastBucket = z.infer<typeof forecastBucketSchema>;
-export declare const forecastSchema: z.ZodObject<{
-    buckets: z.ZodArray<z.ZodObject<{
-        byLatencyClass: z.ZodObject<{
-            bulk: z.ZodNumber;
-            realtime: z.ZodNumber;
-        }, z.core.$strip>;
-        byPartitionKey: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
-        count: z.ZodNumber;
-        nextFireCount: z.ZodNumber;
-        otherPartitionKeyCount: z.ZodOptional<z.ZodNumber>;
-        start: z.ZodString;
-    }, z.core.$strip>>;
-    freshness: z.ZodObject<{
-        asOf: z.ZodString;
-        kind: z.ZodLiteral<"projected">;
-        lagSeconds: z.ZodNumber;
-    }, z.core.$strip>;
-    window: z.ZodObject<{
-        bucketSeconds: z.ZodNumber;
-        from: z.ZodString;
-        to: z.ZodString;
-    }, z.core.$strip>;
-}, z.core.$strip>;
+export declare const forecastSchema: import("zod").ZodObject<{
+    buckets: import("zod").ZodArray<import("zod").ZodObject<{
+        byLatencyClass: import("zod").ZodObject<{
+            bulk: import("zod").ZodNumber;
+            realtime: import("zod").ZodNumber;
+        }, import("zod/v4/core").$strip>;
+        byPartitionKey: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodNumber>>;
+        count: import("zod").ZodNumber;
+        nextFireCount: import("zod").ZodNumber;
+        otherPartitionKeyCount: import("zod").ZodOptional<import("zod").ZodNumber>;
+        start: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
+    freshness: import("zod").ZodObject<{
+        asOf: import("zod").ZodString;
+        kind: import("zod").ZodLiteral<"projected">;
+        lagSeconds: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>;
+    window: import("zod").ZodObject<{
+        bucketSeconds: import("zod").ZodNumber;
+        from: import("zod").ZodString;
+        to: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>;
+}, import("zod/v4/core").$strip>;
 export type Forecast = z.infer<typeof forecastSchema>;
 /** One bucket, summed across every shard, before it is rendered. */
 export interface ForecastMergedBucket {
@@ -329,32 +329,32 @@ export declare function decideForecastAnswer(answers: readonly ForecastShardAnsw
  * rather than one it discovers.
  */
 export declare const FORECAST_WINDOW_VERSION = "2026-08-09";
-export declare const forecastWindowBucketSchema: z.ZodObject<{
-    byTenant: z.ZodRecord<z.ZodString, z.ZodNumber>;
-    count: z.ZodNumber;
-    nextFireCount: z.ZodNumber;
-    otherCount: z.ZodNumber;
-    start: z.ZodString;
-}, z.core.$strip>;
+export declare const forecastWindowBucketSchema: import("zod").ZodObject<{
+    byTenant: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodNumber>;
+    count: import("zod").ZodNumber;
+    nextFireCount: import("zod").ZodNumber;
+    otherCount: import("zod").ZodNumber;
+    start: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
 export type ForecastWindowBucket = z.infer<typeof forecastWindowBucketSchema>;
-export declare const forecastWindowsSchema: z.ZodObject<{
-    bucketSeconds: z.ZodNumber;
-    buckets: z.ZodArray<z.ZodObject<{
-        byTenant: z.ZodRecord<z.ZodString, z.ZodNumber>;
-        count: z.ZodNumber;
-        nextFireCount: z.ZodNumber;
-        otherCount: z.ZodNumber;
-        start: z.ZodString;
-    }, z.core.$strip>>;
-    freshness: z.ZodDiscriminatedUnion<[z.ZodObject<{
-        kind: z.ZodLiteral<"authoritative">;
-    }, z.core.$strip>, z.ZodObject<{
-        asOf: z.ZodString;
-        kind: z.ZodLiteral<"projected">;
-        lagSeconds: z.ZodNumber;
-    }, z.core.$strip>], "kind">;
-    version: z.ZodLiteral<"2026-08-09">;
-}, z.core.$strip>;
+export declare const forecastWindowsSchema: import("zod").ZodObject<{
+    bucketSeconds: import("zod").ZodNumber;
+    buckets: import("zod").ZodArray<import("zod").ZodObject<{
+        byTenant: import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodNumber>;
+        count: import("zod").ZodNumber;
+        nextFireCount: import("zod").ZodNumber;
+        otherCount: import("zod").ZodNumber;
+        start: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
+    freshness: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+        kind: import("zod").ZodLiteral<"authoritative">;
+    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+        asOf: import("zod").ZodString;
+        kind: import("zod").ZodLiteral<"projected">;
+        lagSeconds: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>], "kind">;
+    version: import("zod").ZodLiteral<"2026-08-09">;
+}, import("zod/v4/core").$strip>;
 export type ForecastWindows = z.infer<typeof forecastWindowsSchema>;
 /**
  * What the migrating consumer may rely on, published as data.

package/dist/forecast.js

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 import { freshnessSchema, projectedFreshnessSchema, } from "./protocol.js";
 import { timestampSchema } from "./time.js";
 /**

package/dist/identifiers.d.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 /**
  * Public identifiers.
  *
@@ -37,25 +37,25 @@ export type IdResource = keyof typeof ID_PREFIXES;
 export declare function idPattern(resource: IdResource): RegExp;
 /** Any well-formed public identifier, whatever it names. */
 export declare const ANY_ID_PATTERN: RegExp;
-export declare function idSchema(resource: IdResource): z.ZodString;
-export declare const apiCredentialIdSchema: z.ZodString;
-export declare const apiCredentialEventIdSchema: z.ZodString;
-export declare const authorizationRequestIdSchema: z.ZodString;
-export declare const callbackSigningKeyIdSchema: z.ZodString;
-export declare const oauthClientIdSchema: z.ZodString;
-export declare const oauthGrantIdSchema: z.ZodString;
-export declare const oauthGrantEventIdSchema: z.ZodString;
-export declare const scheduleIdSchema: z.ZodString;
-export declare const occurrenceIdSchema: z.ZodString;
-export declare const attemptIdSchema: z.ZodString;
-export declare const deliveryIdSchema: z.ZodString;
-export declare const endpointIdSchema: z.ZodString;
-export declare const organizationIdSchema: z.ZodString;
-export declare const projectIdSchema: z.ZodString;
-export declare const environmentIdSchema: z.ZodString;
-export declare const eventIdSchema: z.ZodString;
-export declare const testSinkIdSchema: z.ZodString;
-export declare const testSinkDeliveryIdSchema: z.ZodString;
+export declare function idSchema(resource: IdResource): import("zod").ZodString;
+export declare const apiCredentialIdSchema: import("zod").ZodString;
+export declare const apiCredentialEventIdSchema: import("zod").ZodString;
+export declare const authorizationRequestIdSchema: import("zod").ZodString;
+export declare const callbackSigningKeyIdSchema: import("zod").ZodString;
+export declare const oauthClientIdSchema: import("zod").ZodString;
+export declare const oauthGrantIdSchema: import("zod").ZodString;
+export declare const oauthGrantEventIdSchema: import("zod").ZodString;
+export declare const scheduleIdSchema: import("zod").ZodString;
+export declare const occurrenceIdSchema: import("zod").ZodString;
+export declare const attemptIdSchema: import("zod").ZodString;
+export declare const deliveryIdSchema: import("zod").ZodString;
+export declare const endpointIdSchema: import("zod").ZodString;
+export declare const organizationIdSchema: import("zod").ZodString;
+export declare const projectIdSchema: import("zod").ZodString;
+export declare const environmentIdSchema: import("zod").ZodString;
+export declare const eventIdSchema: import("zod").ZodString;
+export declare const testSinkIdSchema: import("zod").ZodString;
+export declare const testSinkDeliveryIdSchema: import("zod").ZodString;
 export type ApiCredentialId = z.infer<typeof apiCredentialIdSchema>;
 export type ApiCredentialEventId = z.infer<typeof apiCredentialEventIdSchema>;
 export type AuthorizationRequestId = z.infer<typeof authorizationRequestIdSchema>;

package/dist/identifiers.js

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 /**
  * Public identifiers.
  *

package/dist/identity.d.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 /**
  * External identity, and what it projects into.
  *
@@ -32,8 +32,8 @@ import { z } from "zod";
  * surface depend on our identity vendor and hand callers a second spelling of
  * the same tenant.
  */
-export declare const externalOrganizationIdSchema: z.ZodString;
-export declare const externalUserIdSchema: z.ZodString;
+export declare const externalOrganizationIdSchema: import("zod").ZodString;
+export declare const externalUserIdSchema: import("zod").ZodString;
 /**
  * A Clerk organization-membership identifier, and the projection's primary key.
  *
@@ -44,21 +44,22 @@ export declare const externalUserIdSchema: z.ZodString;
  * the new one is a separate row, which is also what makes the two orderable
  * independently.
  */
-export declare const externalMembershipIdSchema: z.ZodString;
+export declare const externalMembershipIdSchema: import("zod").ZodString;
 export type ExternalOrganizationId = z.infer<typeof externalOrganizationIdSchema>;
 export type ExternalUserId = z.infer<typeof externalUserIdSchema>;
 export type ExternalMembershipId = z.infer<typeof externalMembershipIdSchema>;
 /**
- * Product roles, projected from Clerk's `org:admin` and `org:member`.
+ * Product roles, projected from Clerk's organization roles.
  *
  * Named without the `org:` prefix because these are ours: W1-03 builds the
  * role-to-scope matrix on them, and binding that matrix to a vendor's string
  * format would make changing identity providers a contract change.
  */
-export declare const MEMBERSHIP_ROLES: readonly ["admin", "member"];
-export declare const membershipRoleSchema: z.ZodEnum<{
-    admin: "admin";
+export declare const MEMBERSHIP_ROLES: readonly ["admin", "billing", "member"];
+export declare const membershipRoleSchema: import("zod").ZodEnum<{
     member: "member";
+    admin: "admin";
+    billing: "billing";
 }>;
 export type MembershipRole = z.infer<typeof membershipRoleSchema>;
 /**
@@ -69,9 +70,9 @@ export type MembershipRole = z.infer<typeof membershipRoleSchema>;
  * it and rejoining creates a new one. Both refuse access.
  */
 export declare const MEMBERSHIP_STATUSES: readonly ["active", "suspended", "removed"];
-export declare const membershipStatusSchema: z.ZodEnum<{
-    removed: "removed";
+export declare const membershipStatusSchema: import("zod").ZodEnum<{
     active: "active";
+    removed: "removed";
     suspended: "suspended";
 }>;
 export type MembershipStatus = z.infer<typeof membershipStatusSchema>;
@@ -95,21 +96,22 @@ export declare function leastStatus(left: MembershipStatus, right: MembershipSta
  * convergent: there is no event that updates the status while leaving the role
  * behind at an older version, so one version orders the whole record.
  */
-export declare const membershipSchema: z.ZodObject<{
-    id: z.ZodString;
-    organization: z.ZodString;
-    role: z.ZodEnum<{
-        admin: "admin";
+export declare const membershipSchema: import("zod").ZodObject<{
+    id: import("zod").ZodString;
+    organization: import("zod").ZodString;
+    role: import("zod").ZodEnum<{
         member: "member";
+        admin: "admin";
+        billing: "billing";
     }>;
-    status: z.ZodEnum<{
-        removed: "removed";
+    status: import("zod").ZodEnum<{
         active: "active";
+        removed: "removed";
         suspended: "suspended";
     }>;
-    user: z.ZodString;
-    version: z.ZodNumber;
-}, z.core.$strip>;
+    user: import("zod").ZodString;
+    version: import("zod").ZodNumber;
+}, import("zod/v4/core").$strip>;
 export type Membership = z.infer<typeof membershipSchema>;
 /**
  * One change, normalized by the adapter from a Clerk webhook payload.
@@ -136,21 +138,22 @@ export type Membership = z.infer<typeof membershipSchema>;
  * change. Deleting an organization does not. The asymmetry is real and is why
  * only one of the two has a tombstone.
  */
-export declare const membershipChangeSchema: z.ZodObject<{
-    id: z.ZodString;
-    organization: z.ZodString;
-    role: z.ZodEnum<{
-        admin: "admin";
+export declare const membershipChangeSchema: import("zod").ZodObject<{
+    id: import("zod").ZodString;
+    organization: import("zod").ZodString;
+    role: import("zod").ZodEnum<{
         member: "member";
+        admin: "admin";
+        billing: "billing";
     }>;
-    status: z.ZodEnum<{
-        removed: "removed";
+    status: import("zod").ZodEnum<{
         active: "active";
+        removed: "removed";
         suspended: "suspended";
     }>;
-    user: z.ZodString;
-    version: z.ZodNumber;
-}, z.core.$strip>;
+    user: import("zod").ZodString;
+    version: import("zod").ZodNumber;
+}, import("zod/v4/core").$strip>;
 export type MembershipChange = Membership;
 /**
  * The membership a verified session asserts.
@@ -160,15 +163,16 @@ export type MembershipChange = Membership;
  * milliseconds — when Clerk vouched for this membership — which is what makes it
  * comparable against a projected `version` from the same clock.
  */
-export declare const sessionMembershipSchema: z.ZodObject<{
-    assertedAt: z.ZodNumber;
-    organization: z.ZodString;
-    role: z.ZodEnum<{
-        admin: "admin";
+export declare const sessionMembershipSchema: import("zod").ZodObject<{
+    assertedAt: import("zod").ZodNumber;
+    organization: import("zod").ZodString;
+    role: import("zod").ZodEnum<{
         member: "member";
+        admin: "admin";
+        billing: "billing";
     }>;
-    user: z.ZodString;
-}, z.core.$strip>;
+    user: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
 export type SessionMembership = z.infer<typeof sessionMembershipSchema>;
 /**
  * A record that an organization was deleted.
@@ -189,8 +193,8 @@ export type SessionMembership = z.infer<typeof sessionMembershipSchema>;
  * for an organization that no longer exists. Deleting a *user* does emit a
  * membership deletion. That asymmetry is why this exists — see FXO-1377.
  */
-export declare const organizationTombstoneSchema: z.ZodObject<{
-    organization: z.ZodString;
-    version: z.ZodNumber;
-}, z.core.$strip>;
+export declare const organizationTombstoneSchema: import("zod").ZodObject<{
+    organization: import("zod").ZodString;
+    version: import("zod").ZodNumber;
+}, import("zod/v4/core").$strip>;
 export type OrganizationTombstone = z.infer<typeof organizationTombstoneSchema>;