@spacefast/common 0.0.24 → 0.2.1

package/dist/contracts/test-triggers.js

@@ -0,0 +1,116 @@
+// Reserved trigger values ("magic inputs") for LINKED TEST TENANTS
+// (partner-operations spec §1 "Test mode", L31-34). Stripe models test-mode
+// failures with magic inputs — a card number like `4000000000000341` that a
+// LIVE charge treats as an ordinary (invalid) number but a TEST charge turns
+// into a specific decline. We do the same for the partner API: a partner puts a
+// reserved token into the NATURAL input of an existing operation and, on a TEST
+// tenant only, that operation produces a specific failure state instead of
+// succeeding. There is NO new route and NO new field — a trigger is an ordinary
+// input value the caller already controls.
+//
+// The catalog itself is `TEST_TRIGGER_META` below — token, carrier and effect
+// per trigger, in one record, so the published API documentation renders from
+// the same data the detector matches on rather than a prose copy of it.
+//
+// The tokens carry a `sf-sim-` prefix so they are implausible as an organic name
+// and are valid across every carrier (a DNS label, a URL hostname, a slug, and a
+// principal id are all lowercase-hyphen-safe). A LIVE tenant treats the very same
+// value as ordinary input — the gate is `mode === "test"`, applied by every
+// interpreting call site (see `resolveTestTrigger`).
+//
+// FIDELITY (spec caveat): the `rate_limit` trigger FABRICATES a 429 problem
+// document — the partner-API rate limiter of ops §8 does not exist yet, so this
+// simulates the response a real limiter would return, not a real limiter. The
+// domain/TLS triggers synthesize provider (wp.cloud) SSL-info responses through
+// the simulated driver; there is no real DNS/cert in test mode.
+import { z } from "zod";
+export const testTriggerValues = [
+    "build_failure",
+    "domain_verification_pending",
+    "domain_verification_failed",
+    "tls_failure",
+    "rate_limit",
+    "webhook_retry",
+    "principal_suspension",
+    "usage_correction",
+];
+export const testTrigger = z.enum(testTriggerValues);
+/**
+ * Every trigger, in one record: the reserved token, the input that carries it,
+ * and what a test tenant gets instead of success.
+ *
+ * `carrier` and `effect` are contract text, not commentary — the partner API
+ * document renders its trigger table straight from them, so a renamed token or
+ * a new trigger cannot leave the published contract describing something else.
+ *
+ * No token is a substring of another, so a plain `includes` scan is unambiguous.
+ * Keep them lowercase — the detector lowercases the input, and every carrier (a
+ * DNS label, a slug, a principal id) is compared case-insensitively.
+ */
+export const TEST_TRIGGER_META = {
+    build_failure: {
+        sentinel: "sf-sim-build-fail",
+        carrier: "space slug",
+        effect: "the space's next build fails",
+    },
+    domain_verification_pending: {
+        sentinel: "sf-sim-domain-pending",
+        carrier: "custom domain name",
+        effect: "domain verification stays pending",
+    },
+    domain_verification_failed: {
+        sentinel: "sf-sim-domain-fail",
+        carrier: "custom domain name",
+        effect: "domain verification fails",
+    },
+    tls_failure: {
+        sentinel: "sf-sim-tls-fail",
+        carrier: "custom domain name",
+        effect: "certificate issuance fails",
+    },
+    rate_limit: {
+        sentinel: "sf-sim-rate-limit",
+        carrier: "space slug (on create)",
+        effect: "the create returns 429 `rate_limited`",
+    },
+    webhook_retry: {
+        sentinel: "sf-sim-webhook-retry",
+        carrier: "webhook URL",
+        effect: "delivery fails and enters the retry schedule",
+    },
+    principal_suspension: {
+        sentinel: "sf-sim-suspend",
+        carrier: "external principal id",
+        effect: "the principal is suspended",
+    },
+    usage_correction: {
+        sentinel: "sf-sim-usage-correction",
+        carrier: "space slug",
+        effect: "the next settled usage sample appends a linked correction",
+    },
+};
+// Return the trigger whose reserved token appears in `input`, or null. Carrier-
+// agnostic: `input` may be a slug, a hostname, a URL, or a principal id. The
+// token may be the whole value or a label within it (`sf-sim-tls-fail.acme.dev`).
+// This does NOT gate on mode — it is pure detection; `resolveTestTrigger` adds
+// the test-tenant gate.
+export function detectTestTrigger(input) {
+    if (!input)
+        return null;
+    const haystack = input.toLowerCase();
+    for (const trigger of testTriggerValues) {
+        if (haystack.includes(TEST_TRIGGER_META[trigger].sentinel))
+            return trigger;
+    }
+    return null;
+}
+// The one gate every interpreting call site shares: a trigger fires ONLY for a
+// `mode === "test"` tenant. A live tenant (or any non-test mode) always resolves
+// null, so the same input flows through the ordinary path — the no-leak-to-live
+// guarantee, in one place. `mode` is the owning tenant's mode (a `TenantMode`, or
+// the raw `tenants.mode` string).
+export function resolveTestTrigger(mode, input) {
+    if (mode !== "test")
+        return null;
+    return detectTestTrigger(input);
+}

