@spacefast/common 0.0.23 → 0.0.24

package/dist/contracts/comments.js

@@ -72,6 +72,15 @@ export const collaborationPublicProfileSchema = z
         .nullable(),
 })
     .strict();
+/**
+ * Where the browser holding this ticket is.
+ *
+ * "embed" is a third-party site the owner allowlisted, and it is its own state
+ * precisely so nothing pretends a foreign origin is a published Spacefast host:
+ * the room an embed ticket names is origin-scoped, and both the mint and Cast
+ * refuse the pairing in either direction.
+ */
+export const collaborationSurfaceSchema = z.enum(["published", "preview", "embed"]);
 export const collaborationTicketClaimsSchema = z
     .object({
     sub: z.string().min(1),
@@ -96,7 +105,7 @@ export const collaborationTicketClaimsSchema = z
     emailVerified: z.boolean().optional(),
     room: z.string().min(1).max(4_096),
     scope: z.string().min(1).max(COMMENT_PAGE_PATH_MAX_LENGTH),
-    surface: z.enum(["published", "preview"]),
+    surface: collaborationSurfaceSchema,
     nonce: z.string().min(1).max(160),
     iat: z.number().int(),
     nbf: z.number().int(),
@@ -140,15 +149,43 @@ export const collaborationTicketClaimsSchema = z
         }
     }
 });
