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

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

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/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"],
+    },
+]);