package/dist/contracts/theme-json.js

@@ -1,13 +1,8 @@
 import { z } from "zod";
 // WordPress `theme.json`-compatible subset used only to infer Pages tokens.
-// Real WP theme.json carries dozens of unrelated keys (layout, blocks,
-// customTemplates, styles, ...); this schema accepts the file as a loose
-// object (`.passthrough()`) and only validates the two branches Pages
-// actually consume: `settings.color.palette` and
-// `settings.typography.fontFamilies`. Everything else rides through
-// unvalidated and is simply never read — this is not a reimplementation of
-// WP_Theme_JSON, just the safe slice that reaches presentation-only gate
-// pages.
+// The file is accepted as a loose object; only `settings.color.palette` and
+// `settings.typography.fontFamilies` are validated. Every other WP key rides
+// through unvalidated and is never read.
 const presetSlug = z
     .string()
     .min(1)

package/dist/contracts/transfers.d.ts

@@ -16,6 +16,7 @@ export declare const transferPrincipalSchema: z.ZodObject<{
     tenantId: z.ZodString;
 }, z.core.$strip>;
 export declare const spaceTransferCreateSchema: z.ZodObject<{
+    spaceId: z.ZodString;
     to: z.ZodObject<{
         principalType: z.ZodEnum<{
             team: "team";

package/dist/contracts/transfers.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { spaceTransferStatus } from "./enums.js";
-// Tenant-local external principal id grammar (internal-docs/platform.md
+// Tenant-local external principal id grammar (the platform spec
 // "Principal"): 1-256 chars, no whitespace, no `/` or `\`, no
 // control/non-printable characters. Team principal ids are Better Auth team
 // ids and trivially satisfy the same grammar.
@@ -15,7 +15,7 @@ export const principalIdSchema = z
 }))
     .describe("Tenant-local principal id: a team id or an integrator external customer id.");
 // Request `to` omits tenantId: transfers are tenant-local and the tenant is
