@spacefast/common 0.0.2

package/dist/contracts/resources.js

@@ -0,0 +1,209 @@
+import { z } from "zod";
+import { policyDocSchema } from "./access.js";
+import { AsyncOperationSchema, baseDiagnosticSchema } from "./common.js";
+import { publishSourceKind, versionStatus, spaceDisabledReasonCode, spaceStatus } from "./enums.js";
+import { pendingUploadSchema } from "./internal.js";
+import { spaceConfigSchema } from "./space-config.js";
+export const DiagnosticSchema = baseDiagnosticSchema.extend({
+    id: z.string(),
+    versionId: z.string(),
+    createdAt: z.string().datetime(),
+});
+export const PrincipalRefSchema = z.object({
+    tenantId: z.string(),
+    principalType: z.enum(["team", "external"]),
+    principalId: z.string(),
+});
+// ChannelPointer (internal-docs/platform.md "ChannelPointer"): exactly one of
+// `versionId` | `weighted` is present; an empty pointer is invalid. Weighted
+// pointers (gradual rollouts) are a future write surface — the shape is final.
+export const ChannelPointerSchema = z
+    .object({
+    versionId: z.string().optional().describe("Version this channel serves."),
+    weighted: z
+        .array(z.object({
+        versionId: z.string(),
+        percentage: z.number().int().min(1).max(100),
+    }))
+        .min(2)
+        .optional()
+        .describe("Weighted rollout across >=2 ready versions; percentages sum to 100."),
+    updatedAt: z.string().datetime(),
+})
+    .superRefine((value, ctx) => {
+    const hasVersion = value.versionId !== undefined;
+    const hasWeighted = value.weighted !== undefined;
+    if (hasVersion === hasWeighted) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "Exactly one of versionId or weighted must be present.",
+        });
+        return;
+    }
+    if (value.weighted &&
+        value.weighted.reduce((sum, entry) => sum + entry.percentage, 0) !== 100) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["weighted"],
+            message: "Weighted percentages must sum to 100.",
+        });
+    }
+});
+export const SpaceSchema = z.object({
+    id: z.string(),
+    tenantId: z.string(),
+    siteId: z.string().nullable(),
+    teamId: z.string().nullable(),
+    teamSlug: z.string().nullable(),
+    principal: PrincipalRefSchema.nullable(),
+    anonymous: z.boolean(),
+    slug: z.string(),
+    title: z.string(),
+    status: spaceStatus.describe("Operation-lifecycle status. Serving state is the separate `disabled` axis."),
+    // Serving axis, distinct from the operation-lifecycle state: set whenever
+    // the space is dark. A disabled space can still be moving. Malware takedowns
+    // are `abuse_takedown` with `details.source = "malware_scan"`.
+    disabled: z
+        .object({
+        at: z.string().datetime().nullable(),
+        reasonCode: spaceDisabledReasonCode.describe("Why serving is disabled."),
+    })
+        .nullable(),
+    // Anonymous-claim lifecycle (internal-docs/platform.md Space.claimState): null
+    // for spaces that never went through the anonymous lifecycle. `purgeAfter` is
+    // the end of the one-day post-expiry recovery window before content deletion.
+    claimState: z
+        .object({
+        expiresAt: z.string().datetime().nullable(),
+        claimedAt: z.string().datetime().nullable(),
+        purgeAfter: z.string().datetime().nullable(),
+    })
+        .nullable(),
+    // Expiry rescue: present only on a claim-token read that just extended the
+    // anonymous hold; reports the new expiry so claim pages can confirm the grant.
+    expiryExtension: z.object({ extendedTo: z.string().datetime() }).nullable().optional(),
+    defaultHostname: z
+        .string()
+        .describe("Stable Spacefast-owned default hostname, built from the public project name under view.fast; survives slug renames."),
+    publicName: z.string().describe("Public project label used in the managed view.fast hostname."),
+    liveUrl: z
+        .string()
+        .describe("Live space URL: the primary bound domain when one exists, else the default hostname. Always present on non-deleted spaces."),
+    dataLocation: z
+        .string()
+        .describe('Resolved data-location region; immutable after ownership exists. "auto" only while no concrete region is known yet.'),
+    channels: z
+        .record(z.string(), ChannelPointerSchema)
+        .describe('Channel pointers by name; "live" is present once a version has been promoted.'),
+    config: spaceConfigSchema
+        .nullable()
+        .describe("Stored SpaceConfig overlay applied over the live version's sf.jsonc; null when nothing is overridden."),
+    noindex: z
+        .boolean()
+        .describe("When true, the live production hostnames serve platform noindex directives. Immutable version and preview hostnames are always noindex regardless of this setting."),
+    policy: policyDocSchema
+        .nullable()
+        .describe("Deprecated space-level access projection. Use /v1/spaces/{spaceId}/access and /effective for the unified policy lane."),
+    operation: AsyncOperationSchema.nullable(),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+});
+// PublishSource (internal-docs/platform.md "PublishSource"): the single
+// provenance shape for how a version came to exist. Sent on publish/version
+// create and echoed on the Version resource. Structured CI/git detail beyond
+// the named fields rides in `metadata` (string values only).
+export const PublishSourceSchema = z.object({
+    kind: publishSourceKind.describe("How this version was produced."),
+    client: z
+        .string()
+        .max(255)
+        .optional()
+        .describe("Publishing client attribution, e.g. spacefast-cli/1.2.3."),
+    branch: z.string().max(255).optional().describe("Git branch the publish came from."),
+    commit: z.string().max(64).optional().describe("Git commit SHA the publish came from."),
+    message: z
+        .string()
+        .max(2000)
+        .optional()
+        .describe("Plain-language description of the publish (the version changelog entry, commit message, or release note). This is THE spelling for the publish description; the version files-diff API is the fallback when none is given."),
+    dirty: z
+        .boolean()
+        .optional()
+        .describe("True when the working tree had uncommitted changes at publish time."),
+    metadata: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe("Additional provenance (repository, CI run URL, workflow, actor, ...)."),
+    git: z
+        .object({
+        repository: z.string().nullable().optional(),
+        repositoryFullName: z.string().nullable().optional(),
+        repositoryUrl: z.string().nullable().optional(),
+        ref: z.string().nullable().optional(),
+        branch: z.string().nullable().optional(),
+        branchAliasUrl: z.string().nullable().optional(),
+        commit: z.string().nullable().optional(),
+        commitSha: z.string().nullable().optional(),
+        pullRequestNumber: z.number().nullable().optional(),
+    })
+        .catchall(z.unknown())
+        .optional(),
+});
+export const VersionSchema = z.object({
+    id: z.string(),
+    ref: z
+        .string()
+        .nullable()
+        .describe('Human ref "v{number}"; null until the version reaches ready.'),
+    // Assigned in readiness order when the version reaches `ready`; null before.
+    number: z.number().int().positive().nullable(),
+    spaceId: z.string(),
+    source: PublishSourceSchema.nullable().describe("Publish provenance: who/what produced this version."),
+    status: versionStatus,
+    failureCode: z.string().nullable(),
+    failureMessage: z.string().nullable(),
+    failedStage: z.string().nullable(),
+    // `sha256:`-prefixed digest of the canonical manifest.
+    manifestHash: z.string().nullable(),
+    // Build (`bld_`) that produced this version; null for direct uploads.
+    buildId: z.string().nullable(),
+    // Import provenance: the source version this one was materialized from.
+    importedFromVersionId: z.string().nullable(),
+    // Finalize-time variable resolution provenance — names and value hashes only,
+    // never values.
+    variables: z.array(z.object({ name: z.string(), valueHash: z.string() })).nullable(),
+    fileCount: z.number().int().nullable(),
+    totalBytes: z.number().int().nullable(),
+    pendingUploads: z.array(pendingUploadSchema),
+    skippedPaths: z.array(z.string()),
+    immutableUrl: z
+        .string()
+        .nullable()
+        .describe("Permanent version URL (v{number}--{label}.view.fast form), computed once and stored at ready; survives slug changes, transfers, and channel repointing. Null before ready."),
+    isCurrentProduction: z.boolean(),
+    siteTitle: z.string(),
+    config: spaceConfigSchema
+        .nullable()
+        .describe("SpaceConfig overlay snapshot the version was finalized with."),
+    operation: AsyncOperationSchema.nullable(),
+    headersRuleCount: z.number().int(),
+    redirectsRuleCount: z.number().int(),
+    proxyRouteCount: z.number().int(),
+    functionsDetected: z.boolean(),
+    buildLog: z.string().nullable(),
+    diagnostics: z.array(DiagnosticSchema).default([]),
+    createdAt: z.string().datetime(),
+    // Retention anchor: stamped when the version first reaches "ready".
+    readyAt: z.string().datetime().nullable(),
+    // Retention axes computed from plan policy at read time, never stored per row
+    // (internal-docs/platform.md "Version retention"). Null = not subject to that
+    // axis (live/channel-referenced, anonymous claim lifecycle, or the plan
+    // retains indefinitely).
+    accessibleUntil: z.string().datetime().nullable(),
+    retainedUntil: z.string().datetime().nullable(),
+    updatedAt: z.string().datetime(),
+});
+const activeVersionStatuses = new Set(["created", "uploading", "uploaded", "finalizing"]);
+export function hasActiveVersionStatus(status) {
+    return Boolean(status && activeVersionStatuses.has(status));
+}

