@greatwait/contracts 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/callback-safety.d.ts

@@ -4,8 +4,8 @@
  * DNS is deliberately not represented here: names are resolved and every
  * returned address is passed through `isPublicCallbackAddress` by the caller.
  *
- * **That caller is endpoint creation and verification, and since 2026-08-11 it
- * is nowhere else.** This comment used to end "and immediately before a send",
+ * **That caller is endpoint creation and update, and since 2026-08-11 it is
+ * nowhere else.** This comment used to end "and immediately before a send",
  * which FXO-1566 made false when it removed the send-time re-resolution. What
  * runs at send time is `evaluateCallbackUrl` alone — a string check, which
  * cannot see where a hostname points now. FXO-1575 measured what the platform

package/dist/callback-safety.js

@@ -4,8 +4,8 @@
  * DNS is deliberately not represented here: names are resolved and every
  * returned address is passed through `isPublicCallbackAddress` by the caller.
  *
- * **That caller is endpoint creation and verification, and since 2026-08-11 it
- * is nowhere else.** This comment used to end "and immediately before a send",
+ * **That caller is endpoint creation and update, and since 2026-08-11 it is
+ * nowhere else.** This comment used to end "and immediately before a send",
  * which FXO-1566 made false when it removed the send-time re-resolution. What
  * runs at send time is `evaluateCallbackUrl` alone — a string check, which
  * cannot see where a hostname points now. FXO-1575 measured what the platform