-// inferred from the space (internal-docs/platform.md "Transfer semantics").
+// inferred from the space (the platform spec "Transfer semantics").
 export const transferPrincipalInputSchema = z.object({
     principalType: z
         .enum(["team", "external"])
@@ -27,6 +27,7 @@ export const transferPrincipalSchema = transferPrincipalInputSchema.extend({
     tenantId: z.string().min(1).describe("Tenant both transfer parties live in."),
 });
 export const spaceTransferCreateSchema = z.object({
+    spaceId: z.string().min(1).describe("Space to transfer (`spc_`)."),
     to: transferPrincipalInputSchema.describe("Receiving principal. Must live in the space's tenant; cross-tenant transfers are unsupported."),
 });
 export const spaceTransferSchema = z.object({

package/dist/contracts/usage.d.ts

@@ -59,3 +59,212 @@ export declare const functionUsagePushSchema: z.ZodObject<{
     observedAt: z.ZodString;
 }, z.core.$strip>;
 export type FunctionUsagePush = z.infer<typeof functionUsagePushSchema>;
+export declare const USAGE_DIMENSIONS: readonly ["data_transfer_bytes", "served_requests", "stored_byte_hours", "build_minutes", "build_count", "custom_domain_days", "space_days"];
+export declare const usageDimensionSchema: z.ZodEnum<{
+    data_transfer_bytes: "data_transfer_bytes";
+    served_requests: "served_requests";
+    stored_byte_hours: "stored_byte_hours";
+    build_minutes: "build_minutes";
+    build_count: "build_count";
+    custom_domain_days: "custom_domain_days";
+    space_days: "space_days";
+}>;
+export type UsageDimension = z.infer<typeof usageDimensionSchema>;
+export declare const usageQuantitySchema: z.ZodString;
+export declare const usageRecordSchema: z.ZodObject<{
+    usageRecordId: z.ZodString;
+    tenantId: z.ZodString;
+    principalType: z.ZodEnum<{
+        team: "team";
+        external: "external";
+    }>;
+    principalId: z.ZodString;
+    spaceId: z.ZodNullable<z.ZodString>;
+    bucketStart: z.ZodString;
+    bucketEnd: z.ZodString;
+    region: z.ZodNullable<z.ZodString>;
+    mode: z.ZodEnum<{
+        live: "live";
+        test: "test";
+    }>;
+    dimension: z.ZodEnum<{
+        data_transfer_bytes: "data_transfer_bytes";
+        served_requests: "served_requests";
+        stored_byte_hours: "stored_byte_hours";
+        build_minutes: "build_minutes";
+        build_count: "build_count";
+        custom_domain_days: "custom_domain_days";
+        space_days: "space_days";
+    }>;
+    measuredQuantity: z.ZodString;
+    billableQuantity: z.ZodString;
+    state: z.ZodEnum<{
+        final: "final";
+        estimated: "estimated";
+    }>;
+    corrects: z.ZodNullable<z.ZodString>;
+    correlationId: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+}, z.core.$strict>;
+export type UsageLedgerRecord = z.infer<typeof usageRecordSchema>;
+export declare const usageListQuerySchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+    from: z.ZodOptional<z.ZodString>;
+    to: z.ZodOptional<z.ZodString>;
+    principalId: z.ZodOptional<z.ZodString>;
+    spaceId: z.ZodOptional<z.ZodString>;
+    dimension: z.ZodOptional<z.ZodEnum<{
+        data_transfer_bytes: "data_transfer_bytes";
+        served_requests: "served_requests";
+        stored_byte_hours: "stored_byte_hours";
+        build_minutes: "build_minutes";
+        build_count: "build_count";
+        custom_domain_days: "custom_domain_days";
+        space_days: "space_days";
+    }>>;
+    granularity: z.ZodDefault<z.ZodLiteral<"hour">>;
+}, z.core.$strict>;
+export type UsageListQuery = z.infer<typeof usageListQuerySchema>;
+export declare const usageListResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        usageRecordId: z.ZodString;
+        tenantId: z.ZodString;
+        principalType: z.ZodEnum<{
+            team: "team";
+            external: "external";
+        }>;
+        principalId: z.ZodString;
+        spaceId: z.ZodNullable<z.ZodString>;
+        bucketStart: z.ZodString;
+        bucketEnd: z.ZodString;
+        region: z.ZodNullable<z.ZodString>;
+        mode: z.ZodEnum<{
+            live: "live";
+            test: "test";
+        }>;
+        dimension: z.ZodEnum<{
+            data_transfer_bytes: "data_transfer_bytes";
+            served_requests: "served_requests";
+            stored_byte_hours: "stored_byte_hours";
+            build_minutes: "build_minutes";
+            build_count: "build_count";
+            custom_domain_days: "custom_domain_days";
+            space_days: "space_days";
+        }>;
+        measuredQuantity: z.ZodString;
+        billableQuantity: z.ZodString;
+        state: z.ZodEnum<{
+            final: "final";
+            estimated: "estimated";
+        }>;
+        corrects: z.ZodNullable<z.ZodString>;
+        correlationId: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+    }, z.core.$strict>>;
+    pagination: z.ZodObject<{
+        nextCursor: z.ZodNullable<z.ZodString>;
+        hasMore: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const usagePeriodTotalsSchema: z.ZodObject<{
+    data_transfer_bytes: z.ZodOptional<z.ZodString>;
+    served_requests: z.ZodOptional<z.ZodString>;
+    stored_byte_hours: z.ZodOptional<z.ZodString>;
+    build_minutes: z.ZodOptional<z.ZodString>;
+    build_count: z.ZodOptional<z.ZodString>;
+    custom_domain_days: z.ZodOptional<z.ZodString>;
+    space_days: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const usagePeriodSchema: z.ZodObject<{
+    id: z.ZodString;
+    tenantId: z.ZodString;
+    mode: z.ZodEnum<{
+        live: "live";
+        test: "test";
+    }>;
+    periodStart: z.ZodString;
+    periodEnd: z.ZodString;
+    status: z.ZodEnum<{
+        final: "final";
+        open: "open";
+    }>;
+    totals: z.ZodObject<{
+        data_transfer_bytes: z.ZodOptional<z.ZodString>;
+        served_requests: z.ZodOptional<z.ZodString>;
+        stored_byte_hours: z.ZodOptional<z.ZodString>;
+        build_minutes: z.ZodOptional<z.ZodString>;
+        build_count: z.ZodOptional<z.ZodString>;
+        custom_domain_days: z.ZodOptional<z.ZodString>;
+        space_days: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    checksum: z.ZodNullable<z.ZodString>;
+    finalizedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type UsagePeriod = z.infer<typeof usagePeriodSchema>;
+export declare const usagePeriodListQuerySchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        live: "live";
+        test: "test";
+    }>>;
+}, z.core.$strict>;
+export declare const usagePeriodListResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        tenantId: z.ZodString;
+        mode: z.ZodEnum<{
+            live: "live";
+            test: "test";
+        }>;
+        periodStart: z.ZodString;
+        periodEnd: z.ZodString;
+        status: z.ZodEnum<{
+            final: "final";
+            open: "open";
+        }>;
+        totals: z.ZodObject<{
+            data_transfer_bytes: z.ZodOptional<z.ZodString>;
+            served_requests: z.ZodOptional<z.ZodString>;
+            stored_byte_hours: z.ZodOptional<z.ZodString>;
+            build_minutes: z.ZodOptional<z.ZodString>;
+            build_count: z.ZodOptional<z.ZodString>;
+            custom_domain_days: z.ZodOptional<z.ZodString>;
+            space_days: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        checksum: z.ZodNullable<z.ZodString>;
+        finalizedAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    pagination: z.ZodObject<{
+        nextCursor: z.ZodNullable<z.ZodString>;
+        hasMore: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const usagePeriodResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        id: z.ZodString;
+        tenantId: z.ZodString;
+        mode: z.ZodEnum<{
+            live: "live";
+            test: "test";
+        }>;
+        periodStart: z.ZodString;
+        periodEnd: z.ZodString;
+        status: z.ZodEnum<{
+            final: "final";
+            open: "open";
+        }>;
+        totals: z.ZodObject<{
+            data_transfer_bytes: z.ZodOptional<z.ZodString>;
+            served_requests: z.ZodOptional<z.ZodString>;
+            stored_byte_hours: z.ZodOptional<z.ZodString>;
+            build_minutes: z.ZodOptional<z.ZodString>;
+            build_count: z.ZodOptional<z.ZodString>;
+            custom_domain_days: z.ZodOptional<z.ZodString>;
+            space_days: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        checksum: z.ZodNullable<z.ZodString>;
+        finalizedAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strip>;

package/dist/contracts/usage.js

@@ -1,19 +1,16 @@
 import { z } from "zod";
+import { CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
 /**
  * Resolutions the hosting provider keeps usage at. Hour is retained about a
  * week, day about two months, month about two years.
  */
 export const USAGE_RESOLUTIONS = ["hour", "day", "month"];
 export const usageResolutionSchema = z.enum(USAGE_RESOLUTIONS);
-// Served by `GET /v1/spaces/{spaceId}/usage`: what one Space actually consumed,
-// measured by the infrastructure that served it rather than derived from what
-// was published.
+// Served by `GET /v1/spaces/{spaceId}/usage`: what one Space consumed, measured
+// by the infrastructure that served it.
 //
-// Every number here is a MEASUREMENT OF A PAST PERIOD, not a live gauge, and the
-// contract says so out loud: `period` is the window measured and `sampledAt` is
-// when we last asked. Nothing in this response means "right now". The meter
-// behind it is a time series with real ingestion delay, so a reading is only
-// trusted once its period has settled — expect the period to end an hour or so
+// Every number measures a past period, never "right now". The meter behind it
+// has real ingestion delay, so expect the measured period to end an hour or so
 // before you read it.
 export const spaceUsageMeasurementSchema = z.object({
     period: z
@@ -47,12 +44,11 @@ export const spaceUsageResponseSchema = z.object({
     spaceId: z.string().describe("The space the usage was measured for."),
     usage: spaceUsageMeasurementSchema
         .nullable()
-        .describe("Null when this space has never been measured — a space that has not served yet, or one whose first measurement period has not settled."),
+        .describe("Null when this space has never been measured, either because it has not served yet or because its first measurement period has not settled."),
 });
 // Posted by the Functions host's tail Worker after an isolate finishes serving.
-// Counts only — never messages. Function LOGS travel a different path, into the
-// space's own log stream, and merging the two would quietly turn this into a
-// second log pipeline.
+// Counts only, never messages. Function logs travel a different path, into the
+// space's own log stream.
 export const functionUsagePushSchema = z.object({
     spaceId: z.string().min(1).describe("The space whose functions ran."),
     versionId: z.string().min(1).describe("The version whose bundle served the requests."),
@@ -62,3 +58,119 @@ export const functionUsagePushSchema = z.object({
         .string()
         .describe("The reporter's clock at delivery. The control plane buckets by hour on receipt."),
 });
+export const USAGE_DIMENSIONS = [
+    "data_transfer_bytes",
+    "served_requests",
+    "stored_byte_hours",
+    "build_minutes",
+    "build_count",
+    "custom_domain_days",
+    "space_days",
+];
+export const usageDimensionSchema = z
+    .enum(USAGE_DIMENSIONS)
+    .describe("Meter that produced this usage record.");
+export const usageQuantitySchema = z
+    .string()
+    .regex(/^-?[0-9]+$/)
+    .describe("Signed integer quantity in the dimension's normalized unit.");
+export const usageRecordSchema = z
+    .object({
+    usageRecordId: z.string().describe("Immutable usage record id."),
+    tenantId: z.string().describe("Tenant that owns the charge."),
+    principalType: z.enum(["external", "team"]).describe("Principal type for attribution."),
+    principalId: z.string().describe("Stable principal id for attribution."),
+    spaceId: z.string().nullable().describe("Space that produced the usage, when applicable."),
+    bucketStart: z.string().datetime().describe("Start of the UTC measurement bucket."),
+    bucketEnd: z.string().datetime().describe("End of the UTC measurement bucket."),
+    region: z.string().nullable().describe("Serving region that measured the usage."),
+    mode: z.enum(["live", "test"]).describe("Tenant mode that produced the usage."),
+    dimension: usageDimensionSchema,
+    measuredQuantity: usageQuantitySchema.describe("Quantity the meter observed."),
+    billableQuantity: usageQuantitySchema.describe("Quantity billed after included usage and credits. Test usage is always zero."),
+    state: z.enum(["estimated", "final"]).describe("Whether the measurement can still settle."),
+    corrects: z
+        .string()
+        .nullable()
+        .describe("Earlier usage record corrected by this append-only record."),
+    correlationId: z
+        .string()
+        .nullable()
+        .describe("Request or event id that caused this usage, when applicable."),
+    createdAt: z.string().datetime().describe("Time the ledger appended this record."),
+})
+    .strict()
+    .describe("One immutable usage ledger record.");
+export const usageListQuerySchema = cursorListQuerySchema
+    .extend({
+    from: z.string().datetime().optional().describe("Include buckets that end after this instant."),
+    to: z
+        .string()
+        .datetime()
+        .optional()
+        .describe("Include buckets that start before this instant."),
+    principalId: z
+        .string()
+        .trim()
+        .min(1)
+        .max(255)
+        .optional()
+        .describe("Return only records billed to this external principal."),
+    spaceId: z
+        .string()
+        .trim()
+        .min(1)
+        .max(64)
+        .optional()
+        .describe("Return only records for this space."),
+    dimension: usageDimensionSchema.optional(),
+    granularity: z
+        .literal("hour")
+        .default("hour")
+        .describe("Ledger bucket granularity. Version 1 records hourly buckets."),
+})
+    .strict();
+export const usageListResponseSchema = z.object({
+    data: z.array(usageRecordSchema),
+    pagination: CursorPaginationSchema,
+});
+export const usagePeriodTotalsSchema = z
+    .object({
+    data_transfer_bytes: usageQuantitySchema.optional(),
+    served_requests: usageQuantitySchema.optional(),
+    stored_byte_hours: usageQuantitySchema.optional(),
+    build_minutes: usageQuantitySchema.optional(),
+    build_count: usageQuantitySchema.optional(),
+    custom_domain_days: usageQuantitySchema.optional(),
+    space_days: usageQuantitySchema.optional(),
+})
+    .strict();
+export const usagePeriodSchema = z
+    .object({
+    id: z.string().describe("Billing period id."),
+    tenantId: z.string().describe("Tenant that owns this billing period."),
+    mode: z.enum(["live", "test"]),
+    periodStart: z.string().datetime(),
+    periodEnd: z.string().datetime(),
+    status: z.enum(["open", "final"]),
+    totals: usagePeriodTotalsSchema,
+    checksum: z
+        .string()
+        .nullable()
+        .describe("SHA-256 checksum of frozen final totals. Open periods have no checksum."),
+    finalizedAt: z.string().datetime().nullable(),
+})
+    .strict();
+export const usagePeriodListQuerySchema = cursorListQuerySchema
+    .extend({
+    mode: z
+        .enum(["live", "test"])
+        .optional()
+        .describe("Return periods for the live tenant or its linked test tenant."),
+})
+    .strict();
+export const usagePeriodListResponseSchema = z.object({
+    data: z.array(usagePeriodSchema),
+    pagination: CursorPaginationSchema,
+});
+export const usagePeriodResponseSchema = z.object({ data: usagePeriodSchema });

package/dist/contracts/variables.d.ts

@@ -124,7 +124,7 @@ export declare const variableMutationResponseSchema: z.ZodObject<{
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
                 registrar: "registrar";
-                wpcloud: "wpcloud";
+                infra: "infra";
                 dns: "dns";
                 runtime: "runtime";
             }>>>;
@@ -168,7 +168,7 @@ export declare const variableDeleteResponseSchema: z.ZodObject<{
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
                 registrar: "registrar";
-                wpcloud: "wpcloud";
+                infra: "infra";
                 dns: "dns";
                 runtime: "runtime";
             }>>>;

package/dist/contracts/variables.js

@@ -1,10 +1,9 @@
 import { z } from "zod";
 import { AsyncOperationSchema, CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
-// Variable (internal-docs/platform.md "Product Data Shapes"): one model for
-// every scope. Resolution order at finalize is space -> principal. A space IS
-// a site, so a space variable is the site variable — there is no third scope
-// underneath it. Secret values are write-only after creation: never returned
-// by API, CLI, UI, diagnostics, logs, or activity.
+// One model for every scope. Resolution order at finalize is space ->
+// principal; a space IS a site, so there is no third scope underneath. Secret
+// values are write-only after creation: never returned by API, CLI, UI,
+// diagnostics, logs, or activity.
 export const variableScope = z.enum(["space", "principal"]);
 export const variableNameSchema = z
     .string()
@@ -28,11 +27,10 @@ export const VariableSchema = z.object({
     createdAt: z.string().datetime().describe("Instant when the variable was created."),
     updatedAt: z.string().datetime().describe("Instant when the value was last written."),
 });
-// Version provenance (internal-docs/platform.md "Variable rules"): versions
-// record which variable names and value hashes they were finalized with —
-// never values. Stored only for internal cascade and synchronization; it is
-// never echoed on the public Version resource because historical rows cannot
-// distinguish sealed-value hashes safely.
+// Versions record the variable names and value hashes they were finalized
+// with, never values. Internal to cascade and synchronization: never echoed on
+// the public Version resource, because historical rows cannot distinguish
+// sealed-value hashes safely.
 export const variableProvenanceSchema = z
     .array(z.object({
     name: z.string().describe("Variable name the version was finalized with."),
@@ -66,9 +64,7 @@ export const spaceVariableListResponseSchema = z.object({
     data: z.array(z.union([VariableSchema, SystemVariableSchema])),
     pagination: CursorPaginationSchema,
 });
-// Variable mutations return the debounced cascade operation
-// (internal-docs/platform.md "Debounce contract"): every coalesced PUT/DELETE
-// returns the same pending `op_` id, so "mutation returns `operation`" holds.
+// Every coalesced PUT/DELETE returns the same pending `op_` id.
 export const variableMutationResponseSchema = z.object({
     data: VariableSchema,
     operation: AsyncOperationSchema.nullable().describe("The debounced re-finalize cascade this write coalesced into; null when no cascade was required."),

package/dist/contracts/webhooks.d.ts

@@ -15,6 +15,10 @@ export declare const webhookPatchSchema: z.ZodObject<{
 export declare const webhookSchema: z.ZodObject<{
     id: z.ZodString;
     tenantId: z.ZodString;
+    mode: z.ZodEnum<{
+        live: "live";
+        test: "test";
+    }>;
     principal: z.ZodNullable<z.ZodObject<{
         tenantId: z.ZodString;
         principalType: z.ZodEnum<{
@@ -27,8 +31,8 @@ export declare const webhookSchema: z.ZodObject<{
     events: z.ZodArray<z.ZodString>;
     status: z.ZodEnum<{
         active: "active";
-        deleted: "deleted";
         disabled: "disabled";
+        deleted: "deleted";
         failing: "failing";
     }>;
     secret: z.ZodOptional<z.ZodString>;
@@ -45,6 +49,10 @@ export declare const webhookListResponseSchema: z.ZodObject<{
     data: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         tenantId: z.ZodString;
+        mode: z.ZodEnum<{
+            live: "live";
+            test: "test";
+        }>;
         principal: z.ZodNullable<z.ZodObject<{
             tenantId: z.ZodString;
             principalType: z.ZodEnum<{
@@ -57,8 +65,8 @@ export declare const webhookListResponseSchema: z.ZodObject<{
         events: z.ZodArray<z.ZodString>;
         status: z.ZodEnum<{
             active: "active";
-            deleted: "deleted";
             disabled: "disabled";
+            deleted: "deleted";
             failing: "failing";
         }>;
         secret: z.ZodOptional<z.ZodString>;
@@ -72,7 +80,7 @@ export declare const webhookListResponseSchema: z.ZodObject<{
         hasMore: z.ZodBoolean;
     }, z.core.$strip>;
 }, z.core.$strip>;
-export declare const webhookRotateSecretSchema: z.ZodObject<{
+export declare const webhookRotateSchema: z.ZodObject<{
     expireNow: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 export declare const webhookDeliverySchema: z.ZodObject<{
@@ -101,7 +109,7 @@ export declare const webhookDeliverySchema: z.ZodObject<{
         path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
             registrar: "registrar";
-            wpcloud: "wpcloud";
+            infra: "infra";
             dns: "dns";
             runtime: "runtime";
         }>>>;
@@ -142,7 +150,7 @@ export declare const webhookDeliveryListResponseSchema: z.ZodObject<{
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
                 registrar: "registrar";
-                wpcloud: "wpcloud";
+                infra: "infra";
                 dns: "dns";
                 runtime: "runtime";
             }>>>;