@spacefast/common 0.0.2

package/dist/contracts/annotations.js

@@ -0,0 +1,234 @@
+import { z } from "zod";
+import { CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
+export const collaborationModeSchema = z.enum(["review"]);
+export const annotationThreadStatusSchema = z.enum(["open", "resolved", "archived"]);
+// 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"]);
+// An invited reviewer: a person (by email) granted a level on the space's review
+// surface. Kept in settingsJson so adding/removing reviewers never requires a
+// republish (read from the ETag'd overlay-config, SPACEFAST-CAST-PLAN §4.2).
+export const collaborationInvitedReviewerSchema = z.object({
+    email: z.string().email(),
+    level: collaborationReviewerLevelSchema,
+});
+export const collaborationSettingsSchema = z
+    .object({
+    anonymousReviewers: 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
+    // always-injected inert tag reads behavior from the ETag'd overlay-config.
+    publishedComments: z.boolean().optional(),
+    allowedOrigins: z.array(z.string().min(1)).optional(),
+    notificationPreferences: z
+        .object({
+        newThreads: z.boolean().default(true),
+        newReplies: z.boolean().default(true),
+        statusChanges: z.boolean().default(true),
+    })
+        .partial()
+        .optional(),
+})
+    .catchall(z.unknown());
+export const collaborationSchema = z.object({
+    spaceId: z.string(),
+    enabled: z.boolean(),
+    mode: collaborationModeSchema,
+    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({
+    enabled: z.boolean(),
+    mode: collaborationModeSchema.optional(),
+    settings: collaborationSettingsSchema.optional(),
+});
+export const collaborationTokenRequestSchema = z.object({
+    versionId: z.string().min(1).optional(),
+    pagePath: z.string().min(1).default("/"),
+    displayName: z.string().min(1).max(120).optional(),
+});
+export const collaborationTokenResponseSchema = z.object({
+    token: z.string(),
+    expiresAt: z.string().datetime(),
+    cast: z.object({
+        resource: z.string(),
+        room: z.string().nullable(),
+        loaderUrl: z.string().url(),
+    }),
+});
+export const collaborationHandoffRequestSchema = z.object({
+    versionId: z.string().min(1),
+    pagePath: z.string().min(1).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"),
+});
+export const realtimeTokenResponseSchema = z.object({
+    token: z.string(),
+    expiresAt: z.string().datetime(),
+    cast: z.object({
+        resource: z.string(),
+        room: z.string(),
+        loaderUrl: z.string().url(),
+    }),
+});
+export const noticePublishSchema = z.object({
+    versionId: z.string().optional(),
+    kind: z.string().min(1).max(80).default("version.ready"),
+    title: z.string().min(1).max(160),
+    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(),
+});
+export const noticePublishResponseSchema = z.object({
+    status: z.string(),
+    event: z.record(z.string(), z.unknown()).nullable(),
+    broadcast: z.record(z.string(), z.unknown()).nullable(),
+});
+export const overlayConfigQuerySchema = z.object({
+    path: z.string().min(1).optional(),
+    host: z.string().min(1).optional(),
+});
+export const overlayConfigSchema = z.object({
+    enabled: z.boolean(),
+    features: z.object({
+        annotations: z.boolean(),
+        anonymousReviewers: z.boolean(),
+        notices: z.boolean(),
+    }),
+    cast: z
+        .object({
+        loaderUrl: z.string().url(),
+        resource: z.string(),
+        room: z.string(),
+        wsUrl: z.string().url().nullable().optional(),
+        inboxUrl: z.string().url().nullable().optional(),
+        threadUrl: z.string().url().nullable().optional(),
+        tokenEndpoint: z.string().url(),
+        handoffEndpoint: z.string().url(),
+        authBridgeUrl: z.string().url(),
+    })
+        .nullable(),
+});
+// Public (cookie-optional) space-level overlay config (SPACEFAST-CAST-PLAN §3.2,
+// shared interfaces). Unlike the per-version overlay-config above, this is served
+// to anonymous public visitors with no version id, cross-origin from an arbitrary
+// published host. It returns ONLY the data a tiny loader needs to decide whether
+// to mount the orb and which room/embed/token URLs to use — never a token.
+export const publicOverlayConfigQuerySchema = z.object({
+    path: z.string().min(1).optional(),
+});
+export const publicOverlayConfigSchema = z.object({
+    // Whether collaboration is enabled for the space at all (the orb may mount).
+    enabled: z.boolean(),
+    // Whether comments are enabled on the live/published host (vs preview-only).
+    publishedComments: z.boolean(),
+    // Whether anonymous public visitors may join and comment without opening the
+    // auth bridge. The channel remains the authority for the actual action.
+    anonymousReviewers: z.boolean(),
+    // The room key for this page on the current live version (null when there is
+    // no ready version to anchor a room to).
+    room: z.string().nullable(),
+    // Cast resource key the SDK should join under.
+    resourceKey: z.string().nullable(),
+    // The current live version this page resolves to (null = no ready version).
+    version: z.object({
+        id: z.string().nullable(),
+        current: z.string().nullable(),
+    }),
+    // The Cast overlay SDK + realtime/embed/token endpoints the loader uses.
+    sdkUrl: z.string().url(),
+    wsUrl: z.string().nullable(),
+    inboxUrl: z.string().nullable(),
+    threadUrl: z.string().nullable(),
+    tokenUrl: z.string().url(),
+    // The cross-origin auth-bridge popup URL the published loader opens to mint a
+    // token without a third-party cookie (SPACEFAST-CAST-PLAN §4.2). Space-scoped
+    // so it works on any published host (no immutable version is in play).
+    authBridgeUrl: z.string().url(),
+    // The caller's effective space access level when resolvable from a session;
+    // null for anonymous public callers (no session cookie reaches this origin).
+    level: z.string().nullable(),
+});
+export const annotationAuthorSchema = z.object({
+    kind: z.string().nullable(),
+    id: z.string().nullable(),
+    name: z.string().nullable(),
+});
+export const annotationTargetSchema = z.record(z.string(), z.unknown()).nullable();
+export const annotationThreadSchema = z.object({
+    id: z.string(),
+    castThreadId: z.string(),
+    spaceId: z.string(),
+    versionId: z.string().nullable(),
+    channel: z.string().nullable(),
+    pagePath: z.string(),
+    url: z.string().nullable(),
+    status: annotationThreadStatusSchema,
+    body: z.string().nullable(),
+    author: annotationAuthorSchema.nullable(),
+    target: annotationTargetSchema,
+    comments: z.array(z.record(z.string(), z.unknown())),
+    permalink: z.string().nullable(),
+    updatedAt: z.string().datetime().nullable(),
+});
+export const annotationListQuerySchema = cursorListQuerySchema.extend({
+    versionId: z.string().optional(),
+    status: annotationThreadStatusSchema.optional(),
+    pagePath: z.string().optional(),
+});
+export const annotationCreateSchema = z.object({
+    pagePath: z.string().min(1).default("/"),
+    body: z.string().min(1).max(16_000),
+    target: annotationTargetSchema.optional(),
+    idempotencyKey: z.string().min(1).max(320).optional(),
+});
+export const annotationScreenshotCreateSchema = z.object({
+    versionId: z.string().min(1),
+    pagePath: z.string().min(1).default("/"),
+    contentType: z.enum(["image/png", "image/jpeg", "image/webp"]),
+    contentBase64: z.string().min(1),
+});
+export const annotationScreenshotSchema = z.object({
+    id: z.string(),
+    key: z.string(),
+    url: z.string().url(),
+    expiresAt: z.string().datetime(),
+});
+export const annotationReplySchema = z.object({
+    body: z.string().min(1).max(16_000),
+    idempotencyKey: z.string().min(1).max(320).optional(),
+});
+export const annotationPatchSchema = z.object({
+    status: annotationThreadStatusSchema.optional(),
+});
+export const annotationExportQuerySchema = z.object({
+    format: z.enum(["markdown", "json"]).default("markdown"),
+    status: annotationThreadStatusSchema.optional(),
+});
+export const annotationListResponseSchema = z.object({
+    data: z.array(annotationThreadSchema),
+    pagination: CursorPaginationSchema,
+});
+export const annotationExportResponseSchema = z.object({
+    format: z.enum(["markdown", "json"]),
+    content: z.string(),
+});