@spacefast/common 0.0.26 → 0.2.1

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

@@ -117,8 +117,8 @@ export declare const variableMutationResponseSchema: z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
                 info: "info";
-                error: "error";
                 warning: "warning";
+                error: "error";
             }>;
             message: z.ZodString;
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -161,8 +161,8 @@ export declare const variableDeleteResponseSchema: z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
                 info: "info";
-                error: "error";
                 warning: "warning";
+                error: "error";
             }>;
             message: z.ZodString;
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;

package/dist/contracts/variables.js

@@ -1,10 +1,9 @@
 import { z } from "zod";
 import { AsyncOperationSchema, CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
-// Variable (the platform spec "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 (the platform spec "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
-// (the platform spec "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<{
@@ -94,8 +102,8 @@ export declare const webhookDeliverySchema: z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
             info: "info";
-            error: "error";
             warning: "warning";
+            error: "error";
         }>;
         message: z.ZodString;
         path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -135,8 +143,8 @@ export declare const webhookDeliveryListResponseSchema: z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
                 info: "info";
-                error: "error";
                 warning: "warning";
+                error: "error";
             }>;
             message: z.ZodString;
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;

package/dist/contracts/webhooks.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { baseDiagnosticSchema, CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
+import { tenantMode } from "./enums.js";
 export const webhookCreateSchema = z.object({
     teamId: z.string().min(1).optional(),
     url: z.string().url(),
@@ -15,6 +16,7 @@ export const webhookPatchSchema = z
 export const webhookSchema = z.object({
     id: z.string(),
     tenantId: z.string(),
+    mode: tenantMode.describe("`test` when the owning tenant is a linked test tenant, `live` otherwise."),
     principal: z
         .object({
         tenantId: z.string(),
@@ -36,7 +38,7 @@ export const webhookListResponseSchema = z.object({
     data: z.array(webhookSchema),
     pagination: CursorPaginationSchema,
 });
-export const webhookRotateSecretSchema = z.object({
+export const webhookRotateSchema = z.object({
     expireNow: z.boolean().default(false),
 });
 export const webhookDeliverySchema = z.object({