@spacefast/common 0.0.13 → 0.0.18

package/dist/contracts/platform.js

@@ -103,9 +103,9 @@ export const analyticsQuerySchema = z.object({
     window: z
         .enum(["48h", "7d", "30d", "custom"])
         .optional()
-        .describe('Analytics summary window; defaults to "7d". "custom" requires since/until.'),
-    since: z.string().datetime().optional().describe("Custom analytics start."),
-    until: z.string().datetime().optional().describe("Custom analytics end."),
+        .describe('Analytics summary window. Defaults to "7d". "custom" requires since/until.'),
+    since: z.string().datetime().optional().describe("Start of the custom analytics window."),
+    until: z.string().datetime().optional().describe("End of the custom analytics window."),
 });
 // Served by `GET /v1/spaces/{spaceId}/analytics`: traffic summary over the
 // requested window, read from Spacefast's own per-space rollups (ingested on
@@ -113,7 +113,7 @@ export const analyticsQuerySchema = z.object({
 // Counts cover main hostnames only: default, custom-domain, and channel.
 // Immutable version-URL traffic is ingested but never surfaced here.
 export const analyticsResponseSchema = z.object({
-    spaceId: z.string().describe("Space the traffic was aggregated for."),
+    spaceId: z.string().describe("The space id the traffic was aggregated for."),
     window: z.enum(["48h", "7d", "30d", "custom"]).describe("Resolved summary window."),
     since: z.string().describe("Resolved window start (ISO 8601), after retention clamping."),
     until: z.string().describe("Resolved window end (ISO 8601)."),
@@ -121,15 +121,17 @@ export const analyticsResponseSchema = z.object({
     dataAsOf: z
         .string()
         .nullable()
-        .describe("End of the last fully-ingested hour; null while the first ingest is running."),
-    refreshing: z.boolean().describe("Whether an ingest run is active or was just triggered."),
+        .describe("End of the last fully-ingested hour; null until the first ingest starts."),
+    refreshing: z
+        .boolean()
+        .describe("Whether an ingest run is active or the server just triggered one."),
     views: z
         .number()
         .describe("Successful non-crawler requests (status < 400, assets included) summed across main hostnames over the window."),
     visitors: z
         .number()
         .nullable()
-        .describe("Unique-visitor estimate. Currently always null: per-hostname unique-visitor data is not yet available from the hosting provider."),
+        .describe("Unique-visitor estimate. Always null because per-hostname unique-visitor data is not yet available from the hosting provider."),
     bandwidthBytes: z.number().describe("Total response bytes in the window."),
     visitorsByHost: z
         .array(z.object({
@@ -140,7 +142,7 @@ export const analyticsResponseSchema = z.object({
             views: z.number(),
         })),
     }))
-        .describe("Per-hostname daily visitor estimates. Currently always empty: per-hostname unique-visitor data is not yet available from the hosting provider."),
+        .describe("Per-hostname daily visitor estimates. Always empty because per-hostname unique-visitor data is not yet available from the hosting provider."),
     topPaths: z
         .array(z.object({ path: z.string(), views: z.number() }))
         .describe("Most-viewed paths, capped at 10."),

package/dist/contracts/problem-document.d.ts

@@ -0,0 +1,14 @@
+export interface ProblemDocument {
+    code: string | undefined;
+    detail: string | undefined;
+    type: string | undefined;
+    title: string | undefined;
+    pointer: string | undefined;
+    /** Raw, unnarrowed: each caller decides what shape it accepts. */
+    details: unknown;
+    suggestions: string[];
+    next: string[];
+    requestId: string | undefined;
+}
+/** Returns undefined when the payload cannot be a problem document at all. */
+export declare function parseProblemDocument(payload: unknown): ProblemDocument | undefined;

package/dist/contracts/problem-document.js

@@ -0,0 +1,35 @@
+// Reader for the RFC 9457 problem document every 4xx/5xx response carries, so the
+// client surfaces (CLI, MCP, SDK) share one definition of which members exist and
+// which values are trusted. Callers keep their own entry guards, message fallbacks
+// and public field names — this only extracts the wire members.
+/** Returns undefined when the payload cannot be a problem document at all. */
+export function parseProblemDocument(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        return undefined;
+    }
+    const problem = payload;
+    if (!("code" in problem) && !("detail" in problem)) {
+        return undefined;
+    }
+    const stringField = (name) => {
+        const value = problem[name];
+        return typeof value === "string" ? value : undefined;
+    };
+    const stringArray = (name) => {
+        const value = problem[name];
+        return Array.isArray(value)
+            ? value.filter((entry) => typeof entry === "string")
+            : [];
+    };
+    return {
+        code: stringField("code"),
+        detail: stringField("detail"),
+        type: stringField("type"),
+        title: stringField("title"),
+        pointer: stringField("pointer"),
+        details: problem.details,
+        suggestions: stringArray("suggestions"),
+        next: stringArray("next"),
+        requestId: stringField("requestId"),
+    };
+}

package/dist/contracts/push-new.d.ts

@@ -50,14 +50,19 @@ export declare const PushNewSessionSchema: z.ZodObject<{
     reusedVersionId: z.ZodNullable<z.ZodString>;
     webhookDeliveryId: z.ZodNullable<z.ZodString>;
     liveUrl: z.ZodString;
-    open: z.ZodNullable<z.ZodObject<{
+    open: z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+        url: z.ZodString;
+        expiresAt: z.ZodNullable<z.ZodString>;
+        kind: z.ZodLiteral<"link">;
+    }, z.core.$strip>, z.ZodObject<{
         url: z.ZodString;
         expiresAt: z.ZodString;
         kind: z.ZodEnum<{
             management: "management";
+            person: "person";
             claim_preview: "claim_preview";
         }>;
-    }, z.core.$strip>>;
+    }, z.core.$strip>]>>;
     sessionUrl: z.ZodString;
     logsUrl: z.ZodNullable<z.ZodString>;
     claimUrl: z.ZodString;
@@ -103,14 +108,19 @@ export declare const PushNewCreateSessionResponseSchema: z.ZodObject<{
     reusedVersionId: z.ZodNullable<z.ZodString>;
     webhookDeliveryId: z.ZodNullable<z.ZodString>;
     liveUrl: z.ZodString;
-    open: z.ZodNullable<z.ZodObject<{
+    open: z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+        url: z.ZodString;
+        expiresAt: z.ZodNullable<z.ZodString>;
+        kind: z.ZodLiteral<"link">;
+    }, z.core.$strip>, z.ZodObject<{
         url: z.ZodString;
         expiresAt: z.ZodString;
         kind: z.ZodEnum<{
             management: "management";
+            person: "person";
             claim_preview: "claim_preview";
         }>;
-    }, z.core.$strip>>;
+    }, z.core.$strip>]>>;
     sessionUrl: z.ZodString;
     logsUrl: z.ZodNullable<z.ZodString>;
     claimUrl: z.ZodString;
@@ -124,14 +134,19 @@ export declare const PushNewCreateSessionResponseSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const PushNewStatusResponseSchema: z.ZodObject<{
     id: z.ZodString;
-    open: z.ZodNullable<z.ZodObject<{
+    open: z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+        url: z.ZodString;
+        expiresAt: z.ZodNullable<z.ZodString>;
+        kind: z.ZodLiteral<"link">;
+    }, z.core.$strip>, z.ZodObject<{
         url: z.ZodString;
         expiresAt: z.ZodString;
         kind: z.ZodEnum<{
             management: "management";
+            person: "person";
             claim_preview: "claim_preview";
         }>;
-    }, z.core.$strip>>;
+    }, z.core.$strip>]>>;
     status: z.ZodEnum<{
         live: "live";
         failed: "failed";

package/dist/contracts/push-new.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { privateOpenSchema } from "./access.js";
 export const pushNewSessionStatusSchema = z.enum([
     "waiting_for_push",
     "waiting_for_upload",
@@ -31,14 +32,9 @@ export const PushNewSessionSchema = z.object({
     reusedVersionId: z.string().nullable(),
     webhookDeliveryId: z.string().nullable(),
     liveUrl: z.string().url(),
-    open: z
-        .object({
-        url: z.string().url(),
-        expiresAt: z.string().datetime(),
-        kind: z.enum(["management", "claim_preview"]),
-    })
+    open: privateOpenSchema
         .nullable()
-        .describe("A short-lived, one-use private Open handoff. It is not a stable URL and clients must not persist it as Space state."),
+        .describe("Reusable Open link for the private space at live `/`. A null expiry means it remains valid until revoked."),
     sessionUrl: z.string().url(),
     logsUrl: z.string().url().nullable(),
     claimUrl: z.string().url(),

package/dist/contracts/resources.d.ts

@@ -105,6 +105,7 @@ export declare const SpaceSchema: z.ZodObject<{
         always_hot: "always_hot";
     }>;
     moving: z.ZodBoolean;
+    hasRuntime: z.ZodBoolean;
     channels: z.ZodRecord<z.ZodString, z.ZodObject<{
         versionId: z.ZodString;
         updatedAt: z.ZodString;
@@ -187,7 +188,7 @@ export declare const SpaceSchema: z.ZodObject<{
             bodyEnd: z.ZodOptional<z.ZodArray<z.ZodString>>;
             noscript: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
-        dataSources: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodObject<{
+        dataSources: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodRecord<z.ZodString, z.ZodObject<{
             kind: z.ZodLiteral<"wordpress">;
             url: z.ZodString;
         }, z.core.$strict>>>>;
@@ -241,10 +242,10 @@ export declare const SpaceSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const PublishSourceSchema: z.ZodObject<{
     kind: z.ZodEnum<{
-        api: "api";
-        dashboard: "dashboard";
         build: "build";
         agent: "agent";
+        api: "api";
+        dashboard: "dashboard";
         direct_upload: "direct_upload";
         cli: "cli";
         git: "git";
@@ -278,10 +279,10 @@ export declare const VersionSchema: z.ZodObject<{
     spaceId: z.ZodString;
     source: z.ZodNullable<z.ZodObject<{
         kind: z.ZodEnum<{
-            api: "api";
-            dashboard: "dashboard";
             build: "build";
             agent: "agent";
+            api: "api";
+            dashboard: "dashboard";
             direct_upload: "direct_upload";
             cli: "cli";
             git: "git";
@@ -420,7 +421,7 @@ export declare const VersionSchema: z.ZodObject<{
             bodyEnd: z.ZodOptional<z.ZodArray<z.ZodString>>;
             noscript: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
-        dataSources: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodObject<{
+        dataSources: z.ZodOptional<z.ZodPipe<z.ZodUnknown, z.ZodRecord<z.ZodString, z.ZodObject<{
             kind: z.ZodLiteral<"wordpress">;
             url: z.ZodString;
         }, z.core.$strict>>>>;
@@ -470,7 +471,7 @@ export declare const VersionSchema: z.ZodObject<{
     headersRuleCount: z.ZodNumber;
     redirectsRuleCount: z.ZodNumber;
     proxyRouteCount: z.ZodNumber;
-    functionsDetected: z.ZodBoolean;
+    runtimeCodeDetected: z.ZodBoolean;
     buildLog: z.ZodNullable<z.ZodString>;
     diagnostics: z.ZodDefault<z.ZodArray<z.ZodObject<{
         code: z.ZodString;

package/dist/contracts/resources.js

@@ -63,7 +63,7 @@ export const SpaceSchema = z.object({
     defaultHostname: z
         .string()
         .describe("Current Spacefast-owned managed hostname under view.fast. Renaming the space changes this hostname; previously managed hostnames temporarily redirect to the current one."),
-    publicName: z.string().describe("Public project label used in the managed view.fast hostname."),
+    publicName: z.string().describe("Public space 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."),
@@ -86,17 +86,20 @@ export const SpaceSchema = z.object({
     burstable: z
         .boolean()
         .nullable()
-        .describe("Whether a dedicated placement may burst provider PHP workers."),
+        .describe("Whether a dedicated placement can burst provider PHP workers."),
     archivedBytes: z
         .number()
         .int()
         .nonnegative()
         .describe("Bytes currently archived out of the hot runtime store."),
     tierPolicy: z.enum(["auto", "always_hot"]).describe("Storage tiering policy for this space."),
-    moving: z.boolean().describe("True while a placement or transfer move is queued or running."),
+    moving: z.boolean().describe("Whether a placement or transfer move is queued or running."),
+    hasRuntime: z
+        .boolean()
+        .describe("Whether this space's live version runs code and therefore has a Runtime surface. Feature eligibility alone does not make the surface visible."),
     channels: z
         .record(z.string(), ChannelPointerSchema)
-        .describe('Channel pointers by name; "live" is present once a version has been promoted.'),
+        .describe('Channel pointers by name. "live" is present after a version is promoted.'),
     config: spaceConfigSchema
         .nullable()
         .describe("Stored SpaceConfig overlay applied over the live version's sf.jsonc; null when nothing is overridden."),
@@ -129,7 +132,7 @@ export const PublishSourceSchema = z.object({
     dirty: z
         .boolean()
         .optional()
-        .describe("True when the working tree had uncommitted changes at publish time."),
+        .describe("Whether the working tree had uncommitted changes at publish time."),
     metadata: z
         .record(z.string(), z.string())
         .optional()
@@ -193,7 +196,7 @@ export const VersionSchema = z.object({
     headersRuleCount: z.number().int(),
     redirectsRuleCount: z.number().int(),
     proxyRouteCount: z.number().int(),
-    functionsDetected: z.boolean(),
+    runtimeCodeDetected: z.boolean(),
     buildLog: z.string().nullable(),
     diagnostics: z.array(DiagnosticSchema).default([]),
     createdAt: z.string().datetime(),