@spacefast/common 0.0.2 → 0.0.5

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/deployments.d.ts

@@ -4,9 +4,9 @@ export declare const deploymentStatusSchema: z.ZodEnum<{
     queued: "queued";
     canceled: "canceled";
     ready: "ready";
+    building: "building";
     waiting_for_source: "waiting_for_source";
     skipped: "skipped";
-    building: "building";
 }>;
 export declare const DeploymentSourceSchema: z.ZodObject<{
     kind: z.ZodNullable<z.ZodString>;
@@ -73,10 +73,10 @@ export declare const DeploymentChannelStateSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const DeploymentActivityGroupSchema: z.ZodObject<{
     kind: z.ZodEnum<{
-        version: "version";
         channel: "channel";
-        source: "source";
+        version: "version";
         branch: "branch";
+        source: "source";
         pull_request: "pull_request";
     }>;
     key: z.ZodString;
@@ -104,10 +104,10 @@ export declare const DeploymentSchema: z.ZodObject<{
     }, z.core.$strip>>;
     activityGroup: z.ZodObject<{
         kind: z.ZodEnum<{
-            version: "version";
             channel: "channel";
-            source: "source";
+            version: "version";
             branch: "branch";
+            source: "source";
             pull_request: "pull_request";
         }>;
         key: z.ZodString;
@@ -118,18 +118,18 @@ export declare const DeploymentSchema: z.ZodObject<{
         queued: "queued";
         canceled: "canceled";
         ready: "ready";
+        building: "building";
         waiting_for_source: "waiting_for_source";
         skipped: "skipped";
-        building: "building";
     }>;
     versionStatus: z.ZodNullable<z.ZodEnum<{
         failed: "failed";
         canceled: "canceled";
         ready: "ready";
         expired: "expired";
-        created: "created";
         building: "building";
         prepared: "prepared";
+        created: "created";
         uploading: "uploading";
         uploaded: "uploaded";
         finalizing: "finalizing";
@@ -216,9 +216,9 @@ export declare const DeploymentSchema: z.ZodObject<{
     diagnostics: z.ZodArray<z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
-            info: "info";
             warning: "warning";
             error: "error";
+            info: "info";
         }>;
         message: z.ZodString;
         path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -268,10 +268,10 @@ export declare const deploymentListResponseSchema: z.ZodObject<{
         }, z.core.$strip>>;
         activityGroup: z.ZodObject<{
             kind: z.ZodEnum<{
-                version: "version";
                 channel: "channel";
-                source: "source";
+                version: "version";
                 branch: "branch";
+                source: "source";
                 pull_request: "pull_request";
             }>;
             key: z.ZodString;
@@ -282,18 +282,18 @@ export declare const deploymentListResponseSchema: z.ZodObject<{
             queued: "queued";
             canceled: "canceled";
             ready: "ready";
+            building: "building";
             waiting_for_source: "waiting_for_source";
             skipped: "skipped";
-            building: "building";
         }>;
         versionStatus: z.ZodNullable<z.ZodEnum<{
             failed: "failed";
             canceled: "canceled";
             ready: "ready";
             expired: "expired";
-            created: "created";
             building: "building";
             prepared: "prepared";
+            created: "created";
             uploading: "uploading";
             uploaded: "uploaded";
             finalizing: "finalizing";
@@ -380,9 +380,9 @@ export declare const deploymentListResponseSchema: z.ZodObject<{
         diagnostics: z.ZodArray<z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
-                info: "info";
                 warning: "warning";
                 error: "error";
+                info: "info";
             }>;
             message: z.ZodString;
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -433,10 +433,10 @@ export declare const deploymentGetResponseSchema: z.ZodObject<{
         }, z.core.$strip>>;
         activityGroup: z.ZodObject<{
             kind: z.ZodEnum<{
-                version: "version";
                 channel: "channel";
-                source: "source";
+                version: "version";
                 branch: "branch";
+                source: "source";
                 pull_request: "pull_request";
             }>;
             key: z.ZodString;
@@ -447,18 +447,18 @@ export declare const deploymentGetResponseSchema: z.ZodObject<{
             queued: "queued";
             canceled: "canceled";
             ready: "ready";
+            building: "building";
             waiting_for_source: "waiting_for_source";
             skipped: "skipped";
-            building: "building";
         }>;
         versionStatus: z.ZodNullable<z.ZodEnum<{
             failed: "failed";
             canceled: "canceled";
             ready: "ready";
             expired: "expired";
-            created: "created";
             building: "building";
             prepared: "prepared";
+            created: "created";
             uploading: "uploading";
             uploaded: "uploaded";
             finalizing: "finalizing";
@@ -545,9 +545,9 @@ export declare const deploymentGetResponseSchema: z.ZodObject<{
         diagnostics: z.ZodArray<z.ZodObject<{
             code: z.ZodString;
             severity: z.ZodEnum<{
-                info: "info";
                 warning: "warning";
                 error: "error";
+                info: "info";
             }>;
             message: z.ZodString;
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;

package/dist/contracts/device-auth.d.ts

@@ -23,8 +23,8 @@ export type DeviceAuthorizationPollRequest = z.infer<typeof DeviceAuthorizationP
 export declare const DeviceAuthorizationStatusSchema: z.ZodEnum<{
     expired: "expired";
     pending: "pending";
-    approved: "approved";
     denied: "denied";
+    approved: "approved";
     consumed: "consumed";
 }>;
 export type DeviceAuthorizationStatus = z.infer<typeof DeviceAuthorizationStatusSchema>;
@@ -32,8 +32,8 @@ export declare const DeviceAuthorizationPollResponseSchema: z.ZodObject<{
     status: z.ZodEnum<{
         expired: "expired";
         pending: "pending";
-        approved: "approved";
         denied: "denied";
+        approved: "approved";
         consumed: "consumed";
     }>;
     apiKey: z.ZodOptional<z.ZodObject<{
@@ -42,17 +42,17 @@ export declare const DeviceAuthorizationPollResponseSchema: z.ZodObject<{
         tenantId: z.ZodNullable<z.ZodString>;
         subject: z.ZodNullable<z.ZodObject<{
             type: z.ZodEnum<{
+                team: "team";
                 external: "external";
-                user: "user";
                 system: "system";
-                team: "team";
+                user: "user";
             }>;
             id: z.ZodString;
         }, z.core.$strip>>;
         ownerPrincipal: z.ZodNullable<z.ZodObject<{
             type: z.ZodEnum<{
-                external: "external";
                 team: "team";
+                external: "external";
             }>;
             id: z.ZodString;
         }, z.core.$strip>>;
@@ -150,8 +150,8 @@ export declare const DeviceAuthorizationVerifyResponseSchema: z.ZodObject<{
     status: z.ZodEnum<{
         expired: "expired";
         pending: "pending";
-        approved: "approved";
         denied: "denied";
+        approved: "approved";
         consumed: "consumed";
     }>;
     clientId: z.ZodNullable<z.ZodString>;