+// Where comments are reachable. One escalating axis, not two booleans: "off"
+// means nowhere, "previews" means the immutable Version hosts only, and
+// "everywhere" adds the published Space. Moving between them never requires a
+// republish — the always-injected inert tag re-reads the surface through the
+// runtime's same-origin Comments config exchange on every load.
+export const commentsSurfaceSchema = z.enum(["off", "previews", "everywhere"]);
+export const COMMENTS_EMBED_ORIGINS_MAX = 20;
+/**
+ * A site the Space owner allows the one-line Collab insert to run on.
+ *
+ * Exactly one https origin — scheme, host, and port, nothing else. No
+ * wildcards: on a foreign site this list IS the entitlement, and `*.example.com`
+ * hands it to every subdomain the site ever loses control of. An off-shape
+ * value is refused rather than normalized, so what the owner typed and what the
+ * server matches are the same string.
+ */
+export const commentsEmbedOriginSchema = z
+    .string()
+    .max(255)
+    .refine((value) => {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    return url.protocol === "https:" && url.origin === value && !url.hostname.includes("*");
+}, "must be an exact https origin, e.g. https://docs.example.com");
 export const collaborationSettingsSchema = z
     .object({
     spamFilterEnabled: z.boolean().optional(),
-    // Whether comments are surfaced on the live/published host (vs preview-only).
-    // The published loader (SPACEFAST-CAST-PLAN §4.2) mounts the orb on a live
-    // host only when this is true; toggling it never requires a republish — the
-    // always-injected inert tag re-reads it through the runtime's same-origin
-    // Comments config exchange on every load.
-    publishedComments: z.boolean().optional(),
+    surface: commentsSurfaceSchema.default("previews"),
+    // Non-empty is the embed toggle — there is no fourth `surface` state. An
+    // embed origin sees the Space at its "previews" tier and never the
+    // published Space itself.
+    embedOrigins: z.array(commentsEmbedOriginSchema).max(COMMENTS_EMBED_ORIGINS_MAX).default([]),
     notificationPreferences: z
         .object({
         newThreads: z.boolean().default(true),
@@ -162,7 +199,8 @@ export const collaborationSettingsSchema = z
 const collaborationSettingsPatchSchema = z
     .object({
     spamFilterEnabled: z.boolean().optional(),
-    publishedComments: z.boolean().optional(),
+    surface: commentsSurfaceSchema.optional(),
+    embedOrigins: z.array(commentsEmbedOriginSchema).max(COMMENTS_EMBED_ORIGINS_MAX).optional(),
     notificationPreferences: z
         .object({
         newThreads: z.boolean().optional(),
@@ -176,40 +214,92 @@ const collaborationSettingsPatchSchema = z
 export const collaborationSchema = z.object({
     spaceId: z.string(),
     revision: z.number().int().nonnegative(),
-    enabled: z.boolean(),
     castResourceId: z.string().nullable(),
     castResourceKey: z.string().nullable(),
     settings: collaborationSettingsSchema,
     createdAt: z.string().datetime().nullable(),
     updatedAt: z.string().datetime().nullable(),
 });
-export const collaborationUpdateSchema = z
-    .object({
+export const collaborationUpdateSchema = z.object({
     expectedRevision: z.number().int().nonnegative(),
-    enabled: z.boolean().optional(),
-    settings: collaborationSettingsPatchSchema.optional(),
-})
-    .refine((update) => update.enabled !== undefined || update.settings !== undefined, {
-    message: "At least one collaboration field is required",
+    settings: collaborationSettingsPatchSchema,
 });
-export const commentsTicketRequestSchema = z.object({
-    spaceId: z.string().min(1),
+/**
+ * The overlay's whole configuration, in one shape.
+ *
+ * Both lanes carry this: the Space's own origins get it from the runtime's
+ * same-origin exchange, a third-party site fetches it over CORS keyed by
+ * `data-space`. Only the transport differs — the SDK parses one shape.
+ */
+export const collabOverlayConfigSchema = z.object({
+    enabled: z.boolean(),
+    resource_key: z.string().nullable(),
+    room_key: z.string().nullable(),
+    version: z.object({
+        id: z.string().nullable(),
+        current: z.string().nullable(),
+        url: z.string().nullable(),
+    }),
+    space: z.object({ live_url: z.string().nullable() }),
+    theme: z.object({ accent: z.string().nullable(), hide_branding: z.boolean() }),
+    ws_url: z.string().nullable(),
+    endpoints: z.object({ ticket: z.string() }),
+    features: z.object({
+        picker: z.boolean().optional(),
+        drawing: z.boolean(),
+        capture: z.boolean(),
+        attachments: z.boolean(),
+        notices: z.boolean(),
+    }),
+});
+// What a third-party page may assert about itself. The display name only — the
+// anonymous id is the server's to own, and a browser that could choose one
+// could wear another visitor's identity.
+export const commentsEmbedIdentitySchema = collaborationGuestProjectionSchema.pick({
+    name: true,
+    namedByUser: true,
+});
+export const commentsEmbedTicketRequestSchema = z.object({
     pagePath: z.string().min(1).max(COMMENT_PAGE_PATH_MAX_LENGTH).default("/"),
-    origin: z.string().url(),
-    versionId: z.string().min(1).optional(),
-    identity: commentsGuestIdentitySchema.optional(),
+    identity: commentsEmbedIdentitySchema,
+    /**
+     * The opaque capability a previous mint on this Space + embed origin handed
+     * back. It carries the returning visitor's server-owned anonymous id; an
+     * absent, expired, or foreign one simply mints a new identity.
+     */
+    visitorToken: z.string().min(1).max(2_048).optional(),
 });
-export const commentsTicketResponseSchema = z.object({
+export const commentsEmbedTicketResponseSchema = z.object({
     token: z.string(),
     expiresAt: z.string().datetime(),
     cast: z.object({
         resource: z.string(),
         room: z.string(),
     }),
+    visitorToken: z.string(),
+    visitorExpiresAt: z.string().datetime(),
 });
-export const realtimeTokenRequestSchema = z.object({
-    versionId: z.string().optional(),
-    scope: z.enum(["space", "version"]).default("space"),
+export const commentsTicketResponseSchema = z.object({
+    token: z.string(),
+    expiresAt: z.string().datetime(),
+    cast: z.object({
+        resource: z.string(),
+        room: z.string(),
+        /** Where to open the socket. The client never assembles this itself. */
+        wsUrl: z.string().nullable(),
+    }),
+    /**
+     * The same session, bound to the Space's notice room. Cast binds a ticket to
+     * exactly one room, so an overlay that also wants Space-level notices needs
+     * a second ticket — never a second access decision. Null when this Space has
+     * notices switched off.
+     */
+    notice: z
+        .object({
+        token: z.string(),
+        room: z.string(),
+    })
+        .nullable(),
 });
 export const realtimeTokenResponseSchema = z.object({
     token: z.string(),
@@ -217,8 +307,16 @@ export const realtimeTokenResponseSchema = z.object({
     cast: z.object({
         resource: z.string(),
         room: z.string(),
+        wsUrl: z.string().nullable(),
     }),
 });
+/**
+ * A Space-level fact worth interrupting someone for. It travels as a `notice`
+ * on the Space's notice room — never as an event in a page room — because it
+ * is not conversation content: every open surface needs it regardless of which
+ * page it happens to be sitting on, including surfaces (the dashboard) that
+ * are in no page room at all.
+ */
 export const noticePublishSchema = z.object({
     versionId: z.string().optional(),
     kind: z.string().min(1).max(80).default("version.ready"),
@@ -226,13 +324,15 @@ export const noticePublishSchema = z.object({
     message: z.string().min(1).max(2_000),
     level: z.enum(["info", "success", "warning", "error"]).default("info"),
     payload: z.record(z.string(), z.unknown()).optional(),
-    durable: z.boolean().default(true),
-    idempotencyKey: z.string().min(1).max(320).optional(),
+});
+/** The wire shape of one notice, shared by the platform and comment lanes. */
+export const spaceNoticeSchema = z.looseObject({
+    kind: z.string().min(1),
+    version_id: z.string().nullable(),
 });
 export const noticePublishResponseSchema = z.object({
     status: z.string(),
-    event: z.record(z.string(), z.unknown()).nullable(),
-    broadcast: z.record(z.string(), z.unknown()).nullable(),
+    notice: spaceNoticeSchema,
 });
 // Cross-version navigation directory: the Comments overlay asks for the
 // immutable URLs of version ids present in a room's threads.
@@ -258,6 +358,40 @@ export const commentAuthorSchema = z.object({
     color: z.string().max(64).nullable(),
 });
 export const commentTargetSchema = z.record(z.string(), z.unknown()).nullable();
+/**
+ * How many attachments one thread or reply may carry. Mirrors Cast's own
+ * `@attachment_limit`: Cast is the authority that enforces it on write, this
+ * bound is what REST readers can rely on.
+ */
+export const COMMENT_ATTACHMENT_MAX_COUNT = 10;
+/**
+ * A pointer to a storage object on the Space's own runtime plus the descriptor
+ * needed to render it — never a URL. Cast stores exactly this (snake_case) under
+ * `metadata.attachments`; the id is a bare 32-hex object id.
+ */
+export const commentAttachmentSchema = z.object({
+    id: z.string().regex(/^[a-f0-9]{32}$/),
+    name: z.string().min(1).max(160),
+    contentType: z.string().min(1).max(255),
+    size: z
+        .number()
+        .int()
+        .min(1)
+        .max(5 * 1024 * 1024),
+    kind: z.enum(["screenshot", "image", "file"]),
+    // Document-normalized evidence rectangle. Screenshots only.
+    crop: z
+        .object({ x: z.number(), y: z.number(), width: z.number(), height: z.number() })
+        .optional(),
+});
+/**
+ * What a REST reader gets: the stored attachment plus a freshly composed read
+ * URL. `url` is null when the runtime's revocable read key cannot be resolved —
+ * an honest degraded read rather than a dead link or a dropped attachment.
+ */
+export const commentAttachmentViewSchema = commentAttachmentSchema.extend({
+    url: z.string().nullable(),
+});
 export const commentReactionActorSchema = z.object({
     name: z.string().nullable(),
 });
@@ -270,6 +404,14 @@ export const commentReactionUpdateSchema = z.object({
     emoji: z.enum(COMMENT_REACTION_EMOJIS),
     op: z.enum(["add", "remove"]),
 });
+/**
+ * A reply keeps Cast's own free-form shape; `attachments` is the one field the
+ * API composes rather than passes through (Cast carries it in the reply's
+ * `metadata`, without URLs).
+ */
+export const commentReplyViewSchema = z.looseObject({
+    attachments: z.array(commentAttachmentViewSchema),
+});
 export const commentThreadSchema = z.object({
     id: z.string(),
     castThreadId: z.string(),
@@ -287,7 +429,8 @@ export const commentThreadSchema = z.object({
     author: commentAuthorSchema.nullable(),
     target: commentTargetSchema,
     reactions: z.record(z.string(), commentReactionEntrySchema),
-    comments: z.array(z.record(z.string(), z.unknown())),
+    attachments: z.array(commentAttachmentViewSchema),
+    comments: z.array(commentReplyViewSchema),
     permalink: z.string().nullable(),
     updatedAt: z.string().datetime().nullable(),
 });
@@ -311,28 +454,6 @@ export const commentCreateSchema = z.object({
     target: commentTargetSchema.optional(),
     idempotencyKey: z.string().min(1).max(320).optional(),
 });
-export const commentScreenshotCreateSchema = z.object({
-    versionId: z.string().min(1),
-    pagePath: z.string().min(1).max(COMMENT_PAGE_PATH_MAX_LENGTH).default("/"),
-    contentType: z.enum(["image/png", "image/jpeg", "image/webp"]),
-    contentBase64: z.string().min(1),
-});
-export const commentScreenshotSchema = z.object({
-    id: z.string(),
-    key: z.string(),
-    url: z.string().url(),
-    expiresAt: z.string().datetime(),
-});
-export const commentScreenshotRefreshSchema = z.object({
-    versionId: z.string().min(1),
-    pagePath: z.string().min(1).max(COMMENT_PAGE_PATH_MAX_LENGTH).default("/"),
-    key: z.string().min(1).max(2_048),
-});
-export const commentScreenshotRefreshResponseSchema = z.object({
-    key: z.string(),
-    url: z.string().url(),
-    expiresAt: z.string().datetime(),
-});
 export const commentReplySchema = z.object({
     body: z.string().min(1).max(16_000),
     idempotencyKey: z.string().min(1).max(320).optional(),

package/dist/contracts/common.d.ts

@@ -9,8 +9,8 @@ export declare const baseDiagnosticSchema: z.ZodObject<{
     code: z.ZodString;
     severity: z.ZodEnum<{
         info: "info";
-        error: "error";
         warning: "warning";
+        error: "error";
     }>;
     message: z.ZodString;
     path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -176,8 +176,8 @@ export declare const AsyncOperationSchema: z.ZodObject<{
         code: z.ZodString;
         severity: z.ZodEnum<{
             info: "info";
-            error: "error";
             warning: "warning";
+            error: "error";
         }>;
         message: z.ZodString;
         path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -220,8 +220,8 @@ export declare function mutationEnvelope<T extends z.ZodType>(data: T): z.ZodObj
             code: z.ZodString;
             severity: z.ZodEnum<{
                 info: "info";
-                error: "error";
                 warning: "warning";
+                error: "error";
             }>;
             message: z.ZodString;
             path: z.ZodOptional<z.ZodNullable<z.ZodString>>;

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

@@ -81,6 +81,8 @@ export declare const DeviceAuthorizationPollResponseSchema: z.ZodObject<{
                     "spaces:write": "spaces:write";
                     "spaces:rename": "spaces:rename";
                     "domains:read": "domains:read";
+                    "spaces:publish": "spaces:publish";
+                    "builds:trigger": "builds:trigger";
                     "mcp:tools": "mcp:tools";
                     "*": "*";
                     "sites:read": "sites:read";
@@ -90,7 +92,6 @@ export declare const DeviceAuthorizationPollResponseSchema: z.ZodObject<{
                     "sites:policy.write": "sites:policy.write";
                     "spaces:create": "spaces:create";
                     "spaces:delete": "spaces:delete";
-                    "spaces:publish": "spaces:publish";
                     "spaces:transfer": "spaces:transfer";
                     "spaces:export": "spaces:export";
                     "spaces:import": "spaces:import";
@@ -109,7 +110,6 @@ export declare const DeviceAuthorizationPollResponseSchema: z.ZodObject<{
                     "webhooks:read": "webhooks:read";
                     "webhooks:write": "webhooks:write";
                     "builds:read": "builds:read";
-                    "builds:trigger": "builds:trigger";
                     "builds:create": "builds:create";
                     "teams:write": "teams:write";
                     "teams:members.write": "teams:members.write";
@@ -125,8 +125,8 @@ export declare const DeviceAuthorizationPollResponseSchema: z.ZodObject<{
                     "request.client": z.ZodOptional<z.ZodEnum<{
                         api: "api";
                         dashboard: "dashboard";
-                        worker: "worker";
                         cli: "cli";
+                        worker: "worker";
                     }>>;
                 }, z.core.$strict>>;
             }, z.core.$strict>>;
@@ -276,6 +276,8 @@ export declare const AgentHandoffRedeemResponseSchema: z.ZodObject<{
                     "spaces:write": "spaces:write";
                     "spaces:rename": "spaces:rename";
                     "domains:read": "domains:read";
+                    "spaces:publish": "spaces:publish";
+                    "builds:trigger": "builds:trigger";
                     "mcp:tools": "mcp:tools";
                     "*": "*";
                     "sites:read": "sites:read";
@@ -285,7 +287,6 @@ export declare const AgentHandoffRedeemResponseSchema: z.ZodObject<{
                     "sites:policy.write": "sites:policy.write";
                     "spaces:create": "spaces:create";
                     "spaces:delete": "spaces:delete";
-                    "spaces:publish": "spaces:publish";
                     "spaces:transfer": "spaces:transfer";
                     "spaces:export": "spaces:export";
                     "spaces:import": "spaces:import";
@@ -304,7 +305,6 @@ export declare const AgentHandoffRedeemResponseSchema: z.ZodObject<{
                     "webhooks:read": "webhooks:read";
                     "webhooks:write": "webhooks:write";
                     "builds:read": "builds:read";
-                    "builds:trigger": "builds:trigger";
                     "builds:create": "builds:create";
                     "teams:write": "teams:write";
                     "teams:members.write": "teams:members.write";
@@ -320,8 +320,8 @@ export declare const AgentHandoffRedeemResponseSchema: z.ZodObject<{
                     "request.client": z.ZodOptional<z.ZodEnum<{
                         api: "api";
                         dashboard: "dashboard";
-                        worker: "worker";
                         cli: "cli";
+                        worker: "worker";
                     }>>;
                 }, z.core.$strict>>;
             }, z.core.$strict>>;

package/dist/contracts/device-auth.js

@@ -37,7 +37,7 @@ export const DeviceAuthorizationStartRequestSchema = z
             .trim()
             .min(1)
             .max(512)
-            .describe("Anonymous-space claim token. Stored server-side only as a hash."),
+            .describe("Anonymous Space key. Stored server-side only as a hash."),
     })
         .strict()
         .optional()

package/dist/contracts/docs.d.ts

@@ -11,8 +11,8 @@ export declare const docsIndexQuerySchema: z.ZodObject<{
     category: z.ZodOptional<z.ZodEnum<{
         guide: "guide";
         api: "api";
-        error: "error";
         cli: "cli";
+        error: "error";
         workflow: "workflow";
         recipe: "recipe";
     }>>;
@@ -30,8 +30,8 @@ export declare const DocsEntrySchema: z.ZodObject<{
     category: z.ZodEnum<{
         guide: "guide";
         api: "api";
-        error: "error";
         cli: "cli";
+        error: "error";
         workflow: "workflow";
         recipe: "recipe";
     }>;
@@ -56,8 +56,8 @@ export declare const DocsDocSchema: z.ZodObject<{
     category: z.ZodEnum<{
         guide: "guide";
         api: "api";
-        error: "error";
         cli: "cli";
+        error: "error";
         workflow: "workflow";
         recipe: "recipe";
     }>;
@@ -86,8 +86,8 @@ export declare const DocsIndexResponseSchema: z.ZodObject<{
     category: z.ZodNullable<z.ZodEnum<{
         guide: "guide";
         api: "api";
-        error: "error";
         cli: "cli";
+        error: "error";
         workflow: "workflow";
         recipe: "recipe";
     }>>;
@@ -99,8 +99,8 @@ export declare const DocsIndexResponseSchema: z.ZodObject<{
         category: z.ZodEnum<{
             guide: "guide";
             api: "api";
-            error: "error";
             cli: "cli";
+            error: "error";
             workflow: "workflow";
             recipe: "recipe";
         }>;