@spacefast/common 0.0.26 → 0.2.2

package/dist/contracts/channels.js

@@ -1,12 +1,21 @@
 import { z } from "zod";
-// Channels READ surface (the platform spec "Channels"): a read-only
-// projection over the existing `channels` table and the `channel.promoted`
-// activity log. No writes, no new storage — promotion stays owned by the
-// publish/version lifecycle. Additive only.
-// One row of the channel list: where each named channel points right now.
+// Channels READ surface (the platform spec "Channels"): a projection over the
+// `channels` table and the `channel.promoted` activity log. No writes:
+// promotion stays owned by the publish/version lifecycle.
+// How a channel pointer moved: a fresh publish going live, a forward promote,
+// or a rollback to an older version. Recorded on the `channel.promoted` event
+// at write time; null on events that predate kind recording.
+export const channelChangeKindSchema = z.enum(["publish", "promote", "rollback"]);
+// The channel's most recent pointer move, straight from the promotion log.
+export const channelLastChangeSchema = z.object({
+    kind: channelChangeKindSchema
+        .nullable()
+        .describe("How the pointer moved, or null when the log entry predates kind recording."),
+    at: z.string().datetime().describe("Instant the pointer moved, from the promotion log."),
+});
 // `currentVersionId` is the channel's version pointer (`channels.versionId`).
 export const channelListItemSchema = z.object({
-    name: z.string().describe("Channel name; `live` is the default channel."),
+    name: z.string().describe("Channel name; `live` is the default."),
     currentVersionId: z
         .string()
         .nullable()
@@ -22,10 +31,13 @@ export const channelListItemSchema = z.object({
         .optional()
         .describe("Last version this channel served before the current pointer (rollback target)."),
     updatedAt: z.string().datetime().describe("Instant when this channel pointer last moved."),
+    lastChange: channelLastChangeSchema
+        .nullable()
+        .optional()
+        .describe("The most recent pointer move from the promotion log, or null when none exists."),
 });
 // One entry of a channel's promotion history (the deploy log): a single
-// `channel.promoted` event, newest first. This is the audit trail of every
-// pointer move on the channel.
+// `channel.promoted` event, newest first.
 export const channelHistoryEntrySchema = z.object({
     versionId: z.string().describe("Version the channel was promoted to."),
     channel: z.string().describe("Channel that moved."),
@@ -35,11 +47,15 @@ export const channelHistoryEntrySchema = z.object({
         .optional()
         .describe("Version the channel served immediately before this promotion."),
     actorType: z
-        .enum(["user", "api_key", "oauth_client", "anonymous_claim", "system"])
+        .enum(["user", "api_key", "partner_token", "oauth_client", "anonymous_claim", "system"])
         .nullable()
         .optional()
         .describe("Kind of actor that performed the promotion."),
     actorId: z.string().nullable().optional().describe("Identifier of the promoting actor."),
+    kind: channelChangeKindSchema
+        .nullable()
+        .optional()
+        .describe("How the pointer moved, or null when the entry predates kind recording."),
     at: z.string().datetime().describe("Instant when the promotion happened."),
 });
 export const channelListResponseSchema = z.object({

package/dist/contracts/cli.d.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 export declare const CLI_EXIT_CODES: {
     readonly ok: 0;
     readonly validation: 2;
@@ -8,3 +9,9 @@ export declare const CLI_EXIT_CODES: {
     readonly timeout: 50;
     readonly unknown: 1;
 };
+export declare const cliWarningSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    hint: z.ZodString;
+}, z.core.$strip>;
+export type CliWarning = z.infer<typeof cliWarningSchema>;

package/dist/contracts/cli.js

@@ -1,3 +1,4 @@
+import { z } from "zod";
 export const CLI_EXIT_CODES = {
     ok: 0,
     validation: 2,
@@ -8,3 +9,8 @@ export const CLI_EXIT_CODES = {
     timeout: 50,
     unknown: 1,
 };
+export const cliWarningSchema = z.object({
+    code: z.string().min(1),
+    message: z.string().min(1),
+    hint: z.string().min(1),
+});

package/dist/contracts/collab-public.d.ts

@@ -6,7 +6,7 @@ export declare const publicActorSchema: z.ZodObject<{
     avatar_url: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type PublicActor = z.infer<typeof publicActorSchema>;
-/** A thread as a list renders it — the body is an excerpt, the anchor is gone. */
+/** A thread as a list renders it. The body is an excerpt, the anchor is gone. */
 export declare const publicThreadSchema: z.ZodObject<{
     id: z.ZodString;
     path: z.ZodString;

package/dist/contracts/collab-public.js

@@ -1,10 +1,7 @@
-// The Collab public types — the sanitized shapes every collab surface emits or
-// renders (collab-public-api.html §5). One home: the SDK, the overlay, the
-// dashboard bridge, the control-plane projection and any published layout all
-// import from here. Re-exported nowhere.
-//
-// Sanitized means sanitized: no emails, no raw authority refs, no anchors. A
-// custom layout can restyle everything these carry and escalate nothing.
+// The sanitized shapes every collab surface emits or renders
+// (collab-public-api.html §5). One home, imported directly, re-exported nowhere.
+// Sanitized means no emails, no raw authority refs, no anchors: a custom layout
+// can restyle everything these carry and escalate nothing.
 import { z } from "zod";
 /** A person, as everyone else may see them. Identity colors are not themeable. */
 export const publicActorSchema = z.object({
@@ -12,7 +9,7 @@ export const publicActorSchema = z.object({
     color: z.string().min(1).max(32),
     avatar_url: z.string().url().max(2048).optional(),
 });
-/** A thread as a list renders it — the body is an excerpt, the anchor is gone. */
+/** A thread as a list renders it. The body is an excerpt, the anchor is gone. */
 export const publicThreadSchema = z.object({
     id: z.string().min(1).max(128),
     path: z.string().min(1).max(2048),

package/dist/contracts/comments.d.ts

@@ -4,6 +4,17 @@ export declare const commentThreadStatusSchema: z.ZodEnum<{
     open: "open";
     archived: "archived";
 }>;
+/**
+ * What a moderator may ask a thread to become. Spam is not a stored status —
+ * Cast holds it as the thread's moderation state — so "spam" is a verdict the
+ * wire accepts, and reading a thread back always reports `open` or `archived`
+ * with `moderationState` beside it.
+ */
+export declare const commentThreadStatusPatchSchema: z.ZodEnum<{
+    open: "open";
+    spam: "spam";
+    archived: "archived";
+}>;
 export declare const COMMENT_SEARCH_QUERY_MAX_LENGTH = 160;
 export declare function normalizeCommentSearchQuery(value: string | undefined): string | undefined;
 export declare const COMMENT_PAGE_PATH_MAX_LENGTH = 2048;
@@ -41,12 +52,10 @@ export declare const collaborationPublicProfileSchema: z.ZodObject<{
 }, z.core.$strict>;
 export type CollaborationPublicProfile = z.infer<typeof collaborationPublicProfileSchema>;
 /**
- * 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.
+ * Where the browser holding this ticket is. "embed" is a third-party site the
+ * owner allowlisted, kept a separate state so no foreign origin passes as a
+ * published host: an embed ticket's room is origin-scoped, and both the mint
+ * and Cast refuse the pairing in either direction.
  */
 export declare const collaborationSurfaceSchema: z.ZodEnum<{
     preview: "preview";
@@ -63,9 +72,9 @@ export declare const collaborationTicketClaimsSchema: z.ZodObject<{
         avatar_url: z.ZodNullable<z.ZodURL>;
     }, z.core.$strict>>;
     role: z.ZodEnum<{
+        editor: "editor";
         viewer: "viewer";
         commenter: "commenter";
-        editor: "editor";
         manager: "manager";
     }>;
     actorKind: z.ZodEnum<{
@@ -97,6 +106,8 @@ export declare const collaborationTicketClaimsSchema: z.ZodObject<{
     iss: z.ZodLiteral<"spacefast-api">;
     aud: z.ZodString;
 }, z.core.$strip>;
+/** Where a team without the collab.comments feature applies for access. */
+export declare const COMMENTS_WAITLIST_URL = "https://spacefast.com/waitlists/collab";
 export declare const commentsSurfaceSchema: z.ZodEnum<{
     off: "off";
     previews: "previews";
@@ -104,13 +115,11 @@ export declare const commentsSurfaceSchema: z.ZodEnum<{
 }>;
 export declare 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.
+ * A site the Space owner allows the one-line Collab insert to run on. Exactly
+ * one https origin, nothing else: 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
+ * the owner's string and the matched string are the same.
  */
 export declare const commentsEmbedOriginSchema: z.ZodString;
 export declare const collaborationSettingsSchema: z.ZodObject<{
@@ -167,11 +176,9 @@ export declare const collaborationUpdateSchema: z.ZodObject<{
     }, z.core.$strict>;
 }, z.core.$strip>;
 /**
- * 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.
+ * The overlay's whole configuration. Both lanes carry it: the Space's own
+ * origins from the runtime's same-origin exchange, a third-party site over CORS
+ * keyed by `data-space`. Only the transport differs.
  */
 export declare const collabOverlayConfigSchema: z.ZodObject<{
     enabled: z.ZodBoolean;
@@ -247,11 +254,9 @@ export declare const realtimeTokenResponseSchema: z.ZodObject<{
     }, z.core.$strip>;
 }, z.core.$strip>;
 /**
- * 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.
+ * A Space-level fact worth interrupting someone for. It travels on the Space's
+ * notice room, never as a page-room event: every open surface needs it whatever
+ * page it is on, including the dashboard, which is in no page room at all.
  */
 export declare const noticePublishSchema: z.ZodObject<{
     versionId: z.ZodOptional<z.ZodString>;
@@ -261,8 +266,8 @@ export declare const noticePublishSchema: z.ZodObject<{
     level: z.ZodDefault<z.ZodEnum<{
         info: "info";
         success: "success";
-        error: "error";
         warning: "warning";
+        error: "error";
     }>>;
     payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
@@ -296,14 +301,13 @@ export declare const commentAuthorSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const commentTargetSchema: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 /**
- * 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.
+ * How many attachments one thread or reply may carry. Mirrors Cast's
+ * `@attachment_limit`: Cast enforces it on write, this is what REST readers get.
  */
 export declare 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
+ * 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 declare const commentAttachmentSchema: z.ZodObject<{
@@ -324,9 +328,8 @@ export declare const commentAttachmentSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 /**
- * 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.
+ * The stored attachment plus a freshly composed read URL. `url` is null when the
+ * runtime's revocable read key cannot be resolved.
  */
 export declare const commentAttachmentViewSchema: z.ZodObject<{
     id: z.ZodString;
@@ -490,9 +493,6 @@ export declare const commentListQuerySchema: z.ZodObject<{
     author: z.ZodOptional<z.ZodString>;
     unread: z.ZodOptional<z.ZodCodec<z.ZodString, z.ZodBoolean>>;
 }, z.core.$strip>;
-export declare const commentSpamFeedbackSchema: z.ZodDefault<z.ZodObject<{
-    commentId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>>;
 export declare const commentCreateSchema: z.ZodObject<{
     pagePath: z.ZodDefault<z.ZodString>;
     body: z.ZodString;
@@ -503,11 +503,20 @@ export declare const commentReplySchema: z.ZodObject<{
     body: z.ZodString;
     idempotencyKey: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+export declare const commentReplyResponseSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        inserted: "inserted";
+        existing: "existing";
+    }>;
+    comment: z.ZodObject<{}, z.core.$loose>;
+}, z.core.$loose>;
 export declare const commentPatchSchema: z.ZodObject<{
     status: z.ZodOptional<z.ZodEnum<{
         open: "open";
+        spam: "spam";
         archived: "archived";
     }>>;
+    spamCommentId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const commentExportQuerySchema: z.ZodObject<{
     format: z.ZodDefault<z.ZodEnum<{
@@ -614,5 +623,6 @@ export type CollaborationUpdate = z.infer<typeof collaborationUpdateSchema>;
 export type CommentsSurface = z.infer<typeof commentsSurfaceSchema>;
 export type CollabVersionUrl = z.infer<typeof collabVersionUrlSchema>;
 export type CommentThread = z.infer<typeof commentThreadSchema>;
+export type CommentThreadStatusPatch = z.infer<typeof commentThreadStatusPatchSchema>;
 export type CommentAttachment = z.infer<typeof commentAttachmentSchema>;
 export type CommentAttachmentView = z.infer<typeof commentAttachmentViewSchema>;

package/dist/contracts/comments.js

@@ -2,6 +2,13 @@ import { z } from "zod";
 import { accessRoleSchema, authorityReferenceSchema } from "./access.js";
 import { CursorPaginationSchema, cursorListQuerySchema } from "./common.js";
 export const commentThreadStatusSchema = z.enum(["open", "archived"]);
+/**
+ * What a moderator may ask a thread to become. Spam is not a stored status —
+ * Cast holds it as the thread's moderation state — so "spam" is a verdict the
+ * wire accepts, and reading a thread back always reports `open` or `archived`
+ * with `moderationState` beside it.
+ */
+export const commentThreadStatusPatchSchema = z.enum(["open", "archived", "spam"]);
 export const COMMENT_SEARCH_QUERY_MAX_LENGTH = 160;
 export function normalizeCommentSearchQuery(value) {
     const trimmed = value?.trim();
@@ -32,8 +39,7 @@ export const commentCapabilitiesSchema = z
 });
 export const collaborationGuestProjectionSchema = z.object({
     anonymousId: z.string().min(8).max(160),
-    // No control or format characters: newlines, bidi overrides, and zero-width
-    // joiners in a self-asserted display name are only ever spoofing material.
+    // Control and format characters in a self-asserted name are spoofing material.
     name: z
         .string()
         .trim()
@@ -50,8 +56,7 @@ export const collaborationGuestProjectionSchema = z.object({
     emailVerified: z.boolean().default(false),
     capabilities: commentCapabilitiesSchema,
 });
-// The identity a browser asserts when requesting a guest ticket — the
-// self-asserted subset of the guest projection.
+// What a browser may assert about itself when requesting a guest ticket.
 export const commentsGuestIdentitySchema = collaborationGuestProjectionSchema.pick({
     anonymousId: true,
     name: true,
@@ -60,8 +65,7 @@ export const commentsGuestIdentitySchema = collaborationGuestProjectionSchema.pi
 export function commentCapabilitiesOf(capabilities) {
     return capabilities.filter((capability) => COMMENT_CAPABILITIES.includes(capability));
 }
-// The only account metadata exposed to Comments clients. Keep this shape
-// deliberately smaller than the private account record carried server-side.
+// The only account metadata exposed to Comments clients.
 export const collaborationPublicProfileSchema = z
     .object({
     name: z.string().trim().min(1).max(120).nullable(),
@@ -73,12 +77,10 @@ export const collaborationPublicProfileSchema = z
 })
     .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.
+ * Where the browser holding this ticket is. "embed" is a third-party site the
+ * owner allowlisted, kept a separate state so no foreign origin passes as a
+ * published host: an embed ticket's room 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
@@ -116,11 +118,9 @@ export const collaborationTicketClaimsSchema = z
     .superRefine((claims, context) => {
     if (claims.actorKind !== "guest")
         return;
-    // A guest ticket names an anonymous browser identity, and one grant always
-    // admitted it: the guest projection the mint builds carries all five of
-    // these or it is not a guest at all. Capabilities still come from the union
-    // of every authority the session holds — the admitting grant describes the
-    // admission, not the reach.
+    // The mint's guest projection carries all five or it is not a guest. The
+    // admitting grant describes the admission; capabilities come from the union
+    // of every authority the session holds.
     for (const field of [
         "anonymousId",
         "grantId",
@@ -136,9 +136,8 @@ export const collaborationTicketClaimsSchema = z
             });
         }
     }
-    // Identity never follows from an authority, but the reverse still holds:
-    // an anonymous principal can only ever have acquired credential-class
-    // authorities. Account-class references on a guest ticket are a forgery.
+    // An anonymous principal can only ever have acquired credential-class
+    // authorities, so an account-class reference on a guest ticket is a forgery.
     for (const [index, authority] of (claims.authorities ?? []).entries()) {
         if (!authority.startsWith("link:") && !authority.startsWith("password:")) {
             context.addIssue({
@@ -149,21 +148,20 @@ 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.
+// Where comments are reachable, as one escalating axis: "off" is nowhere,
+// "previews" is the immutable Version hosts only, "everywhere" adds the
+// published Space. Moving between them never requires a republish: the inert
+// tag re-reads the surface through the runtime's config exchange on every load.
+/** Where a team without the collab.comments feature applies for access. */
+export const COMMENTS_WAITLIST_URL = "https://spacefast.com/waitlists/collab";
 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.
+ * A site the Space owner allows the one-line Collab insert to run on. Exactly
+ * one https origin, nothing else: 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
+ * the owner's string and the matched string are the same.
  */
 export const commentsEmbedOriginSchema = z
     .string()
@@ -182,9 +180,8 @@ export const collaborationSettingsSchema = z
     .object({
     spamFilterEnabled: 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.
+    // Non-empty is the embed toggle; there is no fourth `surface` state. An embed
+    // origin sees the Space at its "previews" tier, never the published Space.
     embedOrigins: z.array(commentsEmbedOriginSchema).max(COMMENTS_EMBED_ORIGINS_MAX).default([]),
     notificationPreferences: z
         .object({
@@ -225,11 +222,9 @@ export const collaborationUpdateSchema = z.object({
     settings: collaborationSettingsPatchSchema,
 });
 /**
- * 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.
+ * The overlay's whole configuration. Both lanes carry it: the Space's own
+ * origins from the runtime's same-origin exchange, a third-party site over CORS
+ * keyed by `data-space`. Only the transport differs.
  */
 export const collabOverlayConfigSchema = z.object({
     enabled: z.boolean(),
@@ -252,9 +247,8 @@ export const collabOverlayConfigSchema = z.object({
         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.
+// What a third-party page may assert about itself: the display name only. A
+// browser that could choose its anonymous id could wear another visitor's.
 export const commentsEmbedIdentitySchema = collaborationGuestProjectionSchema.pick({
     name: true,
     namedByUser: true,
@@ -290,9 +284,8 @@ export const commentsTicketResponseSchema = z.object({
     }),
     /**
      * 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.
+     * exactly one room, so Space-level notices need a second ticket, never a
+     * second access decision. Null when this Space has notices switched off.
      */
     notice: z
         .object({
@@ -311,11 +304,9 @@ export const realtimeTokenResponseSchema = z.object({
     }),
 });
 /**
- * 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.
+ * A Space-level fact worth interrupting someone for. It travels on the Space's
+ * notice room, never as a page-room event: every open surface needs it whatever
+ * page it is on, including the dashboard, which is in no page room at all.
  */
 export const noticePublishSchema = z.object({
     versionId: z.string().optional(),
@@ -340,8 +331,7 @@ export const COLLAB_VERSION_URLS_MAX_IDS = 50;
 export const collabVersionUrlSchema = z.object({
     id: z.string(),
     url: z.string(),
-    // number/createdAt let clients order versions by real recency instead of
-    // comparing opaque ids.
+    // Ordering by real recency, instead of comparing opaque ids.
     number: z.number().int().nullable(),
     createdAt: z.string().nullable(),
 });
@@ -359,14 +349,13 @@ export const commentAuthorSchema = z.object({
 });
 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.
+ * How many attachments one thread or reply may carry. Mirrors Cast's
+ * `@attachment_limit`: Cast enforces it on write, this is what REST readers get.
  */
 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
+ * 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({
@@ -385,9 +374,8 @@ export const commentAttachmentSchema = z.object({
         .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.
+ * The stored attachment plus a freshly composed read URL. `url` is null when the
+ * runtime's revocable read key cannot be resolved.
  */
 export const commentAttachmentViewSchema = commentAttachmentSchema.extend({
     url: z.string().nullable(),
@@ -435,19 +423,36 @@ export const commentThreadSchema = z.object({
     updatedAt: z.string().datetime().nullable(),
 });
 export const commentListQuerySchema = cursorListQuerySchema.extend({
-    versionId: z.string().optional(),
-    status: commentThreadStatusSchema.optional(),
-    filter: z.enum(["open", "archived", "spam"]).optional(),
-    pagePath: z.string().max(COMMENT_PAGE_PATH_MAX_LENGTH).optional(),
-    q: z.string().trim().max(COMMENT_SEARCH_QUERY_MAX_LENGTH).optional(),
-    author: z.string().trim().max(160).optional(),
-    unread: z.stringbool().optional(),
-});
-export const commentSpamFeedbackSchema = z
-    .object({
-    commentId: z.string().min(1).optional(),
-})
-    .default({});
+    versionId: z.string().optional().describe("Return only threads anchored to this version."),
+    status: commentThreadStatusSchema
+        .optional()
+        .describe("Return only threads in this lifecycle state."),
+    filter: z
+        .enum(["open", "archived", "spam"])
+        .optional()
+        .describe("Named view. `open` and `archived` select a lifecycle state and win over `status`; `spam` lists the moderation-held threads, which requires comment-moderator access."),
+    pagePath: z
+        .string()
+        .max(COMMENT_PAGE_PATH_MAX_LENGTH)
+        .optional()
+        .describe("Return only threads anchored to this page path, for example `/pricing`."),
+    q: z
+        .string()
+        .trim()
+        .max(COMMENT_SEARCH_QUERY_MAX_LENGTH)
+        .optional()
+        .describe("Free-text search across thread and comment bodies."),
+    author: z
+        .string()
+        .trim()
+        .max(160)
+        .optional()
+        .describe("Return only threads started by this author name."),
+    unread: z
+        .stringbool()
+        .optional()
+        .describe("Return only threads that have unread comments for the caller."),
+});
 export const commentCreateSchema = z.object({
     pagePath: z.string().min(1).max(COMMENT_PAGE_PATH_MAX_LENGTH).default("/"),
     body: z.string().min(1).max(16_000),
@@ -458,12 +463,37 @@ export const commentReplySchema = z.object({
     body: z.string().min(1).max(16_000),
     idempotencyKey: z.string().min(1).max(320).optional(),
 });
-export const commentPatchSchema = z.object({
-    status: commentThreadStatusSchema.optional(),
+export const commentReplyResponseSchema = z.looseObject({
+    status: z.enum(["inserted", "existing"]),
+    comment: z.looseObject({}),
+});
+export const commentPatchSchema = z
+    .object({
+    status: commentThreadStatusPatchSchema.optional(),
+    /**
+     * The held reply the verdict is about; the thread itself when absent. It
+     * only means something next to a spam verdict, so it is refused elsewhere
+     * rather than silently dropped.
+     */
+    spamCommentId: z.string().min(1).optional(),
+})
+    .superRefine((patch, context) => {
+    if (patch.spamCommentId && patch.status !== "spam" && patch.status !== "open") {
+        context.addIssue({
+            code: "custom",
+            path: ["spamCommentId"],
+            message: "spamCommentId requires status open or spam",
+        });
+    }
 });
 export const commentExportQuerySchema = z.object({
-    format: z.enum(["markdown", "json"]).default("markdown"),
-    status: commentThreadStatusSchema.optional(),
+    format: z
+        .enum(["markdown", "json"])
+        .default("markdown")
+        .describe("Export shape: `markdown` to read, `json` to process."),
+    status: commentThreadStatusSchema
+        .optional()
+        .describe("Export only threads in this lifecycle state."),
 });
 export const commentListResponseSchema = z.object({
     data: z.array(commentThreadSchema),