@@ -136,10 +136,20 @@ const FORBIDDEN_NAME_SUFFIXES = [
  * surface this rule exists to deny. The old form stays because the old names
  * keep resolving until their custom domains are detached, and because a DNS
  * record somebody forgets is precisely what this should still refuse.
+ *
+ * **`docs` joined the vocabulary at FXO-2441**, with `docs.greatwait.dev`. It
+ * is a static site with no Worker script behind it, which is an argument for
+ * why aiming a callback there is harmless *today* and no argument at all for
+ * allowing it: the rule is about names this product answers on as itself, and
+ * `scripts/deployables.test.ts` asserts it over the deployment model rather
+ * than over this list, so a hostname added there and not here fails. *
+ * **The apex joined it at W9-05**, when the marketing site started serving
+ * `greatwait.dev` itself rather than only forwarding it. It is an address this
+ * product answers on as itself, so it is refused on the same argument.
  */
-const GREATWAIT_RUNTIME_NAME = /^(?:greatwait-(?:api|app|scheduler|contract-mock|postgres-runtime)(?:-[a-z0-9-]+)?\.flowxo\.com|(?:api|app|scheduler|contract-mock|postgres-runtime)(?:-[a-z0-9-]+)?\.greatwait\.dev)$/u;
-const GREATWAIT_PROVIDER_NAME = /^greatwait-(?:api|app|scheduler|contract-mock|postgres-runtime)(?:-[a-z0-9-]+)?(?:\..+)?\.(?:workers|pages)\.dev$/u;
-const GREATWAIT_WORKER_NAME = /^greatwait-(?:api|app|scheduler|contract-mock|postgres-runtime)(?:-[a-z0-9-]+)?$/u;
+const GREATWAIT_RUNTIME_NAME = /^(?:greatwait-(?:api|app|docs|scheduler|contract-mock|postgres-runtime)(?:-[a-z0-9-]+)?\.flowxo\.com|(?:api|app|docs|scheduler|contract-mock|postgres-runtime)(?:-[a-z0-9-]+)?\.greatwait\.dev|greatwait\.dev)$/u;
+const GREATWAIT_PROVIDER_NAME = /^greatwait-(?:api|app|docs|marketing|scheduler|contract-mock|postgres-runtime)(?:-[a-z0-9-]+)?(?:\..+)?\.(?:workers|pages)\.dev$/u;
+const GREATWAIT_WORKER_NAME = /^greatwait-(?:api|app|docs|marketing|scheduler|contract-mock|postgres-runtime)(?:-[a-z0-9-]+)?$/u;
 /** Evaluate the URL-only half of the callback destination policy. */
 export function evaluateCallbackUrl(value) {
     if (value.trim() !== value) {

package/dist/compatibility.d.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 /**
  * What may change, and what that costs.
  *
@@ -7,7 +7,7 @@ import { z } from "zod";
  * day, and a contract change must be visible even when no code deployed.
  */
 export declare const CONTRACT_VERSION: "2026-08-22";
-export declare const contractVersionSchema: z.ZodLiteral<"2026-08-22">;
+export declare const contractVersionSchema: import("zod").ZodLiteral<"2026-08-22">;
 /**
  * Three kinds of change, and only the first is free.
  *
@@ -29,7 +29,7 @@ export declare const contractVersionSchema: z.ZodLiteral<"2026-08-22">;
  * exercised by fixtures, so "we thought it was additive" is a testable claim.
  */
 export declare const CHANGE_KINDS: readonly ["additive", "breaking", "deployment-only"];
-export declare const changeKindSchema: z.ZodEnum<{
+export declare const changeKindSchema: import("zod").ZodEnum<{
     additive: "additive";
     breaking: "breaking";
     "deployment-only": "deployment-only";

package/dist/compatibility.js

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 /**
  * What may change, and what that costs.
  *

package/dist/configuration-bounds.d.ts

@@ -0,0 +1,13 @@
+/** Scalar owners shared by contracts and small runtime bundles. */
+export declare const FIXED_INTERVAL_MIN_SECONDS = 60;
+export declare const FIXED_INTERVAL_MAX_SECONDS: number;
+export declare const MAX_INLINE_PAYLOAD_BYTES = 65536;
+export declare const MAX_FORECAST_HORIZON_SECONDS: number;
+export declare const MAX_HOST_CONNECTIONS = 100000;
+export declare const MAX_USAGE_WINDOW_DAYS = 366;
+export declare const MAX_PARTITION_KEY_CEILING = 10000;
+export declare const PUBLIC_PAGE_SIZE: Readonly<{
+    default: 25;
+    max: 100;
+    min: 1;
+}>;

package/dist/configuration-bounds.js

@@ -0,0 +1,13 @@
+/** Scalar owners shared by contracts and small runtime bundles. */
+export const FIXED_INTERVAL_MIN_SECONDS = 60;
+export const FIXED_INTERVAL_MAX_SECONDS = 365 * 24 * 60 * 60;
+export const MAX_INLINE_PAYLOAD_BYTES = 65_536;
+export const MAX_FORECAST_HORIZON_SECONDS = 25 * 60 * 60;
+export const MAX_HOST_CONNECTIONS = 100_000;
+export const MAX_USAGE_WINDOW_DAYS = 366;
+export const MAX_PARTITION_KEY_CEILING = 10_000;
+export const PUBLIC_PAGE_SIZE = Object.freeze({
+    default: 25,
+    max: 100,
+    min: 1,
+});

package/dist/data-export.d.ts

@@ -0,0 +1,67 @@
+import { z } from "./zod.js";
+import { type RandomBytes } from "./identifiers.js";
+/** A server-assigned export identifier. */
+export declare const dataExportIdSchema: import("zod").ZodString;
+/** Mints the export id without extending the shared identifier vocabulary. */
+export declare function newDataExportId(randomBytes?: RandomBytes): string;
+export declare const DATA_EXPORT_STATES: readonly ["active", "complete", "cancelled"];
+export declare const dataExportStateSchema: import("zod").ZodEnum<{
+    active: "active";
+    cancelled: "cancelled";
+    complete: "complete";
+}>;
+/** Creating an export takes no authority from the body. */
+export declare const dataExportCreateRequestSchema: import("zod").ZodObject<{}, import("zod/v4/core").$strict>;
+export declare const dataExportSchema: import("zod").ZodObject<{
+    createdAt: import("zod").ZodString;
+    consistency: import("zod").ZodLiteral<"creation-cutoff-current-values">;
+    cutoffAt: import("zod").ZodString;
+    id: import("zod").ZodString;
+    state: import("zod").ZodEnum<{
+        active: "active";
+        cancelled: "cancelled";
+        complete: "complete";
+    }>;
+    updatedAt: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
+export declare const dataExportPartRequestSchema: import("zod").ZodObject<{
+    cursor: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strict>;
+/**
+ * One bounded file transported inside the ordinary JSON response envelope.
+ * `content` is NDJSON so callers can save it without interpreting customer
+ * payload fields, while the response itself stays compatible with the SDK.
+ */
+export declare const dataExportPartSchema: import("zod").ZodObject<{
+    content: import("zod").ZodString;
+    fileName: import("zod").ZodString;
+    mediaType: import("zod").ZodLiteral<"application/x-ndjson">;
+    nextCursor: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>;
+export declare const dataExportCancelledSchema: import("zod").ZodObject<{
+    cancelled: import("zod").ZodLiteral<true>;
+    export: import("zod").ZodObject<{
+        createdAt: import("zod").ZodString;
+        consistency: import("zod").ZodLiteral<"creation-cutoff-current-values">;
+        cutoffAt: import("zod").ZodString;
+        id: import("zod").ZodString;
+        state: import("zod").ZodEnum<{
+            active: "active";
+            cancelled: "cancelled";
+            complete: "complete";
+        }>;
+        updatedAt: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>;
+}, import("zod/v4/core").$strip>;
+export type DataExport = z.infer<typeof dataExportSchema>;
+export type DataExportPart = z.infer<typeof dataExportPartSchema>;
+/** Additive operation declarations, merged into the canonical registry by the API wiring. */
+export declare const DATA_EXPORT_OPERATIONS: readonly [import("./operations.js").OperationDefinition & {
+    readonly id: "exports.create";
+}, import("./operations.js").OperationDefinition & {
+    readonly id: "exports.read";
+}, import("./operations.js").OperationDefinition & {
+    readonly id: "exports.part";
+}, import("./operations.js").OperationDefinition & {
+    readonly id: "exports.cancel";
+}];

package/dist/data-export.js

@@ -0,0 +1,182 @@
+import { z } from "./zod.js";
+import { API_UNUSED_RESPONSE_SCHEMA, defineOperations, } from "./operation-definitions.js";
+import { newId } from "./identifiers.js";
+import { timestampSchema } from "./time.js";
+/** A server-assigned export identifier. */
+export const dataExportIdSchema = z
+    .string()
+    .regex(/^exp_[0-9abcdefghjkmnpqrstvwxyz]{26}$/u);
+/** Mints the export id without extending the shared identifier vocabulary. */
+export function newDataExportId(randomBytes) {
+    return newId("schedule", randomBytes).replace("sch", "exp");
+}
+export const DATA_EXPORT_STATES = ["active", "complete", "cancelled"];
+export const dataExportStateSchema = /* @__PURE__ */ z.enum(DATA_EXPORT_STATES);
+/** Creating an export takes no authority from the body. */
+export const dataExportCreateRequestSchema = z.object({}).strict();
+export const dataExportSchema = /* @__PURE__ */ (() => z.object({
+    createdAt: timestampSchema,
+    consistency: z.literal("creation-cutoff-current-values"),
+    cutoffAt: timestampSchema,
+    id: dataExportIdSchema,
+    state: dataExportStateSchema,
+    updatedAt: timestampSchema,
+}))();
+export const dataExportPartRequestSchema = z
+    .object({ cursor: z.string().min(1).optional() })
+    .strict();
+/**
+ * One bounded file transported inside the ordinary JSON response envelope.
+ * `content` is NDJSON so callers can save it without interpreting customer
+ * payload fields, while the response itself stays compatible with the SDK.
+ */
+export const dataExportPartSchema = /* @__PURE__ */ (() => z.object({
+    content: z.string(),
+    fileName: z
+        .string()
+        .regex(/^greatwait-export-exp_[0-9abcdefghjkmnpqrstvwxyz]{26}\.ndjson$/u),
+    mediaType: z.literal("application/x-ndjson"),
+    nextCursor: z.string().min(1).optional(),
+}))();
+export const dataExportCancelledSchema = /* @__PURE__ */ (() => z.object({
+    cancelled: z.literal(true),
+    export: dataExportSchema,
+}))();
+const EXAMPLE = {
+    createdAt: "2035-03-04T12:00:00.000Z",
+    consistency: "creation-cutoff-current-values",
+    cutoffAt: "2035-03-04T12:00:00.000Z",
+    id: "exp_0123456789abcdefghjkmnpqrs",
+    state: "active",
+    updatedAt: "2035-03-04T12:00:00.000Z",
+};
+/** Additive operation declarations, merged into the canonical registry by the API wiring. */
+export const DATA_EXPORT_OPERATIONS = defineOperations([
+    {
+        creates: true,
+        description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Starts an export for the authenticated project and environment. Records created or planned after cutoffAt are excluded; mutable fields have their current value when each part is read. Authority comes from the verified principal; no scope fields are accepted in the body.",
+        example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : EXAMPLE,
+        id: "exports.create",
+        idempotent: false,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "POST",
+        mutates: true,
+        path: "/v1/exports",
+        principals: ["api-credential", "oauth", "session"],
+        problems: [
+            "invalid_request",
+            "plan_limit_reached",
+            "service_unavailable",
+            "state_conflict",
+        ],
+        request: dataExportCreateRequestSchema,
+        requestExample: globalThis
+            .GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : {},
+        response: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? API_UNUSED_RESPONSE_SCHEMA
+            : dataExportSchema,
+        scopes: ["schedules:read", "endpoints:read"],
+        sessionAuthority: "headers",
+        summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "Create a data export",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Reads export progress inside the authenticated authority tuple.",
+        example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : EXAMPLE,
+        id: "exports.read",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/exports/{exportId}",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["not_found", "service_unavailable", "state_conflict"],
+        response: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? API_UNUSED_RESPONSE_SCHEMA
+            : dataExportSchema,
+        scopes: ["schedules:read", "endpoints:read"],
+        sessionAuthority: "headers",
+        summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "Read a data export",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Returns one bounded NDJSON file part. Cursors are opaque, authenticated, and bound to this export job.",
+        example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : {
+                content: '{"kind":"schedule","value":{"id":"sch_0123456789abcdefghjkmnpq"}}\n',
+                fileName: "greatwait-export-exp_0123456789abcdefghjkmnpqrs.ndjson",
+                mediaType: "application/x-ndjson",
+            },
+        id: "exports.part",
+        idempotent: true,
+        mcp: {
+            kind: "unavailable",
+            reason: "A file part may contain customer payload plaintext; MCP exposes export metadata but never raw export content.",
+        },
+        method: "GET",
+        mutates: false,
+        path: "/v1/exports/{exportId}/parts",
+        principals: ["api-credential", "oauth", "session"],
+        problems: [
+            "invalid_request",
+            "not_found",
+            "service_unavailable",
+            "state_conflict",
+        ],
+        query: dataExportPartRequestSchema,
+        response: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? API_UNUSED_RESPONSE_SCHEMA
+            : dataExportPartSchema,
+        scopes: ["schedules:read", "endpoints:read"],
+        sessionAuthority: "headers",
+        summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "Download a data export part",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Permanently cancels an export job. Repeating cancellation is safe and cancelled jobs cannot serve file parts.",
+        example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : { cancelled: true, export: { ...EXAMPLE, state: "cancelled" } },
+        id: "exports.cancel",
+        idempotent: true,
+        mcp: { destructive: true, kind: "tool", openWorld: false },
+        method: "POST",
+        mutates: true,
+        path: "/v1/exports/{exportId}/cancel",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["not_found", "service_unavailable", "state_conflict"],
+        response: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? API_UNUSED_RESPONSE_SCHEMA
+            : dataExportCancelledSchema,
+        scopes: ["schedules:read", "endpoints:read"],
+        sessionAuthority: "headers",
+        summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "Cancel a data export",
+        surfaces: ["api", "mock"],
+    },
+]);

package/dist/effective-limits.d.ts

@@ -0,0 +1,40 @@
+import { z } from "./zod.js";
+export declare const effectiveCustomerLimitsSchema: import("zod").ZodObject<{
+    limits: import("zod").ZodObject<{
+        inlinePayloadBytes: import("zod").ZodNumber;
+        partitionKeyCeiling: import("zod").ZodOptional<import("zod").ZodNumber>;
+        forecastHorizonSeconds: import("zod").ZodNumber;
+        usageWindowDays: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strict>;
+    provenance: import("zod").ZodObject<{
+        inlinePayloadBytes: import("zod").ZodEnum<{
+            organization: "organization";
+            default: "default";
+            global: "global";
+            deployment: "deployment";
+        }>;
+        partitionKeyCeiling: import("zod").ZodOptional<import("zod").ZodEnum<{
+            organization: "organization";
+            default: "default";
+            global: "global";
+            deployment: "deployment";
+        }>>;
+        forecastHorizonSeconds: import("zod").ZodEnum<{
+            organization: "organization";
+            default: "default";
+            global: "global";
+            deployment: "deployment";
+        }>;
+        usageWindowDays: import("zod").ZodEnum<{
+            organization: "organization";
+            default: "default";
+            global: "global";
+            deployment: "deployment";
+        }>;
+    }, import("zod/v4/core").$strict>;
+    revision: import("zod").ZodObject<{
+        global: import("zod").ZodNumber;
+        organization: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strict>;
+}, import("zod/v4/core").$strict>;
+export type EffectiveCustomerLimits = z.infer<typeof effectiveCustomerLimitsSchema>;

package/dist/effective-limits.js

@@ -0,0 +1,42 @@
+import { z } from "./zod.js";
+import { MAX_INLINE_PAYLOAD_BYTES, MAX_FORECAST_HORIZON_SECONDS, MAX_USAGE_WINDOW_DAYS, MAX_PARTITION_KEY_CEILING, } from "./configuration-bounds.js";
+const layer = z.enum(["default", "global", "deployment", "organization"]);
+export const effectiveCustomerLimitsSchema = z
+    .object({
+    limits: z
+        .object({
+        inlinePayloadBytes: z
+            .number()
+            .int()
+            .min(0)
+            .max(MAX_INLINE_PAYLOAD_BYTES),
+        partitionKeyCeiling: z
+            .number()
+            .int()
+            .min(1)
+            .max(MAX_PARTITION_KEY_CEILING)
+            .optional(),
+        forecastHorizonSeconds: z
+            .number()
+            .int()
+            .min(60)
+            .max(MAX_FORECAST_HORIZON_SECONDS),
+        usageWindowDays: z.number().int().min(1).max(MAX_USAGE_WINDOW_DAYS),
+    })
+        .strict(),
+    provenance: z
+        .object({
+        inlinePayloadBytes: layer,
+        partitionKeyCeiling: layer.optional(),
+        forecastHorizonSeconds: layer,
+        usageWindowDays: layer,
+    })
+        .strict(),
+    revision: z
+        .object({
+        global: z.number().int().nonnegative(),
+        organization: z.number().int().nonnegative(),
+    })
+        .strict(),
+})
+    .strict();