package/dist/contracts/routes.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+export declare const websiteRouteSchema: z.ZodObject<{
+    hostname: z.ZodString;
+    path_prefix: z.ZodDefault<z.ZodString>;
+    mount: z.ZodDefault<z.ZodEnum<{
+        strip_prefix: "strip_prefix";
+        preserve_path: "preserve_path";
+    }>>;
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"version">;
+        version_id: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"channel">;
+        channel: z.ZodString;
+    }, z.core.$strip>], "type">;
+    options: z.ZodDefault<z.ZodObject<{
+        noindex: z.ZodOptional<z.ZodBoolean>;
+        auth: z.ZodOptional<z.ZodNullable<z.ZodUnknown>>;
+        expires_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+export declare const websiteRoutesConfigSchema: z.ZodObject<{
+    routes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        hostname: z.ZodString;
+        path_prefix: z.ZodDefault<z.ZodString>;
+        mount: z.ZodDefault<z.ZodEnum<{
+            strip_prefix: "strip_prefix";
+            preserve_path: "preserve_path";
+        }>>;
+        target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"version">;
+            version_id: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"channel">;
+            channel: z.ZodString;
+        }, z.core.$strip>], "type">;
+        options: z.ZodDefault<z.ZodObject<{
+            noindex: z.ZodOptional<z.ZodBoolean>;
+            auth: z.ZodOptional<z.ZodNullable<z.ZodUnknown>>;
+            expires_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type WebsiteRoute = z.infer<typeof websiteRouteSchema>;
+export type WebsiteRoutesConfig = z.infer<typeof websiteRoutesConfigSchema>;

package/dist/contracts/routes.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+const routeTargetSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("version"),
+        version_id: z.string().min(1),
+    }),
+    z.object({
+        type: z.literal("channel"),
+        channel: z.string().min(1),
+    }),
+]);
+export const websiteRouteSchema = z
+    .object({
+    hostname: z.string().min(1),
+    path_prefix: z.string().default("/"),
+    mount: z.enum(["strip_prefix", "preserve_path"]).default("strip_prefix"),
+    target: routeTargetSchema,
+    options: z
+        .object({
+        noindex: z.boolean().optional(),
+        auth: z.unknown().nullable().optional(),
+        expires_at: z.string().nullable().optional(),
+    })
+        .default({}),
+})
+    .strict();
+export const websiteRoutesConfigSchema = z
+    .object({
+    routes: z.array(websiteRouteSchema).default([]),
+})
+    .strict();