@spacefast/common 0.0.12 → 0.0.13

package/dist/contracts/activity.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-export declare const ACTIVITY_EVENT_CODES: readonly ["space.created", "space.claimed", "feedback.lead_claim_pending", "space.transferred", "space.move_requested", "space.moved", "space.expired", "space.disabled", "space.enabled", "space.deleted", "space.config_updated", "space.slug_updated", "space.password_updated", "site.provision_requested", "site.placement_hold_set", "site.placement_hold_cleared", "site.burst_toggled", "space.access_logout_all", "space.access_transfer_scrub", "space.access_operator_token", "space.sharing_updated", "space.share_link_created", "space.share_link_revoked", "space.invite_created", "space.invite_revoked", "space.access_request_created", "space.access_request_resolved", "space.firewall_updated", "team.access_defaults_updated", "team.service_token_created", "team.service_token_revoked", "team.access_connection_created", "team.access_connection_updated", "team.access_connection_revoked", "version.created", "version.ready", "version.warning", "version.failed", "version.expired", "version.canceled", "version.deleted", "version.retention_warning", "version.retention_deleted", "channel.promoted", "build.created", "build.succeeded", "build.failed", "build.canceled", "build.skipped", "domain.created", "domain.verified", "domain.verification_failed", "domain.control_lost", "domain.dns_updated", "domain.nameservers_updated", "domain.registration_purchased", "domain.registration_renewed", "domain.registration_expiring", "domain.registration_expired", "domain.transfer_in_started", "domain.transfer_out_started", "domain.deleted", "domain.attached", "domain.activated", "domain.blocked", "domain.detached", "transfer.requested", "transfer.confirmed", "transfer.completed", "transfer.canceled", "transfer.expired", "transfer.failed", "variable.updated", "variable.deleted", "api_key.created", "api_key.updated", "api_key.revoked", "agent_handoff.created", "agent_handoff.redeemed", "agent_handoff.revoked", "webhook.created", "webhook.updated", "webhook.secret_rotated", "webhook.disabled", "webhook.deleted", "team.updated", "team.slug_updated", "team.member_added", "team.member_removed", "team.member_role_updated", "team.builds_deploys_quota_exceeded", "tenant.past_due", "tenant.suspended", "tenant.reactivated", "tenant.deleted", "export.ready", "export.failed", "import.ready", "import.failed", "comment.token_minted", "comment.created", "comment.reply_created", "comment.archived", "comment.unarchived", "abuse_report.created", "abuse_report.updated", "claim.blocked_takedown", "user.created", "user.signed_in", "user.deleted", "user.impersonation_started", "user.impersonation_stopped", "user.two_factor_enabled", "user.two_factor_disabled"];
+export declare const ACTIVITY_EVENT_CODES: readonly ["space.created", "space.claimed", "feedback.lead_claim_pending", "space.transferred", "space.move_requested", "space.moved", "space.expired", "space.disabled", "space.enabled", "space.deleted", "space.config_updated", "space.slug_updated", "site.provision_requested", "site.placement_hold_set", "site.placement_hold_cleared", "site.burst_toggled", "space.access_logout_all", "space.access_transfer_scrub", "space.share_link_created", "space.share_link_revoked", "space.access_request_created", "space.access_request_resolved", "space.grant_created", "space.grant_updated", "space.grant_revoked", "team.access_defaults_updated", "version.created", "version.ready", "version.warning", "version.failed", "version.expired", "version.canceled", "version.deleted", "version.retention_warning", "version.retention_deleted", "channel.promoted", "build.created", "build.succeeded", "build.failed", "build.canceled", "build.skipped", "domain.created", "domain.verified", "domain.verification_failed", "domain.control_lost", "domain.dns_updated", "domain.nameservers_updated", "domain.registration_purchased", "domain.registration_renewed", "domain.registration_expiring", "domain.registration_expired", "domain.transfer_in_started", "domain.transfer_out_started", "domain.deleted", "domain.attached", "domain.activated", "domain.blocked", "domain.detached", "transfer.requested", "transfer.confirmed", "transfer.completed", "transfer.canceled", "transfer.expired", "transfer.failed", "variable.updated", "variable.deleted", "api_key.created", "api_key.updated", "api_key.revoked", "agent_handoff.created", "agent_handoff.redeemed", "agent_handoff.revoked", "webhook.created", "webhook.updated", "webhook.secret_rotated", "webhook.disabled", "webhook.deleted", "team.updated", "team.slug_updated", "team.member_added", "team.member_removed", "team.member_role_updated", "team.builds_deploys_quota_exceeded", "tenant.past_due", "tenant.suspended", "tenant.reactivated", "tenant.deleted", "export.ready", "export.failed", "import.ready", "import.failed", "comment.token_minted", "comment.created", "comment.reply_created", "comment.archived", "comment.unarchived", "abuse_report.created", "abuse_report.updated", "claim.blocked_takedown", "claim.authority_rotated", "user.created", "user.signed_in", "user.deleted", "user.impersonation_started", "user.impersonation_stopped", "user.two_factor_enabled", "user.two_factor_disabled"];
 export type ActivityEventCode = (typeof ACTIVITY_EVENT_CODES)[number];
 export declare function isActivityEventCode(value: string): value is ActivityEventCode;
 export declare function isValidActivityEventFilter(filter: string): boolean;

