@spacefast/common 0.0.2

package/dist/contracts/common.js

@@ -0,0 +1,175 @@
+import { z } from "zod";
+import { diagnosticProvider, diagnosticSeverity, operationStatus } from "./enums.js";
+export const AnyObjectSchema = z.record(z.string(), z.unknown());
+export const SpaceViewerSchema = z.object({
+    title: z.string().nullable(),
+    description: z.string().nullable(),
+    ogImagePath: z.string().nullable(),
+});
+// The ONE Diagnostic shape (internal-docs/platform.md L1616-1623). Every lifecycle
+// resource (versions, builds, bindings, assignments, exports, imports, transfers)
+// carries `diagnostics: Diagnostic[]` using exactly this vocabulary.
+export const baseDiagnosticSchema = z.object({
+    code: z
+        .string()
+        .describe("Stable snake_case diagnostic code naming the public contract that produced it."),
+    severity: diagnosticSeverity.describe("How actionable the diagnostic is: info, warning, error."),
+    message: z.string().describe("Human-readable explanation with enough detail to act on."),
+    path: z
+        .string()
+        .nullish()
+        .describe('Artifact path the diagnostic points at, e.g. "_headers:12", when one exists.'),
+    provider: diagnosticProvider
+        .nullish()
+        .describe("Upstream system the diagnostic originated from, when not Spacefast itself."),
+    details: AnyObjectSchema.nullish().describe("Machine-readable context for the diagnostic code."),
+    fix: z
+        .string()
+        .nullish()
+        .describe("Concrete, agent-actionable remediation hint for this diagnostic (react-doctor model), when one can be derived."),
+    retryable: z
+        .boolean()
+        .nullish()
+        .describe("Whether retrying the same operation may resolve this diagnostic without the caller changing anything."),
+});
+// Canonical DnsInstruction (internal-docs/platform.md L2500-2506): provider vocabulary
+// never leaks into `purpose`.
+export const DnsInstructionSchema = z.object({
+    type: z.enum(["A", "AAAA", "CNAME", "TXT", "ALIAS"]),
+    name: z.string().describe("Record name to create, relative to the zone."),
+    value: z.string().describe("Exact record value to set."),
+    ttl: z.number().int().optional(),
+    purpose: z.enum(["verification", "routing", "ssl"]).describe("Why this record is needed."),
+});
+// One shared requiredActions vocabulary (internal-docs/platform.md L2512-2517 + L1807-1811):
+// lifecycle resources expose the concrete user steps that unblock them. New action types are
+// added HERE, never as per-resource variants.
+export const requiredActionSchema = z.discriminatedUnion("type", [
+    z
+        .object({
+        type: z.literal("dns"),
+        instructions: z.array(DnsInstructionSchema),
+    })
+        .describe("Create the listed DNS records at the caller's DNS provider."),
+    z
+        .object({ type: z.literal("confirm_move"), conflictId: z.string() })
+        .describe("Confirm taking the hostname over from the conflicting binding."),
+    z
+        .object({ type: z.literal("verify_domain"), domainId: z.string() })
+        .describe("Complete domain ownership verification."),
+    z
+        .object({ type: z.literal("renew"), domainId: z.string() })
+        .describe("Renew the expired or expiring domain registration."),
+]);
+export const requiredActionsSchema = z
+    .array(requiredActionSchema)
+    .describe("Concrete user steps that unblock this resource, using the one shared vocabulary.");
+// The error envelope (internal-docs/platform.md "Global API Conventions"): `docsUrl` is
+// mandatory and derived from `code` (see contracts/error-codes.ts); `param` is a
+// JSON-path-lite pointer into the failing request field on validation failures.
+export const ApiErrorResponseSchema = z.object({
+    error: z.object({
+        code: z.string().describe("Stable snake_case error code naming the failed public contract."),
+        message: z.string().describe("Human-readable failure explanation."),
+        param: z
+            .string()
+            .optional()
+            .describe('JSON-path-lite pointer into the failing request field, e.g. "files[37].path", on validation failures.'),
+        docsUrl: z
+            .string()
+            .describe("Always present; derived mechanically from `code` against the docs origin."),
+        details: AnyObjectSchema.optional().describe("Machine-readable context for the error code."),
+        suggestions: z
+            .array(z.string())
+            .optional()
+            .describe("Actionable recovery steps safe to show in dashboards, SDKs, and CLI output."),
+        requestId: z.string().optional().describe("Request id to quote when contacting support."),
+    }),
+});
+// Success envelope (internal-docs/platform.md "Global API Conventions"): `{ data: T }` for
+// single resources and mutations, `{ data: T[], pagination }` for lists. Mutations whose work
+// outlives the request also carry `operation` — wrap with `.extend({ operation: ... })`.
+export function dataEnvelope(data) {
+    return z.object({ data });
+}
+export const ApiUploadInstructionSchema = z
+    .object({
+    id: z.string().describe("Upload session id (`upl_…`)."),
+    expiresAt: z.string().datetime(),
+    method: z.literal("PUT"),
+    url: z
+        .string()
+        .url()
+        .or(z.string().startsWith("/"))
+        .describe("Absolute or API-relative URL to PUT the bytes to."),
+    contentType: z.string().min(1),
+    maxBytes: z.number().int().positive(),
+})
+    .describe("Generic API upload instruction used by resources that need caller-supplied bytes.");
+export const CursorPaginationSchema = z.object({
+    nextCursor: z
+        .string()
+        .nullable()
+        .describe("Opaque cursor for the next page; pass as `?cursor=`. Null on the last page."),
+    hasMore: z.boolean().describe("Whether another page exists after this one."),
+});
+// The ONE list query shape (default 20, max 100, opaque cursor, newest-first). Extend with
+// module-specific filters; never redeclare `limit`/`cursor`.
+export const cursorListQuerySchema = z.object({
+    limit: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .default(20)
+        .describe("Page size: default 20, maximum 100."),
+    cursor: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Opaque cursor from a previous page's `pagination.nextCursor`."),
+});
+// The operator-only offset list-response shape (superadmin surfaces): the named
+// items array, plus `total`/`limit`/`offset` and the offset `pagination` block.
+// Callers pass the items key, item schema, and their pagination schema so the
+// emitted object is byte-for-byte the hand-written
+// `z.object({ <key>: z.array(...), total, limit, offset, pagination })`.
+export function makeOffsetListSchema(itemsKey, item, pagination) {
+    return z.object({
+        [itemsKey]: z.array(item),
+        total: z.number().int().nonnegative(),
+        limit: z.number().int().positive(),
+        offset: z.number().int().nonnegative(),
+        pagination,
+    });
+}
+export const AsyncOperationProgressSchema = z.object({
+    stage: z.string().nullable().optional(),
+    message: z.string().nullable().optional(),
+    nextCheckAt: z.string().datetime().nullable().optional(),
+});
+export const OperationProgressSchema = z.object({
+    total: z.number().int().nonnegative(),
+    completed: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+});
+export const AsyncOperationSchema = z.object({
+    id: z.string(),
+    kind: z.string(),
+    status: operationStatus,
+    resources: z.array(z.object({ type: z.string(), id: z.string() })),
+    progress: OperationProgressSchema.optional(),
+    diagnostics: z.array(baseDiagnosticSchema).optional(),
+    createdAt: z.string().datetime(),
+    finishedAt: z.string().datetime().optional(),
+});
+// Mutation envelope for async-capable verbs: the post-mutation resource in `data`
+// plus `operation` when work outlives the request (poll the resource or the
+// operation). `operation` is always present and null when the mutation completed
+// synchronously, so the wire shape is deterministic per route.
+export function mutationEnvelope(data) {
+    return z.object({
+        data,
+        operation: AsyncOperationSchema.nullable().describe("Background operation handle when asynchronous work remains after this mutation; null when it completed synchronously."),
+    });
+}