@spacefast/common 0.0.2

package/dist/contracts/variables.d.ts

@@ -0,0 +1,189 @@
+import { z } from "zod";
+export declare const variableScope: z.ZodEnum<{
+    principal: "principal";
+    space: "space";
+    site: "site";
+}>;
+export declare const variableNameSchema: z.ZodString;
+export declare const VariableSchema: z.ZodObject<{
+    name: z.ZodString;
+    scope: z.ZodEnum<{
+        principal: "principal";
+        space: "space";
+        site: "site";
+    }>;
+    secret: z.ZodBoolean;
+    value: z.ZodOptional<z.ZodString>;
+    channelValues: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type Variable = z.infer<typeof VariableSchema>;
+export declare const variableProvenanceSchema: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    valueHash: z.ZodString;
+}, z.core.$strip>>;
+export type VariableProvenance = z.infer<typeof variableProvenanceSchema>;
+export declare function variableResourceId(scope: z.infer<typeof variableScope>, name: string): string;
+export declare const SystemVariableSchema: z.ZodObject<{
+    name: z.ZodString;
+    value: z.ZodString;
+    scope: z.ZodLiteral<"system">;
+}, z.core.$strip>;
+export declare const variableUpsertSchema: z.ZodObject<{
+    name: z.ZodString;
+    value: z.ZodString;
+    secret: z.ZodOptional<z.ZodBoolean>;
+    channelValues: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export declare const variableValueUpsertSchema: z.ZodObject<{
+    value: z.ZodString;
+    secret: z.ZodOptional<z.ZodBoolean>;
+    channelValues: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export declare const variableListQuerySchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const variableListResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        scope: z.ZodEnum<{
+            principal: "principal";
+            space: "space";
+            site: "site";
+        }>;
+        secret: z.ZodBoolean;
+        value: z.ZodOptional<z.ZodString>;
+        channelValues: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strip>>;
+    pagination: z.ZodObject<{
+        nextCursor: z.ZodNullable<z.ZodString>;
+        hasMore: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const spaceVariableListResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        name: z.ZodString;
+        scope: z.ZodEnum<{
+            principal: "principal";
+            space: "space";
+            site: "site";
+        }>;
+        secret: z.ZodBoolean;
+        value: z.ZodOptional<z.ZodString>;
+        channelValues: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodString;
+        scope: z.ZodLiteral<"system">;
+    }, z.core.$strip>]>>;
+    pagination: z.ZodObject<{
+        nextCursor: z.ZodNullable<z.ZodString>;
+        hasMore: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const variableMutationResponseSchema: z.ZodObject<{
+    data: z.ZodObject<{
+        name: z.ZodString;
+        scope: z.ZodEnum<{
+            principal: "principal";
+            space: "space";
+            site: "site";
+        }>;
+        secret: z.ZodBoolean;
+        value: z.ZodOptional<z.ZodString>;
+        channelValues: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strip>;
+    operation: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodString;
+        status: z.ZodEnum<{
+            failed: "failed";
+            queued: "queued";
+            running: "running";
+            succeeded: "succeeded";
+            canceled: "canceled";
+        }>;
+        resources: z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            id: z.ZodString;
+        }, z.core.$strip>>;
+        progress: z.ZodOptional<z.ZodObject<{
+            total: z.ZodNumber;
+            completed: z.ZodNumber;
+            failed: z.ZodNumber;
+        }, z.core.$strip>>;
+        diagnostics: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            code: z.ZodString;
+            severity: z.ZodEnum<{
+                info: "info";
+                warning: "warning";
+                error: "error";
+            }>;
+            message: z.ZodString;
+            path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                wpcloud: "wpcloud";
+                dns: "dns";
+                registrar: "registrar";
+                runtime: "runtime";
+            }>>>;
+            details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+            fix: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            retryable: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        }, z.core.$strip>>>;
+        createdAt: z.ZodString;
+        finishedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const variableDeleteResponseSchema: z.ZodObject<{
+    data: z.ZodNull;
+    operation: z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodString;
+        status: z.ZodEnum<{
+            failed: "failed";
+            queued: "queued";
+            running: "running";
+            succeeded: "succeeded";
+            canceled: "canceled";
+        }>;
+        resources: z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            id: z.ZodString;
+        }, z.core.$strip>>;
+        progress: z.ZodOptional<z.ZodObject<{
+            total: z.ZodNumber;
+            completed: z.ZodNumber;
+            failed: z.ZodNumber;
+        }, z.core.$strip>>;
+        diagnostics: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            code: z.ZodString;
+            severity: z.ZodEnum<{
+                info: "info";
+                warning: "warning";
+                error: "error";
+            }>;
+            message: z.ZodString;
+            path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                wpcloud: "wpcloud";
+                dns: "dns";
+                registrar: "registrar";
+                runtime: "runtime";
+            }>>>;
+            details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+            fix: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            retryable: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        }, z.core.$strip>>>;
+        createdAt: z.ZodString;
+        finishedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;

package/dist/contracts/variables.js

