@spacefast/common 0.0.2

package/dist/contracts/api-keys.js

@@ -0,0 +1,235 @@
+import { z } from "zod";
+import { AnyObjectSchema, CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
+export const SPACEFAST_ACCESS_POLICY_VERSION = "2026-06-09";
+export const StatticActionSchema = z.enum([
+    "sites:read",
+    "sites:create",
+    "sites:write",
+    "sites:delete",
+    "sites:policy.write",
+    "spaces:read",
+    "spaces:create",
+    "spaces:write",
+    "spaces:delete",
+    "spaces:publish",
+    "spaces:transfer",
+    "spaces:export",
+    "spaces:import",
+    "versions:read",
+    "versions:promote",
+    "versions:delete",
+    "versions:download",
+    "domains:read",
+    "domains:create",
+    "domains:verify",
+    "domains:assign",
+    "domains:bind",
+    "domains:delete",
+    "domains:dns.write",
+    "domains:dns.credentials.write",
+    "domains:purchase",
+    "webhooks:read",
+    "webhooks:write",
+    "builds:read",
+    "builds:create",
+    "teams:read",
+    "teams:write",
+    "teams:members.write",
+    "billing:read",
+    "billing:write",
+    "tokens:read",
+    "tokens:create",
+    "tokens:revoke",
+    "mcp:tools",
+    "runtime:manage",
+    "*",
+]);
+const DescribedStatticActionSchema = StatticActionSchema.describe("A namespaced IAM-lite action (`noun:verb`) or `*` for all actions.");
+const RESOURCE_PREFIX = "stt://tenant/";
+function isResourceSegment(value) {
+    return Boolean(value && value.length > 0 && !/[\s/\\]/.test(value));
+}
+export function parseStatticResource(value) {
+    if (!value.startsWith(RESOURCE_PREFIX) || value.length > 512) {
+        return null;
+    }
+    const segments = value.slice(RESOURCE_PREFIX.length).split("/");
+    const tenantId = segments.shift();
+    if (!isResourceSegment(tenantId)) {
+        return null;
+    }
+    if (segments.length === 0) {
+        return { kind: "tenant", tenantId };
+    }
+    const wildcard = segments.at(-1) === "*";
+    const path = wildcard ? segments.slice(0, -1) : segments;
+    const [head, a, b, c] = path;
+    if (head === "principal" && (a === "team" || a === "external") && isResourceSegment(b)) {
+        if (path.length !== 3) {
+            return null;
+        }
+        return { kind: "principal", tenantId, principalType: a, principalId: b, wildcard };
+    }
+    if (head === "site" && isResourceSegment(a)) {
+        if (path.length === 2) {
+            return { kind: "site", tenantId, siteId: a, wildcard };
+        }
+        if (path.length === 4 && b === "space" && isResourceSegment(c)) {
+            return { kind: "space", tenantId, siteId: a, spaceId: c, wildcard };
+        }
+        return null;
+    }
+    if (head === "domain" && isResourceSegment(a) && path.length === 2 && !wildcard) {
+        return { kind: "domain", tenantId, domainId: a };
+    }
+    if (head === "domain-group" && isResourceSegment(a) && path.length === 2 && !wildcard) {
+        return { kind: "domain-group", tenantId, domainGroupId: a };
+    }
+    return null;
+}
+const StatticResourceSchema = z
+    .string()
+    .max(512)
+    .refine((value) => parseStatticResource(value) !== null, {
+    message: "Resource must be a stt:// URI from the StatticResource union (tenant, principal, site, site space, domain, or domain-group).",
+})
+    .describe("A resource URI from the StatticResource union: stt://tenant/{t}, …/principal/(team|external)/{id}[/*], …/site/{id}[/*], …/site/{id}/space/{id}[/*], …/domain/{id}, or …/domain-group/{id}.");
+export const StatticAccessPolicySchema = z
+    .object({
+    version: z
+        .literal(SPACEFAST_ACCESS_POLICY_VERSION)
+        .describe("Policy schema version. Must be the current platform policy version."),
+    statements: z
+        .array(z
+        .object({
+        effect: z
+            .enum(["allow", "deny"])
+            .describe("Statement effect. Explicit deny always wins over allow."),
+        actions: z
+            .array(DescribedStatticActionSchema)
+            .min(1)
+            .describe("Actions this statement covers."),
+        resources: z
+            .array(StatticResourceSchema)
+            .min(1)
+            .describe("Resource URIs this statement covers (wildcards cover subtrees)."),
+        conditions: z
+            .object({
+            "request.client": z
+                .enum(["dashboard", "cli", "api", "worker"])
+                .optional()
+                .describe("Restricts the statement to one resolved request client."),
+        })
+            .strict()
+            .optional()
+            .describe("ANDed condition attributes. Unresolvable attributes fail closed: no-match for allow, match for deny."),
+    })
+        .strict())
+        .min(1)
+        .describe("Evaluation: explicit deny wins, explicit allow permits, otherwise implicit deny."),
+})
+    .strict()
+    .describe("IAM-lite access policy evaluated for every credentialed request.");
+export const ApiKeyPresetSchema = z
+    .enum([
+    "ci_deploy",
+    "space_publisher",
+    "space_admin",
+    "site_admin",
+    "domain_manager",
+    "team_admin",
+    "billing_viewer",
+])
+    .describe("Named policy preset compiled into a concrete access policy at key creation.");
+// `system` is never a principal type: runtime/internal credentials are
+// platform-owned and omit ownerPrincipal entirely (internal-docs/platform.md).
+const ApiKeyOwnerPrincipalSchema = z.object({
+    type: z.enum(["team", "external"]).describe("Principal type that owns this key."),
+    id: z.string().min(1).describe("Stable principal id (Better Auth team id or external id)."),
+});
+const ApiKeySubjectSchema = z.object({
+    type: z
+        .enum(["user", "team", "external", "system"])
+        .describe("Subject kind the key acts as in audit records."),
+    id: z.string().min(1).describe("Stable subject id."),
+});
+export const ApiKeySchema = z.object({
+    id: z.string().describe("API key id."),
+    name: z.string().nullable().describe("Human-readable key name."),
+    tenantId: z.string().nullable().describe("Tenant the key belongs to."),
+    subject: ApiKeySubjectSchema.nullable().describe("Subject the key acts as."),
+    ownerPrincipal: ApiKeyOwnerPrincipalSchema.nullable().describe("Owning principal (ownership metadata, never the authorization gate)."),
+    createdByUserId: z.string().describe("User who created the key."),
+    preset: ApiKeyPresetSchema.nullable().describe("Preset the policy was compiled from, if any."),
+    policy: StatticAccessPolicySchema.nullable().describe("Effective access policy. A key authorizes by policy only."),
+    metadata: AnyObjectSchema.describe("Caller-supplied metadata."),
+    secretPreview: z.string().describe("Masked secret preview (prefix and last characters)."),
+    secret: z.string().optional().describe("Full secret. Returned once, at creation only."),
+    notBefore: z.string().datetime().nullable().describe("Key is rejected before this instant."),
+    expiresAt: z.string().datetime().nullable().describe("Key is rejected from this instant."),
+    ipAllowlist: z
+        .array(z.string())
+        .nullable()
+        .describe("CIDR/IP allowlist. Requests from other addresses are rejected."),
+    revokedAt: z.string().datetime().nullable().describe("Revocation instant, if revoked."),
+    enabled: z.boolean().describe("Whether the key currently authenticates."),
+    createdAt: z.string().datetime().describe("Creation instant."),
+    updatedAt: z.string().datetime().describe("Last update instant."),
+    lastRequestAt: z.string().datetime().nullable().describe("Last authenticated request instant."),
+});
+export const ApiKeyListQuerySchema = cursorListQuerySchema.extend({
+    teamId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Owning team whose keys to list. Defaults to the caller's own team; any team the credential's policy reaches is allowed."),
+});
+export const ApiKeyListResponseSchema = z.object({
+    data: z.array(ApiKeySchema),
+    pagination: CursorPaginationSchema,
+});
+export const ApiKeyCreateRequestSchema = z.object({
+    name: z.string().trim().min(1).max(255).optional().describe("Human-readable key name."),
+    teamId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Owning team for the new key. Defaults to the caller's own team; authorization is by the credential's policy, not key ownership."),
+    preset: ApiKeyPresetSchema.optional(),
+    policy: StatticAccessPolicySchema.nullable()
+        .optional()
+        .describe("Explicit policy. Must be a subset of the calling credential's policy."),
+    metadata: AnyObjectSchema.optional().describe("Caller-supplied metadata."),
+    ipAllowlist: z
+        .array(z.string().trim().min(1).max(255))
+        .max(100)
+        .nullable()
+        .optional()
+        .describe("CIDR/IP allowlist for the new key."),
+    expiresAt: z.string().datetime().nullable().optional().describe("Expiry instant."),
+    notBefore: z.string().datetime().nullable().optional().describe("Activation instant."),
+});
+export const ApiKeyPatchRequestSchema = z
+    .object({
+    metadata: AnyObjectSchema.optional().describe("Replacement caller-supplied metadata."),
+    ipAllowlist: z
+        .array(z.string().trim().min(1).max(255))
+        .max(100)
+        .nullable()
+        .optional()
+        .describe("Replacement CIDR/IP allowlist."),
+    expiresAt: z.string().datetime().nullable().optional().describe("Replacement expiry instant."),
+    notBefore: z
+        .string()
+        .datetime()
+        .nullable()
+        .optional()
+        .describe("Replacement activation instant."),
+    policy: StatticAccessPolicySchema.optional().describe("Replacement policy. Must be a subset of the calling credential's policy at mutation time."),
+})
+    .refine((value) => Object.keys(value).length > 0, {
+    message: "At least one mutable API key field is required.",
+});
+export const ApiKeyParamsSchema = z.object({
+    apiKeyId: z.string().min(1).describe("API key id."),
+});

package/dist/contracts/archives.d.ts

@@ -0,0 +1,332 @@
+import { z } from "zod";
+export declare const archiveListQuerySchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const spaceExportRequestSchema: z.ZodObject<{
+    versionIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    includeFiles: z.ZodDefault<z.ZodBoolean>;
+    includeExplicitConfig: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const spaceExportArchiveSchema: z.ZodObject<{
+    contentType: z.ZodLiteral<"application/zip">;
+    downloadUrl: z.ZodString;
+    expiresAt: z.ZodString;
+    sizeBytes: z.ZodOptional<z.ZodNumber>;
+    sha256: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const spaceExportSchema: z.ZodObject<{
+    id: z.ZodString;
+    spaceId: z.ZodString;
+    status: z.ZodEnum<{
+        failed: "failed";
+        queued: "queued";
+        running: "running";
+        ready: "ready";
+        expired: "expired";
+    }>;
+    format: z.ZodLiteral<"stattic_export_v1">;
+    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>>>;
+    archive: z.ZodOptional<z.ZodObject<{
+        contentType: z.ZodLiteral<"application/zip">;
+        downloadUrl: z.ZodString;
+        expiresAt: z.ZodString;
+        sizeBytes: z.ZodOptional<z.ZodNumber>;
+        sha256: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    operationId: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export declare const spaceExportListResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        spaceId: z.ZodString;
+        status: z.ZodEnum<{
+            failed: "failed";
+            queued: "queued";
+            running: "running";
+            ready: "ready";
+            expired: "expired";
+        }>;
+        format: z.ZodLiteral<"stattic_export_v1">;
+        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>>>;
+        archive: z.ZodOptional<z.ZodObject<{
+            contentType: z.ZodLiteral<"application/zip">;
+            downloadUrl: z.ZodString;
+            expiresAt: z.ZodString;
+            sizeBytes: z.ZodOptional<z.ZodNumber>;
+            sha256: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        operationId: 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 spaceImportSourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"upload">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"url">;
+    url: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"export">;
+    exportId: z.ZodString;
+}, z.core.$strip>], "kind">;
+export declare const spaceImportRequestSchema: z.ZodObject<{
+    source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"upload">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"url">;
+        url: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"export">;
+        exportId: z.ZodString;
+    }, z.core.$strip>], "kind">;
+    publish: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const spaceImportSchema: z.ZodObject<{
+    id: z.ZodString;
+    targetSpaceId: z.ZodString;
+    status: z.ZodEnum<{
+        failed: "failed";
+        canceled: "canceled";
+        ready: "ready";
+        created: "created";
+        waiting_for_archive: "waiting_for_archive";
+        validating: "validating";
+        materializing: "materializing";
+    }>;
+    archiveUpload: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        mode: z.ZodEnum<{
+            dist: "dist";
+            source: "source";
+        }>;
+        expiresAt: z.ZodString;
+        summary: z.ZodObject<{
+            upload: z.ZodNumber;
+            reused: z.ZodNumber;
+            ignored: z.ZodNumber;
+        }, z.core.$strip>;
+        targets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            method: z.ZodEnum<{
+                PUT: "PUT";
+                POST: "POST";
+            }>;
+            url: z.ZodUnion<[z.ZodString, z.ZodString]>;
+            headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+            body: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"url">;
+                url: z.ZodString;
+            }, z.core.$strip>], "kind">>;
+            size: z.ZodOptional<z.ZodNumber>;
+            maxBytes: z.ZodOptional<z.ZodNumber>;
+            sha256: z.ZodOptional<z.ZodString>;
+            contentType: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        links: z.ZodObject<{
+            resume: z.ZodString;
+            finalize: z.ZodString;
+        }, z.core.$strip>;
+        details: z.ZodOptional<z.ZodObject<{
+            reused: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                reason: z.ZodString;
+            }, z.core.$strip>>>;
+            ignored: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                reason: z.ZodString;
+            }, 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>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    draftVersionIds: z.ZodArray<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>>>;
+    operationId: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export declare const spaceImportListResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        targetSpaceId: z.ZodString;
+        status: z.ZodEnum<{
+            failed: "failed";
+            canceled: "canceled";
+            ready: "ready";
+            created: "created";
+            waiting_for_archive: "waiting_for_archive";
+            validating: "validating";
+            materializing: "materializing";
+        }>;
+        archiveUpload: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            mode: z.ZodEnum<{
+                dist: "dist";
+                source: "source";
+            }>;
+            expiresAt: z.ZodString;
+            summary: z.ZodObject<{
+                upload: z.ZodNumber;
+                reused: z.ZodNumber;
+                ignored: z.ZodNumber;
+            }, z.core.$strip>;
+            targets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                method: z.ZodEnum<{
+                    PUT: "PUT";
+                    POST: "POST";
+                }>;
+                url: z.ZodUnion<[z.ZodString, z.ZodString]>;
+                headers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+                body: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"url">;
+                    url: z.ZodString;
+                }, z.core.$strip>], "kind">>;
+                size: z.ZodOptional<z.ZodNumber>;
+                maxBytes: z.ZodOptional<z.ZodNumber>;
+                sha256: z.ZodOptional<z.ZodString>;
+                contentType: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            links: z.ZodObject<{
+                resume: z.ZodString;
+                finalize: z.ZodString;
+            }, z.core.$strip>;
+            details: z.ZodOptional<z.ZodObject<{
+                reused: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    path: z.ZodString;
+                    reason: z.ZodString;
+                }, z.core.$strip>>>;
+                ignored: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    path: z.ZodString;
+                    reason: z.ZodString;
+                }, 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>>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        draftVersionIds: z.ZodArray<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>>>;
+        operationId: 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 type SpaceExport = z.infer<typeof spaceExportSchema>;
+export type SpaceImport = z.infer<typeof spaceImportSchema>;