package/dist/contracts/activity.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { AnyObjectSchema, CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
 // The single event taxonomy (internal-docs/platform.md "Event taxonomy").
 // Every emitted activity event and every webhook `events` filter selects on
-// these codes. Growth is additive-only: codes are never renamed or removed.
+// these codes.
 // `appendActivityEvent` is typed against this list, so emitting a code that is
 // not in the table is a typecheck (CI) failure.
 export const ACTIVITY_EVENT_CODES = [
@@ -19,31 +19,22 @@ export const ACTIVITY_EVENT_CODES = [
     "space.deleted",
     "space.config_updated",
     "space.slug_updated",
-    "space.password_updated",
     // site
     "site.provision_requested",
     "site.placement_hold_set",
     "site.placement_hold_cleared",
     "site.burst_toggled",
-    // access (internal-docs/access-plan.html): every access mutation emits an
-    // activity event; operator mints are audited and owner-visible (X-27).
+    // access
     "space.access_logout_all",
     "space.access_transfer_scrub",
-    "space.access_operator_token",
-    "space.sharing_updated",
     "space.share_link_created",
     "space.share_link_revoked",
-    "space.invite_created",
-    "space.invite_revoked",
     "space.access_request_created",
     "space.access_request_resolved",
-    "space.firewall_updated",
+    "space.grant_created",
+    "space.grant_updated",
+    "space.grant_revoked",
     "team.access_defaults_updated",
-    "team.service_token_created",
-    "team.service_token_revoked",
-    "team.access_connection_created",
-    "team.access_connection_updated",
-    "team.access_connection_revoked",
     // version
     "version.created",
     "version.ready",
@@ -135,6 +126,7 @@ export const ACTIVITY_EVENT_CODES = [
     // claim (additive extension: a claim attempt against a taken-down space is
     // flagged, never silently 404ed — internal-docs/platform.md "Abuse Posture")
     "claim.blocked_takedown",
+    "claim.authority_rotated",
     // user (additive extension: account lifecycle plus the 2FA and
     // admin-impersonation effects that must surface through ActivityEvent —
     // internal-docs/platform.md Better Auth usage). `user.created` fires once on

package/dist/contracts/api-keys.d.ts

@@ -5,6 +5,7 @@ export declare const StatticActionSchema: z.ZodEnum<{
     "teams:create": "teams:create";
     "spaces:read": "spaces:read";
     "spaces:write": "spaces:write";
+    "spaces:rename": "spaces:rename";
     "domains:read": "domains:read";
     "mcp:tools": "mcp:tools";
     "*": "*";
@@ -34,6 +35,7 @@ export declare const StatticActionSchema: z.ZodEnum<{
     "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";
@@ -87,6 +89,7 @@ export declare const ApiCredentialPolicySchema: z.ZodObject<{
             "teams:create": "teams:create";
             "spaces:read": "spaces:read";
             "spaces:write": "spaces:write";
+            "spaces:rename": "spaces:rename";
             "domains:read": "domains:read";
             "mcp:tools": "mcp:tools";
             "*": "*";
@@ -116,6 +119,7 @@ export declare const ApiCredentialPolicySchema: 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";
@@ -191,6 +195,7 @@ export declare const ApiKeySchema: z.ZodObject<{
                 "teams:create": "teams:create";
                 "spaces:read": "spaces:read";
                 "spaces:write": "spaces:write";
+                "spaces:rename": "spaces:rename";
                 "domains:read": "domains:read";
                 "mcp:tools": "mcp:tools";
                 "*": "*";
@@ -220,6 +225,7 @@ export declare const ApiKeySchema: 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";
@@ -303,6 +309,7 @@ export declare const ApiKeyListResponseSchema: z.ZodObject<{
                     "teams:create": "teams:create";
                     "spaces:read": "spaces:read";
                     "spaces:write": "spaces:write";
+                    "spaces:rename": "spaces:rename";
                     "domains:read": "domains:read";
                     "mcp:tools": "mcp:tools";
                     "*": "*";
@@ -332,6 +339,7 @@ export declare const ApiKeyListResponseSchema: 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";
@@ -395,6 +403,7 @@ export declare const ApiKeyCreateRequestSchema: z.ZodObject<{
                 "teams:create": "teams:create";
                 "spaces:read": "spaces:read";
                 "spaces:write": "spaces:write";
+                "spaces:rename": "spaces:rename";
                 "domains:read": "domains:read";
                 "mcp:tools": "mcp:tools";
                 "*": "*";
@@ -424,6 +433,7 @@ export declare const ApiKeyCreateRequestSchema: 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";
@@ -469,6 +479,7 @@ export declare const ApiKeyPatchRequestSchema: z.ZodObject<{
                 "teams:create": "teams:create";
                 "spaces:read": "spaces:read";
                 "spaces:write": "spaces:write";
+                "spaces:rename": "spaces:rename";
                 "domains:read": "domains:read";
                 "mcp:tools": "mcp:tools";
                 "*": "*";
@@ -498,6 +509,7 @@ export declare const ApiKeyPatchRequestSchema: 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";
@@ -542,6 +554,7 @@ export declare const ApiKeyScopedCreateRequestSchema: z.ZodObject<{
         "teams:create": "teams:create";
         "spaces:read": "spaces:read";
         "spaces:write": "spaces:write";
+        "spaces:rename": "spaces:rename";
         "domains:read": "domains:read";
         "mcp:tools": "mcp:tools";
         "*": "*";
@@ -571,6 +584,7 @@ export declare const ApiKeyScopedCreateRequestSchema: 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";
@@ -601,6 +615,7 @@ export declare const ApiKeyScopedPatchRequestSchema: z.ZodObject<{
         "teams:create": "teams:create";
         "spaces:read": "spaces:read";
         "spaces:write": "spaces:write";
+        "spaces:rename": "spaces:rename";
         "domains:read": "domains:read";
         "mcp:tools": "mcp:tools";
         "*": "*";
@@ -630,6 +645,7 @@ export declare const ApiKeyScopedPatchRequestSchema: 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";

package/dist/contracts/api-keys.js

@@ -11,6 +11,7 @@ export const StatticActionSchema = z.enum([
     "spaces:read",
     "spaces:create",
     "spaces:write",
+    "spaces:rename",
     "spaces:delete",
     "spaces:publish",
     "spaces:transfer",
@@ -32,6 +33,7 @@ export const StatticActionSchema = z.enum([
     "webhooks:read",
     "webhooks:write",
     "builds:read",
+    "builds:trigger",
     "builds:create",
     "teams:read",
     "teams:create",

package/dist/contracts/archives.d.ts

@@ -6,8 +6,7 @@ export declare const archiveListQuerySchema: z.ZodObject<{
 export declare const spaceExportRequestSchema: z.ZodObject<{
     versionIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
     includeFiles: z.ZodDefault<z.ZodBoolean>;
-    includeExplicitConfig: z.ZodDefault<z.ZodBoolean>;
-}, z.core.$strip>;
+}, z.core.$strict>;
 export declare const spaceExportArchiveSchema: z.ZodObject<{
     contentType: z.ZodLiteral<"application/zip">;
     downloadUrl: z.ZodString;

package/dist/contracts/archives.js

@@ -2,7 +2,8 @@ import { z } from "zod";
 import { baseDiagnosticSchema, CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
 import { uploadInstructionsSchema } from "./internal.js";
 export const archiveListQuerySchema = cursorListQuerySchema;
-export const spaceExportRequestSchema = z.object({
+export const spaceExportRequestSchema = z
+    .object({
     versionIds: z
         .array(z.string().min(1))
         .min(1)
@@ -12,11 +13,8 @@ export const spaceExportRequestSchema = z.object({
         .boolean()
         .default(true)
         .describe("Include version file trees and compiled serving artifacts. `false` produces a config-only archive that is not self-servable and cannot be re-imported."),
-    includeExplicitConfig: z
-        .boolean()
-        .default(true)
-        .describe("Include explicit space config (the space access policy) in the archive. Version manifests are always included."),
-});
+})
+    .strict();
 export const spaceExportArchiveSchema = z.object({
     // Zip-only contract: spacefast_export_v1 archives are always zip (the spec
     // allows "zip or tar"; one format keeps the enum honest).

package/dist/contracts/comments.d.ts

@@ -1,36 +1,70 @@
 import { z } from "zod";
+import type { GrantCapability } from "./grants.js";
 export declare const commentThreadStatusSchema: z.ZodEnum<{
     open: "open";
     archived: "archived";
 }>;
 export declare const COMMENT_SEARCH_QUERY_MAX_LENGTH = 160;
 export declare function normalizeCommentSearchQuery(value: string | undefined): string | undefined;
-export declare const collaborationReviewerLevelSchema: z.ZodEnum<{
-    viewer: "viewer";
-    commenter: "commenter";
-    editor: "editor";
-}>;
 export declare const COMMENT_PAGE_PATH_MAX_LENGTH = 2048;
-export declare const collaborationInvitedReviewerSchema: z.ZodObject<{
-    email: z.ZodString;
-    level: z.ZodEnum<{
+export declare const commentCapabilitiesSchema: z.ZodArray<z.ZodEnum<{
+    "page.view": "page.view";
+    "comments.read": "comments.read";
+    "comments.write": "comments.write";
+}>>;
+export type CommentCapability = Extract<GrantCapability, "page.view" | "comments.read" | "comments.write">;
+export type CommentCapabilities = CommentCapability[];
+export declare const collaborationGuestProjectionSchema: z.ZodObject<{
+    anonymousId: z.ZodString;
+    name: z.ZodString;
+    namedByUser: z.ZodBoolean;
+    grantId: z.ZodString;
+    admittedBy: z.ZodUnion<readonly [z.ZodLiteral<"anyone">, z.ZodTemplateLiteral<`link:${string}`>, z.ZodTemplateLiteral<`password:${string}`>]>;
+    emailVerified: z.ZodDefault<z.ZodBoolean>;
+    capabilities: z.ZodArray<z.ZodEnum<{
+        "page.view": "page.view";
+        "comments.read": "comments.read";
+        "comments.write": "comments.write";
+    }>>;
+}, z.core.$strip>;
+export type CollaborationGuestProjection = z.infer<typeof collaborationGuestProjectionSchema>;
+export declare const collaborationTicketClaimsSchema: z.ZodObject<{
+    sub: z.ZodString;
+    email: z.ZodOptional<z.ZodString>;
+    role: z.ZodEnum<{
         viewer: "viewer";
         commenter: "commenter";
         editor: "editor";
+        manager: "manager";
+    }>;
+    actorKind: z.ZodEnum<{
+        user: "user";
+        guest: "guest";
     }>;
+    capabilities: z.ZodArray<z.ZodEnum<{
+        "page.view": "page.view";
+        "comments.read": "comments.read";
+        "comments.write": "comments.write";
+    }>>;
+    anonymousId: z.ZodOptional<z.ZodString>;
+    namedByUser: z.ZodOptional<z.ZodBoolean>;
+    admittedBy: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"anyone">, z.ZodTemplateLiteral<`link:${string}`>, z.ZodTemplateLiteral<`password:${string}`>]>>;
+    emailVerified: z.ZodOptional<z.ZodBoolean>;
+    room: z.ZodString;
+    scope: z.ZodString;
+    surface: z.ZodEnum<{
+        preview: "preview";
+        published: "published";
+    }>;
+    nonce: z.ZodString;
+    iat: z.ZodNumber;
+    nbf: z.ZodNumber;
+    exp: z.ZodNumber;
+    iss: z.ZodLiteral<"spacefast-api">;
+    aud: z.ZodString;
 }, z.core.$strip>;
 export declare const collaborationSettingsSchema: z.ZodObject<{
-    anonymousReviewers: z.ZodOptional<z.ZodBoolean>;
-    publishedAnonymousCommenters: z.ZodOptional<z.ZodBoolean>;
     spamFilterEnabled: z.ZodOptional<z.ZodBoolean>;
-    invitedReviewers: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        email: z.ZodString;
-        level: z.ZodEnum<{
-            viewer: "viewer";
-            commenter: "commenter";
-            editor: "editor";
-        }>;
-    }, z.core.$strip>>>;
     publishedComments: z.ZodOptional<z.ZodBoolean>;
     notificationPreferences: z.ZodOptional<z.ZodObject<{
         newThreads: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
@@ -44,17 +78,7 @@ export declare const collaborationSchema: z.ZodObject<{
     castResourceId: z.ZodNullable<z.ZodString>;
     castResourceKey: z.ZodNullable<z.ZodString>;
     settings: z.ZodObject<{
-        anonymousReviewers: z.ZodOptional<z.ZodBoolean>;
-        publishedAnonymousCommenters: z.ZodOptional<z.ZodBoolean>;
         spamFilterEnabled: z.ZodOptional<z.ZodBoolean>;
-        invitedReviewers: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            email: z.ZodString;
-            level: z.ZodEnum<{
-                viewer: "viewer";
-                commenter: "commenter";
-                editor: "editor";
-            }>;
-        }, z.core.$strip>>>;
         publishedComments: z.ZodOptional<z.ZodBoolean>;
         notificationPreferences: z.ZodOptional<z.ZodObject<{
             newThreads: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
@@ -68,17 +92,7 @@ export declare const collaborationSchema: z.ZodObject<{
 export declare const collaborationUpdateSchema: z.ZodObject<{
     enabled: z.ZodBoolean;
     settings: z.ZodOptional<z.ZodObject<{
-        anonymousReviewers: z.ZodOptional<z.ZodBoolean>;
-        publishedAnonymousCommenters: z.ZodOptional<z.ZodBoolean>;
         spamFilterEnabled: z.ZodOptional<z.ZodBoolean>;
-        invitedReviewers: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            email: z.ZodString;
-            level: z.ZodEnum<{
-                viewer: "viewer";
-                commenter: "commenter";
-                editor: "editor";
-            }>;
-        }, z.core.$strip>>>;
         publishedComments: z.ZodOptional<z.ZodBoolean>;
         notificationPreferences: z.ZodOptional<z.ZodObject<{
             newThreads: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
@@ -87,13 +101,13 @@ export declare const collaborationUpdateSchema: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strict>>;
 }, z.core.$strip>;
-export declare const collaborationTokenRequestSchema: z.ZodObject<{
-    versionId: z.ZodOptional<z.ZodString>;
+export declare const commentsTicketRequestSchema: z.ZodObject<{
+    spaceId: z.ZodString;
     pagePath: z.ZodDefault<z.ZodString>;
-    anonymousId: z.ZodOptional<z.ZodString>;
-    displayName: z.ZodOptional<z.ZodString>;
+    origin: z.ZodString;
+    versionId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-export declare const collaborationTokenResponseSchema: z.ZodObject<{
+export declare const commentsTicketResponseSchema: z.ZodObject<{
     token: z.ZodString;
     expiresAt: z.ZodString;
     cast: z.ZodObject<{
@@ -101,18 +115,6 @@ export declare const collaborationTokenResponseSchema: z.ZodObject<{
         room: z.ZodString;
     }, z.core.$strip>;
 }, z.core.$strip>;
-export declare const collaborationHandoffRequestSchema: z.ZodObject<{
-    versionId: z.ZodString;
-    pagePath: z.ZodDefault<z.ZodString>;
-}, z.core.$strip>;
-export declare const collaborationHandoffResponseSchema: z.ZodObject<{
-    handoffToken: z.ZodString;
-    expiresAt: z.ZodString;
-    url: z.ZodNullable<z.ZodString>;
-}, z.core.$strip>;
-export declare const collaborationHandoffExchangeSchema: z.ZodObject<{
-    handoffToken: z.ZodString;
-}, z.core.$strip>;
 export declare const realtimeTokenRequestSchema: z.ZodObject<{
     versionId: z.ZodOptional<z.ZodString>;
     scope: z.ZodDefault<z.ZodEnum<{
@@ -155,37 +157,9 @@ export declare const collabOverlayConfigQuerySchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const collabOverlayConfigSchema: z.ZodObject<{
     enabled: z.ZodBoolean;
-    anonymous_commenters: z.ZodBoolean;
-    resource_key: z.ZodNullable<z.ZodString>;
-    room_key: z.ZodNullable<z.ZodString>;
-    version: z.ZodObject<{
-        id: z.ZodNullable<z.ZodString>;
-        current: z.ZodNullable<z.ZodString>;
-        url: z.ZodNullable<z.ZodString>;
-    }, z.core.$strip>;
-    space: z.ZodObject<{
-        live_url: z.ZodNullable<z.ZodString>;
-    }, z.core.$strip>;
-    ws_url: z.ZodNullable<z.ZodString>;
-    endpoints: z.ZodObject<{
-        token: z.ZodString;
-        handoff_exchange: z.ZodString;
-        auth_bridge: z.ZodString;
-        screenshots: z.ZodString;
-    }, z.core.$strip>;
-    features: z.ZodObject<{
-        drawing: z.ZodBoolean;
-        capture: z.ZodBoolean;
-        notices: z.ZodBoolean;
-    }, z.core.$strip>;
+    surface_url: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export declare const COLLAB_VERSION_URLS_MAX_IDS = 50;
-export declare const collabVersionUrlsQuerySchema: z.ZodObject<{
-    path: z.ZodOptional<z.ZodString>;
-    versionId: z.ZodOptional<z.ZodString>;
-    host: z.ZodOptional<z.ZodString>;
-    ids: z.ZodString;
-}, z.core.$strip>;
 export declare const collabVersionUrlSchema: z.ZodObject<{
     id: z.ZodString;
     url: z.ZodString;
@@ -337,7 +311,6 @@ export declare const commentExportResponseSchema: z.ZodObject<{
     }>;
     content: z.ZodString;
 }, z.core.$strip>;
-export type CollaborationInvitedReviewer = z.infer<typeof collaborationInvitedReviewerSchema>;
 export type Collaboration = z.infer<typeof collaborationSchema>;
 export type CollaborationUpdate = z.infer<typeof collaborationUpdateSchema>;
 export type CollabOverlayConfig = z.infer<typeof collabOverlayConfigSchema>;

package/dist/contracts/comments.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { accessRoleSchema } from "./access.js";
 import { CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
 export const commentThreadStatusSchema = z.enum(["open", "archived"]);
 export const COMMENT_SEARCH_QUERY_MAX_LENGTH = 160;
@@ -6,24 +7,85 @@ export function normalizeCommentSearchQuery(value) {
     const trimmed = value?.trim();
     return trimmed ? trimmed.slice(0, COMMENT_SEARCH_QUERY_MAX_LENGTH) : undefined;
 }
-// The space access levels capability follows (SPACEFAST-CAST-PLAN D-2). Invited
-// reviewers are space invitees with one of these levels; the on-page overlay and
-// inbox re-evaluate the effective level server-side at join — this is only the
-// stored grant the dashboard manages.
-export const collaborationReviewerLevelSchema = z.enum(["viewer", "commenter", "editor"]);
 export const COMMENT_PAGE_PATH_MAX_LENGTH = 2_048;
-// An invited reviewer: request input projected into the access lane's canonical
-// `cast_reviewer` managed block. It is never mirrored into collaboration settings.
-export const collaborationInvitedReviewerSchema = z.object({
-    email: z.string().email(),
-    level: collaborationReviewerLevelSchema,
+const COMMENT_CAPABILITIES = ["page.view", "comments.read", "comments.write"];
+export const commentCapabilitiesSchema = z
+    .array(z.enum(COMMENT_CAPABILITIES))
+    .min(2)
+    .max(3)
+    .refine((capabilities) => new Set(capabilities).size === capabilities.length, {
+    message: "comment capabilities must be unique",
+})
+    .superRefine((capabilities, context) => {
+    if (capabilities.includes("comments.write") && !capabilities.includes("comments.read")) {
+        context.addIssue({
+            code: "custom",
+            message: "comments.write requires comments.read",
+        });
+    }
+    if (capabilities.includes("comments.read") && !capabilities.includes("page.view")) {
+        context.addIssue({
+            code: "custom",
+            message: "comments.read requires page.view",
+        });
+    }
+});
+export const collaborationGuestProjectionSchema = z.object({
+    anonymousId: z.string().min(8).max(160),
+    name: z.string().trim().min(1).max(160),
+    namedByUser: z.boolean(),
+    grantId: z.string().min(1).max(128),
+    admittedBy: z.union([
+        z.literal("anyone"),
+        z.templateLiteral(["link:", z.string().regex(/^[A-Za-z0-9_.-]+$/)]),
+        z.templateLiteral(["password:", z.string().regex(/^[A-Za-z0-9_.-]+$/)]),
+    ]),
+    emailVerified: z.boolean().default(false),
+    capabilities: commentCapabilitiesSchema,
+});
+export const collaborationTicketClaimsSchema = z
+    .object({
+    sub: z.string().min(1),
+    email: z.string().email().optional(),
+    role: accessRoleSchema,
+    actorKind: z.enum(["user", "guest"]),
+    capabilities: commentCapabilitiesSchema,
+    anonymousId: z.string().min(8).max(160).optional(),
+    namedByUser: z.boolean().optional(),
+    admittedBy: z
+        .union([
+        z.literal("anyone"),
+        z.templateLiteral(["link:", z.string().regex(/^[A-Za-z0-9_.-]+$/)]),
+        z.templateLiteral(["password:", z.string().regex(/^[A-Za-z0-9_.-]+$/)]),
+    ])
+        .optional(),
+    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"]),
+    nonce: z.string().min(1).max(160),
+    iat: z.number().int(),
+    nbf: z.number().int(),
+    exp: z.number().int(),
+    iss: z.literal("spacefast-api"),
+    aud: z.string().min(1),
+})
+    .superRefine((claims, context) => {
+    if (claims.actorKind !== "guest")
+        return;
+    for (const field of ["anonymousId", "namedByUser", "admittedBy", "emailVerified"]) {
+        if (claims[field] === undefined) {
+            context.addIssue({
+                code: "custom",
+                path: [field],
+                message: `${field} is required for a guest ticket`,
+            });
+        }
+    }
 });
 export const collaborationSettingsSchema = z
     .object({
-    anonymousReviewers: z.boolean().optional(),
-    publishedAnonymousCommenters: z.boolean().optional(),
     spamFilterEnabled: z.boolean().optional(),
-    invitedReviewers: z.array(collaborationInvitedReviewerSchema).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
@@ -52,13 +114,13 @@ export const collaborationUpdateSchema = z.object({
     enabled: z.boolean(),
     settings: collaborationSettingsSchema.optional(),
 });
-export const collaborationTokenRequestSchema = z.object({
-    versionId: z.string().min(1).optional(),
+export const commentsTicketRequestSchema = z.object({
+    spaceId: z.string().min(1),
     pagePath: z.string().min(1).max(COMMENT_PAGE_PATH_MAX_LENGTH).default("/"),
-    anonymousId: z.string().min(1).max(160).optional(),
-    displayName: z.string().min(1).max(120).optional(),
+    origin: z.string().url(),
+    versionId: z.string().min(1).optional(),
 });
-export const collaborationTokenResponseSchema = z.object({
+export const commentsTicketResponseSchema = z.object({
     token: z.string(),
     expiresAt: z.string().datetime(),
     cast: z.object({
@@ -66,18 +128,6 @@ export const collaborationTokenResponseSchema = z.object({
         room: z.string(),
     }),
 });
-export const collaborationHandoffRequestSchema = z.object({
-    versionId: z.string().min(1),
-    pagePath: z.string().min(1).max(COMMENT_PAGE_PATH_MAX_LENGTH).default("/"),
-});
-export const collaborationHandoffResponseSchema = z.object({
-    handoffToken: z.string(),
-    expiresAt: z.string().datetime(),
-    url: z.string().url().nullable(),
-});
-export const collaborationHandoffExchangeSchema = z.object({
-    handoffToken: z.string().min(16),
-});
 export const realtimeTokenRequestSchema = z.object({
     versionId: z.string().optional(),
     scope: z.enum(["space", "version"]).default("space"),
@@ -110,47 +160,16 @@ export const collabOverlayConfigQuerySchema = z.object({
     versionId: z.string().min(1).optional(),
     host: z.string().min(1).optional(),
 });
-// Snake case is intentional: the injected Collab SDK consumes this alongside
-// Cast's snake-case join payload without a remapping layer.
+// Customer pages receive launcher state only. Room ids, Cast endpoints, resource
+// keys, tickets, and platform session state never cross the customer-origin
+// boundary.
 export const collabOverlayConfigSchema = z.object({
     enabled: z.boolean(),
-    anonymous_commenters: z.boolean(),
-    resource_key: z.string().nullable(),
-    room_key: z.string().nullable(),
-    version: z.object({
-        id: z.string().nullable(),
-        current: z.string().nullable(),
-        // The viewed version's immutable URL; null when unknown (live context).
-        url: z.string().nullable(),
-    }),
-    // The space's canonical live/published URL; null when comments-on-live is the
-    // current context (you're already there) or no live URL exists.
-    space: z.object({
-        live_url: z.string().nullable(),
-    }),
-    ws_url: z.string().nullable(),
-    endpoints: z.object({
-        token: z.string().url(),
-        handoff_exchange: z.string().url(),
-        auth_bridge: z.string().url(),
-        screenshots: z.string().url(),
-    }),
-    features: z.object({
-        drawing: z.boolean(),
-        capture: z.boolean(),
-        notices: z.boolean(),
-    }),
+    surface_url: z.string().url().nullable(),
 });
-// Cross-version navigation directory (§5 "versions are native"): the SDK asks
-// for the immutable URLs of the version ids present in a room's threads so
-// "Open this comment on v12" is a real link. Gated exactly like the overlay
-// config — disabled comments never leak version URLs.
+// Cross-version navigation directory: the platform Comments page asks for the
+// immutable URLs of version ids present in a room's threads.
 export const COLLAB_VERSION_URLS_MAX_IDS = 50;
-export const collabVersionUrlsQuerySchema = collabOverlayConfigQuerySchema.extend({
-    // Comma-separated version ids; the route caps the lookup at
-    // COLLAB_VERSION_URLS_MAX_IDS ids.
-    ids: z.string().min(1).max(4_096),
-});
 export const collabVersionUrlSchema = z.object({
     id: z.string(),
     url: z.string(),