@@ -0,0 +1,82 @@
+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 -> site.
+// Secret values are write-only after creation: never returned by API, CLI,
+// UI, diagnostics, logs, or activity.
+export const variableScope = z.enum(["space", "principal", "site"]);
+export const variableNameSchema = z
+    .string()
+    .min(1)
+    .max(128)
+    .regex(/^[A-Za-z_][A-Za-z0-9_]*$/, {
+    message: "Variable names must start with a letter or underscore and contain only letters, numbers, and underscores.",
+})
+    .refine((name) => !name.toUpperCase().startsWith("SPACEFAST_"), {
+    message: "Variable names starting with SPACEFAST_ are reserved.",
+});
+export const VariableSchema = z.object({
+    name: variableNameSchema.describe("Variable name, referenced as {{ vars.NAME }} in templates."),
+    scope: variableScope.describe("Where the variable is defined; space wins over principal/site."),
+    secret: z.boolean().describe("Secret values are write-only and never returned after creation."),
+    value: z.string().optional().describe("Variable value; omitted when secret=true."),
+    channelValues: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe("Per-channel overrides compiled into channel template variants; omitted for secrets."),
+    createdAt: z.string().datetime().describe("When the variable was created."),
+    updatedAt: z.string().datetime().describe("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 on the version row and echoed on the Version resource;
+// the cascade discovers affected spaces through it.
+export const variableProvenanceSchema = z
+    .array(z.object({
+    name: z.string().describe("Variable name the version was finalized with."),
+    valueHash: z
+        .string()
+        .describe("sha256 of the resolved value at finalize time. Never the value itself."),
+}))
+    .describe("Variable names + value hashes baked into this version at finalize. Never values.");
+// Operation `resources` entry id for a coalesced variable write
+// (internal-docs/platform.md "Debounce contract"): `{scope}/{name}`.
+export function variableResourceId(scope, name) {
+    return `${scope}/${name}`;
+}
+// Platform-provided, read-only values (SPACEFAST_*) surfaced alongside stored
+// variables on list reads. Not persistable and not a Variable scope.
+export const SystemVariableSchema = z.object({
+    name: z.string(),
+    value: z.string(),
+    scope: z.literal("system").describe("Platform-provided, read-only variable."),
+});
+export const variableUpsertSchema = z.object({
+    name: variableNameSchema,
+    value: z.string().min(1),
+    secret: z.boolean().optional().describe("Mark the value write-only. Defaults to false."),
+    channelValues: z.record(z.string(), z.string()).optional(),
+});
+export const variableValueUpsertSchema = variableUpsertSchema.omit({ name: true });
+export const variableListQuerySchema = cursorListQuerySchema;
+export const variableListResponseSchema = z.object({
+    data: z.array(VariableSchema),
+    pagination: CursorPaginationSchema,
+});
+// Space variable lists interleave platform-provided SPACEFAST_* values with the
+// stored variables visible to the space (space scope plus principal scope).
+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.
+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."),
+});
+export const variableDeleteResponseSchema = z.object({
+    data: z.null().describe("Variable deletes return no resource body."),
+    operation: AsyncOperationSchema.nullable().describe("The debounced re-finalize cascade this delete coalesced into; null when no cascade was required."),
+});

package/dist/contracts/webhooks.d.ts

@@ -0,0 +1,159 @@
+import { z } from "zod";
+export declare const webhookCreateSchema: z.ZodObject<{
+    teamId: z.ZodOptional<z.ZodString>;
+    url: z.ZodString;
+    events: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const webhookPatchSchema: z.ZodObject<{
+    url: z.ZodOptional<z.ZodString>;
+    events: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        disabled: "disabled";
+    }>>;
+}, z.core.$strip>;
+export declare const webhookSchema: z.ZodObject<{
+    id: z.ZodString;
+    tenantId: z.ZodString;
+    principal: z.ZodNullable<z.ZodObject<{
+        tenantId: z.ZodString;
+        principalType: z.ZodEnum<{
+            external: "external";
+            team: "team";
+        }>;
+        principalId: z.ZodString;
+    }, z.core.$strip>>;
+    url: z.ZodString;
+    events: z.ZodArray<z.ZodString>;
+    status: z.ZodEnum<{
+        active: "active";
+        disabled: "disabled";
+        failing: "failing";
+    }>;
+    secret: z.ZodOptional<z.ZodString>;
+    secretPreview: z.ZodString;
+    previousSecretExpiresAt: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export declare const webhookListQuerySchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const webhookListResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        tenantId: z.ZodString;
+        principal: z.ZodNullable<z.ZodObject<{
+            tenantId: z.ZodString;
+            principalType: z.ZodEnum<{
+                external: "external";
+                team: "team";
+            }>;
+            principalId: z.ZodString;
+        }, z.core.$strip>>;
+        url: z.ZodString;
+        events: z.ZodArray<z.ZodString>;
+        status: z.ZodEnum<{
+            active: "active";
+            disabled: "disabled";
+            failing: "failing";
+        }>;
+        secret: z.ZodOptional<z.ZodString>;
+        secretPreview: z.ZodString;
+        previousSecretExpiresAt: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strip>>;
+    pagination: z.ZodObject<{
+        nextCursor: z.ZodNullable<z.ZodString>;
+        hasMore: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const webhookRotateSecretSchema: z.ZodObject<{
+    expireNow: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const webhookDeliverySchema: z.ZodObject<{
+    id: z.ZodString;
+    webhookId: z.ZodString;
+    eventId: z.ZodString;
+    status: z.ZodEnum<{
+        failed: "failed";
+        succeeded: "succeeded";
+        pending: "pending";
+        exhausted: "exhausted";
+    }>;
+    attempts: z.ZodNumber;
+    lastAttemptAt: z.ZodNullable<z.ZodString>;
+    lastResponseStatus: z.ZodNullable<z.ZodNumber>;
+    nextRetryAt: z.ZodNullable<z.ZodString>;
+    redeliveredFromId: z.ZodNullable<z.ZodString>;
+    diagnostics: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        severity: z.ZodEnum<{
+            info: "info";
+            warning: "warning";
+            error: "error";
+        }>;
+        message: z.ZodString;
+        path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            wpcloud: "wpcloud";
+            dns: "dns";
+            registrar: "registrar";
+            runtime: "runtime";
+        }>>>;
+        details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        fix: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        retryable: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    }, z.core.$strip>>>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+export declare const webhookDeliveryListQuerySchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const webhookDeliveryListResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        webhookId: z.ZodString;
+        eventId: z.ZodString;
+        status: z.ZodEnum<{
+            failed: "failed";
+            succeeded: "succeeded";
+            pending: "pending";
+            exhausted: "exhausted";
+        }>;
+        attempts: z.ZodNumber;
+        lastAttemptAt: z.ZodNullable<z.ZodString>;
+        lastResponseStatus: z.ZodNullable<z.ZodNumber>;
+        nextRetryAt: z.ZodNullable<z.ZodString>;
+        redeliveredFromId: z.ZodNullable<z.ZodString>;
+        diagnostics: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            code: z.ZodString;
+            severity: z.ZodEnum<{
+                info: "info";
+                warning: "warning";
+                error: "error";
+            }>;
+            message: z.ZodString;
+            path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                wpcloud: "wpcloud";
+                dns: "dns";
+                registrar: "registrar";
+                runtime: "runtime";
+            }>>>;
+            details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+            fix: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            retryable: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+        }, z.core.$strip>>>;
+        createdAt: z.ZodString;
+    }, z.core.$strip>>;
+    pagination: z.ZodObject<{
+        nextCursor: z.ZodNullable<z.ZodString>;
+        hasMore: z.ZodBoolean;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type Webhook = z.infer<typeof webhookSchema>;
+export type WebhookDelivery = z.infer<typeof webhookDeliverySchema>;

package/dist/contracts/webhooks.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { baseDiagnosticSchema, CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
+export const webhookCreateSchema = z.object({
+    teamId: z.string().min(1).optional(),
+    url: z.string().url(),
+    events: z.array(z.string().min(1)).min(1).default(["*"]),
+});
+export const webhookPatchSchema = z
+    .object({
+    url: z.string().url().optional(),
+    events: z.array(z.string().min(1)).min(1).optional(),
+    status: z.enum(["active", "disabled"]).optional(),
+})
+    .refine((value) => Object.keys(value).length > 0, "At least one field is required.");
+export const webhookSchema = z.object({
+    id: z.string(),
+    tenantId: z.string(),
+    principal: z
+        .object({
+        tenantId: z.string(),
+        principalType: z.enum(["team", "external"]),
+        principalId: z.string(),
+    })
+        .nullable(),
+    url: z.string().url(),
+    events: z.array(z.string()),
+    status: z.enum(["active", "disabled", "failing"]),
+    secret: z.string().optional(),
+    secretPreview: z.string(),
+    previousSecretExpiresAt: z.string().datetime().nullable(),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+});
+export const webhookListQuerySchema = cursorListQuerySchema;
+export const webhookListResponseSchema = z.object({
+    data: z.array(webhookSchema),
+    pagination: CursorPaginationSchema,
+});
+export const webhookRotateSecretSchema = z.object({
+    expireNow: z.boolean().default(false),
+});
+export const webhookDeliverySchema = z.object({
+    id: z.string(),
+    webhookId: z.string(),
+    eventId: z.string(),
+    status: z.enum(["pending", "succeeded", "failed", "exhausted"]),
+    attempts: z.number().int().nonnegative(),
+    lastAttemptAt: z.string().datetime().nullable(),
+    lastResponseStatus: z.number().int().nullable(),
+    nextRetryAt: z.string().datetime().nullable(),
+    redeliveredFromId: z.string().nullable(),
+    diagnostics: z.array(baseDiagnosticSchema).default([]),
+    createdAt: z.string().datetime(),
+});
+export const webhookDeliveryListQuerySchema = webhookListQuerySchema;
+export const webhookDeliveryListResponseSchema = z.object({
+    data: z.array(webhookDeliverySchema),
+    pagination: CursorPaginationSchema,
+});