package/dist/contracts/archives.js

@@ -0,0 +1,120 @@
+import { z } from "zod";
+import { baseDiagnosticSchema, CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
+import { uploadInstructionsSchema } from "./internal.js";
+export const archiveListQuerySchema = cursorListQuerySchema;
+export const spaceExportRequestSchema = z.object({
+    versionIds: z
+        .array(z.string().min(1))
+        .min(1)
+        .optional()
+        .describe("Version ids (ver_…) to export. Every id must belong to the space; omit to export all versions."),
+    includeFiles: z
+        .boolean()
+        .default(true)
+        .describe("Include version file trees and compiled serving artifacts. `false` produces a config-only archive that is not self-servable and cannot be re-imported."),
+    includeExplicitConfig: z
+        .boolean()
+        .default(true)
+        .describe("Include explicit space config (the space access policy) in the archive. Version manifests are always included."),
+});
+export const spaceExportArchiveSchema = z.object({
+    // Zip-only contract: stattic_export_v1 archives are always zip (the spec
+    // allows "zip or tar"; one format keeps the enum honest).
+    contentType: z.literal("application/zip").describe("Archive media type. Always zip."),
+    downloadUrl: z
+        .string()
+        .describe("API-relative URL streaming the archive while it has not expired."),
+    expiresAt: z
+        .string()
+        .datetime()
+        .describe("When the archive download expires; the export flips to `expired` afterwards."),
+    sizeBytes: z.number().int().nonnegative().optional().describe("Archive size in bytes."),
+    sha256: z
+        .string()
+        .optional()
+        .describe("SHA-256 of the archive bytes (64 lowercase hex characters), for verification."),
+});
+export const spaceExportSchema = z.object({
+    id: z.string().describe("Export handle id (exp_…)."),
+    spaceId: z.string().describe("Source space id (spc_…)."),
+    status: z
+        .enum(["queued", "running", "ready", "failed", "expired"])
+        .describe("Export lifecycle. `expired` means the archive download window has passed."),
+    format: z.literal("stattic_export_v1").describe("Archive format identifier."),
+    diagnostics: z
+        .array(baseDiagnosticSchema)
+        .default([])
+        .describe("Diagnostics collected while producing the export."),
+    archive: spaceExportArchiveSchema
+        .optional()
+        .describe("Archive download details; present only while status is `ready`."),
+    operationId: z
+        .string()
+        .nullable()
+        .describe("Operation (op_…) tracking the asynchronous export work."),
+    createdAt: z.string().datetime().describe("When the export handle was created."),
+    updatedAt: z.string().datetime().describe("When the export handle last changed."),
+});
+export const spaceExportListResponseSchema = z.object({
+    data: z.array(spaceExportSchema),
+    pagination: CursorPaginationSchema,
+});
+export const spaceImportSourceSchema = z
+    .discriminatedUnion("kind", [
+    z.object({
+        kind: z
+            .literal("upload")
+            .describe("Upload an archive; the response carries `archiveUpload` instructions."),
+    }),
+    z.object({
+        kind: z.literal("url").describe("Fetch the archive from a public HTTPS URL."),
+        url: z.string().url().describe("Public HTTPS URL of a stattic_export_v1 archive."),
+    }),
+    z.object({
+        kind: z.literal("export").describe("Import directly from an export on this control plane."),
+        exportId: z.string().min(1).describe("Source export id (exp_…) accessible to the caller."),
+    }),
+])
+    .describe("Where the stattic_export_v1 archive comes from.");
+export const spaceImportRequestSchema = z.object({
+    source: spaceImportSourceSchema,
+    publish: z
+        .boolean()
+        .default(false)
+        .describe("Promote the newest imported version to the live channel once materialized. Imported versions never go public implicitly."),
+});
+export const spaceImportSchema = z.object({
+    id: z.string().describe("Import handle id (imp_…)."),
+    targetSpaceId: z.string().describe("Target space id (spc_…) the import materializes into."),
+    status: z
+        .enum([
+        "created",
+        "waiting_for_archive",
+        "validating",
+        "materializing",
+        "ready",
+        "failed",
+        "canceled",
+    ])
+        .describe("Import lifecycle. Upload-kind imports wait in `waiting_for_archive` until the archive is uploaded and the import is finalized."),
+    archiveUpload: uploadInstructionsSchema
+        .optional()
+        .describe("Archive upload instructions — the same upload contract as publish. Present while status is `waiting_for_archive`: PUT the archive to `{baseUrl}/{files[0]}` with the session token, then POST `links.finalize`. Each fetch of the import re-mints a fresh token."),
+    draftVersionIds: z
+        .array(z.string())
+        .describe("Version ids (ver_…) minted and owned by this import."),
+    diagnostics: z
+        .array(baseDiagnosticSchema)
+        .default([])
+        .describe("Diagnostics collected during validation and materialization, including warnings for imported config overridden by the target space/parent policy."),
+    operationId: z
+        .string()
+        .nullable()
+        .describe("Operation (op_…) tracking the asynchronous import work."),
+    createdAt: z.string().datetime().describe("When the import handle was created."),
+    updatedAt: z.string().datetime().describe("When the import handle last changed."),
+});
+export const spaceImportListResponseSchema = z.object({
+    data: z.array(spaceImportSchema),
+    pagination: CursorPaginationSchema,
+});