@spacefast/common 0.0.3 → 0.0.6

package/dist/contracts/builds.d.ts

@@ -92,18 +92,22 @@ declare const InternalBuildExecutionSchema: z.ZodObject<{
     sandboxId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     region: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    phases: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        phase: z.ZodString;
+        at: z.ZodString;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export declare const BuildSchema: z.ZodObject<{
     id: z.ZodString;
     spaceId: z.ZodString;
     status: z.ZodEnum<{
         failed: "failed";
-        queued: "queued";
-        running: "running";
-        succeeded: "succeeded";
         canceled: "canceled";
         waiting_for_source: "waiting_for_source";
         uploading_source: "uploading_source";
+        queued: "queued";
+        running: "running";
+        succeeded: "succeeded";
         skipped: "skipped";
     }>;
     input: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -144,9 +148,9 @@ export declare const BuildSchema: z.ZodObject<{
         message: z.ZodString;
         path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            registrar: "registrar";
             wpcloud: "wpcloud";
             dns: "dns";
-            registrar: "registrar";
             runtime: "runtime";
         }>>>;
         details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
@@ -195,9 +199,9 @@ export declare const buildCreateRequestSchema: z.ZodObject<{
         message: z.ZodString;
         path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            registrar: "registrar";
             wpcloud: "wpcloud";
             dns: "dns";
-            registrar: "registrar";
             runtime: "runtime";
         }>>>;
         details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
@@ -209,8 +213,8 @@ export declare const buildCreateRequestSchema: z.ZodObject<{
 export declare const buildSourceArchiveUploadSchema: z.ZodObject<{
     id: z.ZodString;
     mode: z.ZodEnum<{
-        dist: "dist";
         source: "source";
+        dist: "dist";
     }>;
     expiresAt: z.ZodString;
     summary: z.ZodObject<{
@@ -258,9 +262,9 @@ export declare const buildSourceArchiveUploadSchema: z.ZodObject<{
             message: z.ZodString;
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                registrar: "registrar";
                 wpcloud: "wpcloud";
                 dns: "dns";
-                registrar: "registrar";
                 runtime: "runtime";
             }>>>;
             details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
@@ -276,12 +280,12 @@ export declare const buildCreateResponseSchema: z.ZodObject<{
             spaceId: z.ZodString;
             status: z.ZodEnum<{
                 failed: "failed";
-                queued: "queued";
-                running: "running";
-                succeeded: "succeeded";
                 canceled: "canceled";
                 waiting_for_source: "waiting_for_source";
                 uploading_source: "uploading_source";
+                queued: "queued";
+                running: "running";
+                succeeded: "succeeded";
                 skipped: "skipped";
             }>;
             input: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -322,9 +326,9 @@ export declare const buildCreateResponseSchema: z.ZodObject<{
                 message: z.ZodString;
                 path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                    registrar: "registrar";
                     wpcloud: "wpcloud";
                     dns: "dns";
-                    registrar: "registrar";
                     runtime: "runtime";
                 }>>>;
                 details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
@@ -338,8 +342,8 @@ export declare const buildCreateResponseSchema: z.ZodObject<{
         upload: z.ZodDefault<z.ZodNullable<z.ZodObject<{
             id: z.ZodString;
             mode: z.ZodEnum<{
-                dist: "dist";
                 source: "source";
+                dist: "dist";
             }>;
             expiresAt: z.ZodString;
             summary: z.ZodObject<{
@@ -387,9 +391,9 @@ export declare const buildCreateResponseSchema: z.ZodObject<{
                     message: z.ZodString;
                     path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                     provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                        registrar: "registrar";
                         wpcloud: "wpcloud";
                         dns: "dns";
-                        registrar: "registrar";
                         runtime: "runtime";
                     }>>>;
                     details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
@@ -410,12 +414,12 @@ export declare const buildListResponseSchema: z.ZodObject<{
         spaceId: z.ZodString;
         status: z.ZodEnum<{
             failed: "failed";
-            queued: "queued";
-            running: "running";
-            succeeded: "succeeded";
             canceled: "canceled";
             waiting_for_source: "waiting_for_source";
             uploading_source: "uploading_source";
+            queued: "queued";
+            running: "running";
+            succeeded: "succeeded";
             skipped: "skipped";
         }>;
         input: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -456,9 +460,9 @@ export declare const buildListResponseSchema: z.ZodObject<{
             message: z.ZodString;
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                registrar: "registrar";
                 wpcloud: "wpcloud";
                 dns: "dns";
-                registrar: "registrar";
                 runtime: "runtime";
             }>>>;
             details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;

package/dist/contracts/builds.js

@@ -168,6 +168,14 @@ export const BuildCreateInputSchema = z
     }),
 ])
     .describe("What a new build should run against.");
+// One phase-timeline entry the build runner appends via recordBuildPhase
+// (apps/control-plane/src/builds/runner.ts BUILD_PHASES); `phase` stays a
+// plain string here since the runner's specific phase vocabulary is an
+// app-level concern, not a shared contract.
+const buildExecutionPhaseSchema = z.object({
+    phase: z.string().min(1).describe("Build phase name; see BUILD_PHASES in builds/runner.ts."),
+    at: z.string().datetime(),
+});
 const InternalBuildExecutionSchema = z
     .object({
     runner: z.string().nullable().default(null),
@@ -175,6 +183,10 @@ const InternalBuildExecutionSchema = z
     sandboxId: z.string().nullable().default(null),
     region: z.string().nullable().default(null),
     metadata: z.record(z.string(), z.unknown()).default({}),
+    phases: z
+        .array(buildExecutionPhaseSchema)
+        .optional()
+        .describe("Phase timeline the runner appends to via recordBuildPhase."),
 })
     .describe("Internal runner execution metadata surfaced only where appropriate.");
 export const BuildSchema = z.object({

package/dist/contracts/channels.d.ts

@@ -12,11 +12,11 @@ export declare const channelHistoryEntrySchema: z.ZodObject<{
     channel: z.ZodString;
     previousVersionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     actorType: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        system: "system";
         user: "user";
         api_key: "api_key";
         oauth_client: "oauth_client";
         anonymous_claim: "anonymous_claim";
-        system: "system";
     }>>>;
     actorId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     at: z.ZodString;
@@ -37,11 +37,11 @@ export declare const channelHistoryResponseSchema: z.ZodObject<{
         channel: z.ZodString;
         previousVersionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         actorType: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            system: "system";
             user: "user";
             api_key: "api_key";
             oauth_client: "oauth_client";
             anonymous_claim: "anonymous_claim";
-            system: "system";
         }>>>;
         actorId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         at: z.ZodString;

package/dist/contracts/common.d.ts

@@ -15,9 +15,9 @@ export declare const baseDiagnosticSchema: z.ZodObject<{
     message: z.ZodString;
     path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        registrar: "registrar";
         wpcloud: "wpcloud";
         dns: "dns";
-        registrar: "registrar";
         runtime: "runtime";
     }>>>;
     details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
@@ -110,9 +110,11 @@ export declare const ApiErrorResponseSchema: z.ZodObject<{
         docsUrl: z.ZodString;
         details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         suggestions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        next: z.ZodOptional<z.ZodArray<z.ZodString>>;
         requestId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
 }, z.core.$strip>;
+export type ApiErrorResponse = z.infer<typeof ApiErrorResponseSchema>;
 export declare function dataEnvelope<T extends z.ZodType>(data: T): z.ZodObject<{
     data: T;
 }, z.core.$strip>;
@@ -155,10 +157,10 @@ export declare const AsyncOperationSchema: z.ZodObject<{
     kind: z.ZodString;
     status: z.ZodEnum<{
         failed: "failed";
+        canceled: "canceled";
         queued: "queued";
         running: "running";
         succeeded: "succeeded";
-        canceled: "canceled";
     }>;
     resources: z.ZodArray<z.ZodObject<{
         type: z.ZodString;
@@ -179,9 +181,9 @@ export declare const AsyncOperationSchema: z.ZodObject<{
         message: z.ZodString;
         path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            registrar: "registrar";
             wpcloud: "wpcloud";
             dns: "dns";
-            registrar: "registrar";
             runtime: "runtime";
         }>>>;
         details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
@@ -199,10 +201,10 @@ export declare function mutationEnvelope<T extends z.ZodType>(data: T): z.ZodObj
         kind: z.ZodString;
         status: z.ZodEnum<{
             failed: "failed";
+            canceled: "canceled";
             queued: "queued";
             running: "running";
             succeeded: "succeeded";
-            canceled: "canceled";
         }>;
         resources: z.ZodArray<z.ZodObject<{
             type: z.ZodString;
@@ -223,9 +225,9 @@ export declare function mutationEnvelope<T extends z.ZodType>(data: T): z.ZodObj
             message: z.ZodString;
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                registrar: "registrar";
                 wpcloud: "wpcloud";
                 dns: "dns";
-                registrar: "registrar";
                 runtime: "runtime";
             }>>>;
             details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;

package/dist/contracts/common.js

@@ -83,6 +83,10 @@ export const ApiErrorResponseSchema = z.object({
             .array(z.string())
             .optional()
             .describe("Actionable recovery steps safe to show in dashboards, SDKs, and CLI output."),
+        next: z
+            .array(z.string())
+            .optional()
+            .describe("Copy-pasteable commands or API requests an agent can run next."),
         requestId: z.string().optional().describe("Request id to quote when contacting support."),
     }),
 });

package/dist/contracts/continuation.d.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+export declare const RequiresActionTypeSchema: z.ZodEnum<{
+    device_authorization: "device_authorization";
+}>;
+export declare const RequiresActionSchema: z.ZodObject<{
+    actionType: z.ZodEnum<{
+        device_authorization: "device_authorization";
+    }>;
+    instruction: z.ZodString;
+    url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    continuationToken: z.ZodString;
+    pollAfterSeconds: z.ZodNumber;
+    expiresAt: z.ZodString;
+}, z.core.$strict>;
+export type RequiresAction = z.infer<typeof RequiresActionSchema>;
+/** The canonical `{ requiresAction }` envelope, additive alongside `{ data }` / `{ error }`. */
+export declare const RequiresActionEnvelopeSchema: z.ZodObject<{
+    requiresAction: z.ZodObject<{
+        actionType: z.ZodEnum<{
+            device_authorization: "device_authorization";
+        }>;
+        instruction: z.ZodString;
+        url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        continuationToken: z.ZodString;
+        pollAfterSeconds: z.ZodNumber;
+        expiresAt: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const ActionResumeRequestSchema: z.ZodObject<{
+    continuationToken: z.ZodString;
+}, z.core.$strict>;
+export declare const ActionResumeResponseSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"pending">;
+    requiresAction: z.ZodObject<{
+        actionType: z.ZodEnum<{
+            device_authorization: "device_authorization";
+        }>;
+        instruction: z.ZodString;
+        url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        continuationToken: z.ZodString;
+        pollAfterSeconds: z.ZodNumber;
+        expiresAt: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"completed">;
+    actionType: z.ZodEnum<{
+        device_authorization: "device_authorization";
+    }>;
+    result: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"denied">;
+    actionType: z.ZodEnum<{
+        device_authorization: "device_authorization";
+    }>;
+    message: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"expired">;
+    actionType: z.ZodEnum<{
+        device_authorization: "device_authorization";
+    }>;
+    message: z.ZodString;
+}, z.core.$strict>], "status">;
+export type ActionResumeResponse = z.infer<typeof ActionResumeResponseSchema>;

package/dist/contracts/continuation.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { AnyObjectSchema } from "./common.js";
+// Canonical `requires_action` result envelope (W5: agent dead-end fix).
+//
+// Some flows cannot finish inside a single request: they need an out-of-band
+// human step (approve a device in the browser, confirm an approval). Historically
+// those flows returned an `{ error }` an agent could not programmatically continue
+// from — it was forced into the browser and the automation died. This envelope is
+// the additive third shape alongside `{ data }` / `{ error }`: it tells the caller
+// exactly what human step is pending, where to send the human, and — crucially —
+// hands back a short-lived, single-use, principal-scoped continuation token plus a
+// poll hint so the SAME agent can drive the flow to completion through the
+// generalized resume endpoint once the human step is done.
+export const RequiresActionTypeSchema = z
+    .enum(["device_authorization"])
+    .describe("Stable identifier for the out-of-band step a flow is blocked on. New blocking steps are added HERE so resume stays one generalized contract.");
+export const RequiresActionSchema = z
+    .object({
+    actionType: RequiresActionTypeSchema,
+    instruction: z
+        .string()
+        .describe("Human-facing instruction describing the step a person must complete out of band."),
+    url: z
+        .string()
+        .url()
+        .nullable()
+        .optional()
+        .describe("Where to send the human to complete the step, when a destination exists."),
+    continuationToken: z
+        .string()
+        .min(1)
+        .describe("Short-lived, single-use-on-completion, principal-scoped capability the agent presents to POST /v1/actions/resume to poll and complete this exact flow. Treat as a secret; never log it."),
+    pollAfterSeconds: z
+        .number()
+        .int()
+        .positive()
+        .describe("Minimum number of seconds to wait before calling resume again (retry-after hint)."),
+    expiresAt: z
+        .string()
+        .datetime()
+        .describe("Instant by which the human step must be completed — the originating flow's own deadline. Resume after this returns a terminal `expired` status (the token survives a short grace past this so resume can report that), but the flow can no longer be redeemed."),
+})
+    .strict();
+/** The canonical `{ requiresAction }` envelope, additive alongside `{ data }` / `{ error }`. */
+export const RequiresActionEnvelopeSchema = z
+    .object({ requiresAction: RequiresActionSchema })
+    .strict();
+// Generalized resume/poll contract. One endpoint (`POST /v1/actions/resume`)
+// drives every requires_action flow to completion from its continuation token, so
+// agents learn the pattern once and reuse it everywhere.
+export const ActionResumeRequestSchema = z
+    .object({
+    continuationToken: z
+        .string()
+        .trim()
+        .min(1)
+        .max(4096)
+        .describe("Continuation token from a `requiresAction` envelope. Body-only, never a URL."),
+})
+    .strict();
+export const ActionResumeResponseSchema = z
+    .discriminatedUnion("status", [
+    z
+        .object({
+        status: z.literal("pending"),
+        requiresAction: RequiresActionSchema.describe("The human step is still incomplete. Wait `pollAfterSeconds` and resume again with the same token."),
+    })
+        .strict(),
+    z
+        .object({
+        status: z.literal("completed"),
+        actionType: RequiresActionTypeSchema,
+        result: AnyObjectSchema.describe("The flow's success payload, redeemed exactly once. For device_authorization this carries the one-time `apiKey` and any `claimedSpaceId`."),
+    })
+        .strict(),
+    z
+        .object({
+        status: z.literal("denied"),
+        actionType: RequiresActionTypeSchema,
+        message: z.string(),
+    })
+        .strict(),
+    z
+        .object({
+        status: z.literal("expired"),
+        actionType: RequiresActionTypeSchema,
+        message: z.string(),
+    })
+        .strict(),
+])
+    .describe("Consistent resume result across flows: keep polling on `pending`, read the one-time payload on `completed`, stop on `denied`/`expired`.");

package/dist/contracts/countries.d.ts

@@ -0,0 +1,2 @@
+export declare const ISO_COUNTRY_CODES: readonly ["AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW"];
+export type IsoCountryCode = (typeof ISO_COUNTRY_CODES)[number];