@spacefast/common 0.0.2

package/dist/contracts/spaces.js

@@ -0,0 +1,589 @@
+import { z } from "zod";
+import { AsyncOperationSchema, baseDiagnosticSchema, CursorPaginationSchema, cursorListQuerySchema, } from "./common.js";
+import { versionStatus, spaceStatus } from "./enums.js";
+import { conventionFilesSchema, uploadInstructionsSchema, manifestFileSchema } from "./internal.js";
+import { ChannelPointerSchema, VersionSchema, PublishSourceSchema, SpaceSchema, } from "./resources.js";
+import { spaceConfigSchema } from "./space-config.js";
+import { principalIdSchema } from "./transfers.js";
+import { zeroRuntimeKindSchema } from "./zero.js";
+export const AnonymousSpaceAccessSchema = z.object({
+    claimToken: z
+        .string()
+        .nullable()
+        .describe("One-time, space-scoped credential returned only at anonymous space creation. Save it immediately — it is never shown again and is required to publish and manage the space until it is claimed."),
+    claimUrl: z
+        .string()
+        .nullable()
+        .describe("Browser-only link that lets a human log in with WordPress.com and claim this space into an team. Not an API credential."),
+    expiresAt: z
+        .string()
+        .datetime()
+        .nullable()
+        .describe("When the unclaimed space expires if nobody publishes to it or claims it."),
+    warning: z
+        .string()
+        .describe("Human-readable notice explaining that the space is anonymous and will expire unless claimed."),
+});
+export const SpaceCreateResponseSchema = z.object({
+    space: SpaceSchema,
+    anonymousAccess: AnonymousSpaceAccessSchema.optional(),
+});
+// Stored per-version diagnostic surfaced on the space diagnostics feed: the shared
+// Diagnostic shape (contracts/common.ts) plus persistence identity.
+export const spaceDiagnosticSchema = baseDiagnosticSchema.extend({
+    id: z.string().describe("Stable diagnostic record id."),
+    versionId: z.string().describe("Version the diagnostic was recorded against."),
+    createdAt: z.string().datetime(),
+});
+export const spaceDiagnosticListResponseSchema = z.object({
+    data: z.array(spaceDiagnosticSchema),
+    pagination: CursorPaginationSchema,
+});
+export const principalRefInputSchema = z.object({
+    type: z.enum(["team", "external"]).describe("Owning principal kind."),
+    id: principalIdSchema,
+});
+export const spaceCreateSchema = z
+    .object({
+    // `siteId` selects the static site the space lives under. Optional today:
+    // when omitted the tenant's default static site is resolved (internal-docs/platform.md "Site
+    // Context Resolution"). Spaces are valid only under static sites.
+    siteId: z.string().min(1).optional(),
+    teamId: z.string().nullable().optional(),
+    principal: principalRefInputSchema.optional(),
+    slug: z.string().min(2).max(55).optional(),
+    title: z.string().min(1).max(255).optional(),
+    config: spaceConfigSchema.optional().describe("Initial SpaceConfig overlay for the new space."),
+    dataLocation: z.string().min(1).optional(),
+})
+    .superRefine((value, ctx) => {
+    if (value.teamId && value.principal?.type === "team" && value.teamId !== value.principal.id) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "teamId must match principal.id when principal.type is team.",
+            path: ["principal", "id"],
+        });
+    }
+})
+    .optional()
+    .default({});
+export const spacePatchSchema = z.object({
+    title: z.string().min(1).max(255).optional(),
+    config: spaceConfigSchema
+        .nullable()
+        .optional()
+        .describe("Replaces the stored SpaceConfig overlay; null clears it."),
+    dataLocation: z.string().min(1).optional(),
+    noindex: z
+        .boolean()
+        .optional()
+        .describe("Hide the live production site from search engines. Applies only to claimed spaces' live hostnames; preview and version hostnames are always noindex."),
+    password: z
+        .string()
+        .min(1)
+        .max(255)
+        .nullable()
+        .optional()
+        .describe("Sets (string) or removes (null) space password protection."),
+});
+export const spaceClaimSchema = z
+    .object({
+    claimToken: z
+        .string()
+        .min(1)
+        .describe("One-time claim token returned at anonymous creation. Rides the body, never URLs; claiming revokes it."),
+    teamId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Team receiving the space. Inferred when you belong to exactly one team; otherwise required (`team_required`)."),
+    targetTeamId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Alias of teamId; must match when both are provided."),
+})
+    .superRefine((value, ctx) => {
+    if (value.teamId && value.targetTeamId && value.teamId !== value.targetTeamId) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["teamId"],
+            message: "teamId and targetTeamId must match when both are provided.",
+        });
+    }
+});
+export const spaceClaimReminderSchema = z.object({
+    email: z
+        .string()
+        .email()
+        .max(320)
+        .describe("Expiry-reminder address for an unclaimed anonymous space. Stored only until the space is claimed or expires, then deleted; never logged."),
+});
+export const spaceClaimReminderResponseSchema = z.object({
+    accepted: z.literal(true),
+});
+export const spaceVersionCreateSchema = z
+    .object({
+    source: PublishSourceSchema.optional().describe('Publish provenance recorded on the version; defaults to {kind: "direct_upload"}.'),
+    publishMode: z
+        .enum(["additive", "snapshot"])
+        .default("additive")
+        .describe("How to interpret omitted paths in files: additive retains existing paths unless explicitly replaced; snapshot treats files as the complete desired manifest."),
+    sourceMetadata: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("Additional control-plane-only provenance for build/deploy read models."),
+    buildLog: z
+        .string()
+        .max(64_000)
+        .optional()
+        .describe("Bounded build transcript for deploys that ran a local build before publishing."),
+    files: z
+        .array(manifestFileSchema)
+        .optional()
+        .describe("Full desired file manifest. For first deploys, send path/size/contentType without hashes so upload can begin immediately. For updates, include sha256 to let the server skip unchanged files. Omit entirely for an open session: the upload token then authorizes any policy-valid path within plan caps and finalize derives the manifest from what was uploaded."),
+    deletePaths: z
+        .array(z.string().min(1))
+        .default([])
+        .describe("Explicit paths to remove when publishMode is additive. Omitted paths are retained; only paths listed here are deleted."),
+})
+    .superRefine((value, ctx) => {
+    if (value.files === undefined && value.deletePaths.length > 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "deletePaths requires a declared files manifest.",
+            path: ["deletePaths"],
+        });
+    }
+});
+export const spaceVersionListSchema = z.object({
+    data: z.array(VersionSchema),
+    pagination: CursorPaginationSchema,
+});
+export const spaceListSchema = z.object({
+    data: z.array(SpaceSchema),
+    pagination: CursorPaginationSchema,
+});
+export const spaceListQuerySchema = cursorListQuerySchema.extend({
+    team: z.string().min(1).optional().describe("Filter to spaces owned by this team id or slug."),
+});
+export const spaceVersionListQuerySchema = cursorListQuerySchema;
+// Version processing log lines (upload/finalize/promote output), newest-first.
+export const versionLogEntrySchema = z.object({
+    timestamp: z.string().datetime().describe("When the version last changed state."),
+    level: z.string().describe("Log severity: info or error."),
+    code: z.string().describe("Stable version.{status} code for the line."),
+    message: z.string().describe("Human-readable log line."),
+});
+export const VERSION_BUILD_LOG_MAX_LENGTH = 512 * 1024;
+export const versionLogListResponseSchema = z.object({
+    data: z.array(versionLogEntrySchema),
+    pagination: CursorPaginationSchema,
+});
+export const spaceVersionGeneratedPreviewSchema = z.object({
+    kind: z.literal("image"),
+    status: z.enum(["ready", "pending"]),
+    key: z.string(),
+    cacheScope: z.enum(["hash", "version-path"]),
+    contentType: z.literal("image/webp"),
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+});
+export const spaceVersionFileSchema = manifestFileSchema.extend({
+    previewable: z.boolean(),
+    generatedPreview: spaceVersionGeneratedPreviewSchema.nullable(),
+});
+export const spaceVersionFileIndexEntrySchema = z.object({
+    key: z.string(),
+    selector: z.discriminatedUnion("kind", [
+        z.object({ kind: z.literal("hash"), sha256: z.string() }),
+        z.object({ kind: z.literal("path"), path: z.string() }),
+    ]),
+    primaryPath: z.string(),
+    paths: z.array(z.string()),
+    count: z.number().int().nonnegative(),
+    size: z.number().int().nonnegative(),
+    totalBytes: z.number().int().nonnegative(),
+    contentTypes: z.array(z.string()),
+    previewable: z.boolean(),
+    generatedPreview: spaceVersionGeneratedPreviewSchema.nullable(),
+    searchText: z.string(),
+});
+export const spaceVersionFileIndexSchema = z.object({
+    entries: z.array(spaceVersionFileIndexEntrySchema),
+    byHash: z.record(z.string(), spaceVersionFileIndexEntrySchema),
+    byPath: z.record(z.string(), spaceVersionFileIndexEntrySchema),
+});
+export const spaceVersionFilesQuerySchema = z.object({
+    q: z.string().trim().min(1).max(255).optional(),
+});
+export const spaceVersionFilesSearchSchema = z.object({
+    query: z.string().nullable(),
+    total: z.number().int().nonnegative(),
+    matched: z.number().int().nonnegative(),
+});
+export const spaceVersionFilesResponseSchema = z.object({
+    versionId: z.string(),
+    files: z.array(spaceVersionFileSchema),
+    index: spaceVersionFileIndexSchema,
+    search: spaceVersionFilesSearchSchema,
+});
+export const spaceFilesResponseSchema = z.object({
+    channel: z.literal("live"),
+    versionId: z.string().nullable(),
+    files: z.array(spaceVersionFileSchema),
+    index: spaceVersionFileIndexSchema,
+    search: spaceVersionFilesSearchSchema,
+});
+export const spaceVersionFileQuerySchema = z.object({
+    path: z.string().min(1),
+    download: z.string().optional(),
+});
+export const spaceVersionFileResponseSchema = z.object({
+    versionId: z.string(),
+    path: z.string(),
+    size: z.number().int().nonnegative(),
+    contentType: z.string().nullable(),
+    sha256: z.string().nullable(),
+    encoding: z.enum(["utf8", "base64"]),
+    content: z.string(),
+    truncated: z.boolean(),
+    cached: z.boolean(),
+});
+export const spaceVersionFileDirectUrlResponseSchema = z.object({
+    versionId: z.string(),
+    path: z.string(),
+    url: z.string().url(),
+    managementHostname: z.string(),
+    expiresInSeconds: z.number().int().positive(),
+});
+export const spaceVersionFileUrlPreviewSchema = z.object({
+    versionId: z.string(),
+    path: z.string(),
+    sha256: z.string().nullable(),
+    source: z.enum(["internet-shortcut", "webloc", "plain-url"]),
+    url: z.string().url(),
+    fetchedUrl: z.string().url().nullable(),
+    title: z.string().nullable(),
+    description: z.string().nullable(),
+    siteName: z.string().nullable(),
+    providerName: z.string().nullable(),
+    authorName: z.string().nullable(),
+    imageUrl: z.string().url().nullable(),
+    oEmbedUrl: z.string().url().nullable(),
+    status: z.enum(["ready", "unavailable"]),
+    cached: z.boolean(),
+});
+export const spaceVersionConventionArtifactKindSchema = z.enum(["redirects", "headers"]);
+export const spaceVersionConventionArtifactPathSchema = z.enum(["_redirects", "_headers"]);
+export const spaceVersionConventionArtifactSourceSchema = z.enum([
+    "uploaded",
+    "inherited",
+    "override",
+    "generated",
+    "missing",
+]);
+export const spaceVersionConventionArtifactMetadataSchema = z.object({
+    kind: spaceVersionConventionArtifactKindSchema,
+    path: spaceVersionConventionArtifactPathSchema,
+    source: spaceVersionConventionArtifactSourceSchema,
+    present: z.boolean(),
+    size: z.number().int().nonnegative().nullable(),
+    sha256: z.string().nullable(),
+    contentType: z.string().nullable(),
+    compiledRuleCount: z.number().int().nonnegative(),
+    warningCount: z.number().int().nonnegative(),
+    errorCount: z.number().int().nonnegative(),
+});
+export const spaceVersionConventionArtifactsResponseSchema = z.object({
+    versionId: z.string(),
+    artifacts: z.array(spaceVersionConventionArtifactMetadataSchema),
+});
+export const spaceVersionConventionArtifactQuerySchema = z.object({
+    kind: spaceVersionConventionArtifactKindSchema.optional(),
+    path: spaceVersionConventionArtifactPathSchema.optional(),
+});
+export const spaceVersionConventionArtifactContentResponseSchema = spaceVersionConventionArtifactMetadataSchema.extend({
+    encoding: z.enum(["utf8", "base64"]),
+    content: z.string(),
+    truncated: z.boolean(),
+});
+export const spaceVersionRoutingDiagnosticSchema = z.object({
+    file: spaceVersionConventionArtifactPathSchema,
+    line: z.number().int().nonnegative(),
+    severity: z.enum(["warning", "error"]),
+    code: z.string(),
+    message: z.string(),
+    source: z.string(),
+});
+export const spaceVersionComputedRoutingSummarySchema = z.object({
+    versionId: z.string(),
+    source: z.object({
+        artifacts: z.array(spaceVersionConventionArtifactMetadataSchema),
+    }),
+    compiled: z.object({
+        redirectRuleCount: z.number().int().nonnegative(),
+        headerRuleCount: z.number().int().nonnegative(),
+        staticRedirectCount: z.number().int().nonnegative(),
+        dynamicRedirectCount: z.number().int().nonnegative(),
+        basicAuthRuleCount: z.number().int().nonnegative(),
+        proxyRuleCount: z.number().int().nonnegative(),
+    }),
+    diagnostics: z.array(spaceVersionRoutingDiagnosticSchema),
+});
+export const spaceVersionFileDiffStatusSchema = z.enum([
+    "added",
+    "modified",
+    "deleted",
+    "renamed",
+    "unchanged",
+    "binary",
+    "too_large",
+]);
+export const spaceVersionFileDiffEntrySchema = z.object({
+    path: z.string(),
+    oldPath: z.string().nullable(),
+    status: spaceVersionFileDiffStatusSchema,
+    before: spaceVersionFileSchema.nullable(),
+    after: spaceVersionFileSchema.nullable(),
+    patch: z
+        .object({
+        format: z.literal("unified"),
+        content: z.string(),
+        truncated: z.boolean(),
+    })
+        .nullable(),
+});
+export const spaceVersionFileDiffQuerySchema = z.object({
+    baseVersionId: z.string().optional(),
+});
+export const spaceVersionFileDiffResponseSchema = z.object({
+    versionId: z.string(),
+    baseVersionId: z.string().nullable(),
+    files: z.array(spaceVersionFileDiffEntrySchema),
+});
+// Upload state is inferable (internal-docs/platform.md L2216): `upload` present means bytes are
+// still needed (then finalize); `versionId` null means the manifest matched and nothing changed.
+// No redundant booleans ride along.
+export const spaceVersionIntentResponseSchema = z.object({
+    versionId: z
+        .string()
+        .nullable()
+        .describe("Created version id, or null when the manifest matched and nothing changed."),
+    upload: uploadInstructionsSchema
+        .nullable()
+        .describe("Runtime upload session, present only while bytes still need uploading. Upload, then finalize."),
+    ignoredPaths: z
+        .array(z.string())
+        .default([])
+        .describe("Manifest paths ignored by the server because the current plan does not allow them."),
+});
+export const publishRequestSchema = z
+    .object({
+    spaceId: z.string().min(1).optional(),
+    siteId: z.string().min(1).optional(),
+    teamId: z.string().nullable().optional(),
+    principal: principalRefInputSchema.optional(),
+    files: z
+        .array(manifestFileSchema)
+        .optional()
+        .describe("Desired file manifest for a declared publish session. Clients upload returned paths, then finalize. Omit for inline one-shot and open-session publishes."),
+    deletePaths: z
+        .array(z.string().min(1))
+        .default([])
+        .describe("Explicit paths to remove when publishMode is additive. Omitted paths are retained; only paths listed here are deleted."),
+    source: PublishSourceSchema.optional().describe('Publish provenance recorded on the version; defaults to {kind: "direct_upload"}.'),
+    publishMode: z
+        .enum(["additive", "snapshot"])
+        .default("additive")
+        .describe("How to interpret omitted paths in files: additive retains existing paths unless explicitly replaced; snapshot treats files as the complete desired manifest."),
+    email: z
+        .string()
+        .email()
+        .max(320)
+        .optional()
+        .describe("Optional expiry-reminder address for anonymous publishes. Stored only until the space is claimed or expires, then deleted; never logged."),
+    channel: z
+        .enum(["live"])
+        .nullable()
+        .optional()
+        .describe("Omit for live publish, or pass null to create a ready version without promotion."),
+    space: z
+        .object({
+        slug: z.string().min(2).max(55).optional(),
+        title: z.string().min(1).max(255).optional(),
+        dataLocation: z.string().min(1).optional(),
+    })
+        .optional(),
+    config: spaceConfigSchema
+        .optional()
+        .describe("SpaceConfig overlay to store on the space (sf.jsonc contents)."),
+})
+    .superRefine((value, ctx) => {
+    if (value.teamId && value.principal?.type === "team" && value.teamId !== value.principal.id) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "teamId must match principal.id when principal.type is team.",
+            path: ["principal", "id"],
+        });
+    }
+    if (value.files === undefined && value.deletePaths.length > 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "deletePaths requires a declared files manifest.",
+            path: ["deletePaths"],
+        });
+    }
+});
+export const publishUploadReceiptSchema = z.object({
+    ...uploadInstructionsSchema.shape,
+});
+export const publishReceiptSpaceSchema = z.object({
+    id: z.string(),
+    slug: z.string(),
+    publicName: z.string(),
+    defaultHostname: z.string(),
+    liveUrl: z.string().nullable(),
+});
+export const publishReceiptVersionSchema = z.object({
+    id: z.string(),
+    status: VersionSchema.shape.status,
+    immutableUrl: z.string().nullable(),
+    manifestHash: z.string().nullable(),
+});
+export const publishReceiptSchema = z.object({
+    space: publishReceiptSpaceSchema,
+    version: publishReceiptVersionSchema,
+    operation: AsyncOperationSchema.optional().describe("Background finalize operation when publish work continues asynchronously."),
+    // Paste-ready one-liner (URL + claim nudge) so agents propagate consistent
+    // claim copy into transcripts (internal-docs/platform.md M1a "share blurb").
+    shareBlurb: z.string(),
+    upload: publishUploadReceiptSchema.optional(),
+    claim: z
+        .object({
+        token: z.string().optional(),
+        url: z.string(),
+        expiresAt: z.string().datetime(),
+    })
+        .optional(),
+    diagnostics: z
+        .array(baseDiagnosticSchema)
+        .optional()
+        .describe("Publish diagnostics: the `noop_publish` info diagnostic when nothing changed (the only noop signal), manifest warnings such as `path_case_collision`, and serving-shape notes such as `single_html_index` or `files_mode_inferred`."),
+    links: z
+        .object({
+        resume: z
+            .string()
+            .optional()
+            .describe("Resume endpoint; present while bytes still need uploading."),
+        finalize: z
+            .string()
+            .optional()
+            .describe("Finalize endpoint; present while bytes still need uploading."),
+        promote: z
+            .string()
+            .optional()
+            .describe('Promote endpoint; followable once the version reaches status "ready".'),
+        operation: z.string().optional().describe("Operation polling endpoint when publish queued."),
+        inspect: z.string().optional().describe("Space resource URL for follow-up reads."),
+    })
+        .optional()
+        .describe("Follow-up links so agents can act on the receipt without knowing the full API."),
+});
+// Same inferable contract as the intent response: `upload` present means bytes are still
+// needed (then finalize); absent means everything declared has already landed.
+export const spaceVersionResumeResponseSchema = z.object({
+    versionId: z.string(),
+    upload: uploadInstructionsSchema
+        .nullable()
+        .describe("Fresh runtime upload session, present only while files still need uploading. Upload, then finalize."),
+    ignoredPaths: z
+        .array(z.string())
+        .default([])
+        .describe("Manifest paths ignored by the server because the current plan does not allow them."),
+});
+export const spaceVersionRefreshResponseSchema = spaceVersionResumeResponseSchema;
+// Promote body (spec "Explicit version routes"): `{ channel? }` defaulting to
+// "live". Channels beyond live arrive additively; non-live names reject with
+// `channel_unsupported` until then. Rollback is promoting an older ready
+// version to the same channel.
+export const versionPromoteSchema = z
+    .object({
+    channel: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Channel to point at this version; defaults to "live". Non-live channel names are rejected with channel_unsupported until additional channels ship.'),
+})
+    .optional()
+    .default({});
+export const spaceFinalizeSchema = z
+    .object({
+    conventionFiles: conventionFilesSchema.optional(),
+    channel: z
+        .enum(["live"])
+        .nullable()
+        .optional()
+        .describe("Omit for live publish, or pass null to finalize the version without promoting it."),
+})
+    .optional()
+    .default({});
+export const spaceRuntimeStatusSchema = z.object({
+    liveVersionId: z
+        .string()
+        .nullable()
+        .describe("Version that the live space URL currently points to, if any."),
+    pendingVersionId: z
+        .string()
+        .nullable()
+        .describe("Version that live traffic is trying to publish, if any."),
+    liveUrl: z
+        .string()
+        .nullable()
+        .describe("Live space URL. Flips to the latest version after a successful publish to `live`."),
+    runtimeState: spaceStatus.describe("Space operation-lifecycle status."),
+    liveVersionStatus: versionStatus.nullable(),
+    liveRuntimeKind: zeroRuntimeKindSchema
+        .nullable()
+        .describe("Runtime kind declared by the live version, if any."),
+    pendingVersionStatus: versionStatus.nullable(),
+    operation: AsyncOperationSchema.nullable(),
+});
+// Channel listing entry: the channel name plus its spec ChannelPointer.
+export const spaceChannelSchema = z.object({
+    name: z.string().describe('Channel name; "live" is the default channel.'),
+    pointer: ChannelPointerSchema,
+});
+export const spaceChannelListResponseSchema = z.object({
+    data: z.array(spaceChannelSchema),
+    pagination: CursorPaginationSchema,
+});
+export const spaceApplyChangeBaseSchema = z.object({
+    kind: z.enum(["variable", "routing", "password", "settings"]),
+    name: z.string(),
+    label: z.string(),
+});
+export const spaceApplyModeSchema = z.enum(["stage", "apply"]);
+export const spaceApplyChangeSchema = spaceApplyChangeBaseSchema.extend({
+    id: z.string(),
+    sourceSurface: z.string(),
+    applyMode: spaceApplyModeSchema,
+    changesetId: z.string().optional(),
+    before: z.record(z.string(), z.unknown()).nullable().optional(),
+    after: z.record(z.string(), z.unknown()).nullable().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export const spaceApplyStateSchema = z.object({
+    status: z.enum(["live", "pending", "applying", "failed"]),
+    desiredRevision: z.string().nullable(),
+    appliedRevision: z.string().nullable(),
+    pendingChangeCount: z.number().int(),
+    changes: z.array(spaceApplyChangeSchema),
+    operation: AsyncOperationSchema.nullable(),
+    lastError: z.string().nullable(),
+    canApplyNow: z.boolean(),
+});
+export const spaceApplyResponseSchema = z.object({
+    applied: z.boolean(),
+    applyState: spaceApplyStateSchema,
+});