@bunizao/contracts 0.1.0 → 0.4.0

package/dist/analytics.js

@@ -11,15 +11,15 @@ var BLOG_ANALYTICS_READ_THRESHOLD_MS = 5000;
 var BLOG_ANALYTICS_COMPLETION_SCROLL_DEPTH = 0.9;
 var BLOG_ANALYTICS_RANGE_OPTIONS = [7, 30, 90];
 export {
-  NEWSLETTER_ANALYTICS_OPEN_ENDPOINT,
-  NEWSLETTER_ANALYTICS_CLICK_ENDPOINT,
-  LISTENING_ANALYTICS_EVENT_ENDPOINT,
-  BLOG_ANALYTICS_SUMMARY_ENDPOINT,
-  BLOG_ANALYTICS_READ_THRESHOLD_MS,
-  BLOG_ANALYTICS_RANGE_OPTIONS,
-  BLOG_ANALYTICS_EVENT_ENDPOINT,
-  BLOG_ANALYTICS_EVENTS_ENDPOINT,
-  BLOG_ANALYTICS_EVENTS_DEFAULT_LIMIT,
+  BLOG_ANALYTICS_ARTICLE_ENDPOINT,
   BLOG_ANALYTICS_COMPLETION_SCROLL_DEPTH,
-  BLOG_ANALYTICS_ARTICLE_ENDPOINT
+  BLOG_ANALYTICS_EVENTS_DEFAULT_LIMIT,
+  BLOG_ANALYTICS_EVENTS_ENDPOINT,
+  BLOG_ANALYTICS_EVENT_ENDPOINT,
+  BLOG_ANALYTICS_RANGE_OPTIONS,
+  BLOG_ANALYTICS_READ_THRESHOLD_MS,
+  BLOG_ANALYTICS_SUMMARY_ENDPOINT,
+  LISTENING_ANALYTICS_EVENT_ENDPOINT,
+  NEWSLETTER_ANALYTICS_CLICK_ENDPOINT,
+  NEWSLETTER_ANALYTICS_OPEN_ENDPOINT
 };

package/dist/comments.d.ts

@@ -0,0 +1,327 @@
+/**
+ * Blog comments, reactions, and reader identity on /blog/[slug]. v2 shape —
+ * see plans/blog-comments.md "Decisions taken (v2)" for the model this
+ * follows: anonymous-first participation through a risk stack, lazy and
+ * stateless email verification, one reader table shared with the newsletter.
+ *
+ * Reading is open to everyone. Posting a comment or reacting needs only a
+ * name, with an optional email — no session, no verification gate. Email verification
+ * is an upgrade path (grade L1/L2 in the PRD), never a door charge; the
+ * email address itself never crosses this boundary in a response body.
+ */
+export declare const READER_PROVIDERS: readonly ['email', 'github', 'google'];
+export type ReaderProvider = (typeof READER_PROVIDERS)[number];
+export declare const COMMENT_LOCALES: readonly ['zh', 'en'];
+export type CommentLocale = (typeof COMMENT_LOCALES)[number];
+/** The reader's standing, from "Identity: three grades, one table":
+ *    l0 — `reader_anon` cookie only, nothing verified
+ *    l1 — verified email (lazy verification link)
+ *    l2 — OAuth (GitHub or Google), phase 3 */
+export declare const READER_GRADES: readonly ['l0', 'l1', 'l2'];
+export type ReaderGrade = (typeof READER_GRADES)[number];
+export declare const COMMENT_STATUSES: readonly ['published', 'held', 'rejected', 'deleted'];
+export type CommentStatus = (typeof COMMENT_STATUSES)[number];
+export declare const MODERATION_ACTIONS: readonly ['publish', 'hold', 'reject', 'unsure'];
+export type ModerationAction = (typeof MODERATION_ACTIONS)[number];
+export declare const MODERATION_REASONS: readonly ['ok', 'spam', 'promotional', 'abuse', 'off_topic', 'personal_info'];
+export type ModerationReason = (typeof MODERATION_REASONS)[number];
+/** Never sent to a reader. Rides along on the owner's Telegram notification. */
+export interface ModerationVerdict {
+    action: ModerationAction;
+    reason: ModerationReason;
+    /** One short line explaining the call, in the language of the comment. */
+    note: string;
+}
+/** The calling browser's verified reader standing (L1/L2 only — an L0-only
+    visitor has no reader row and this is null). Never carries email or
+    email_hash; `avatarUrl` is always a same-origin proxy path. */
+export interface ReaderMe {
+    readerId: string;
+    grade: ReaderGrade;
+    provider: ReaderProvider;
+    displayName: string;
+    avatarUrl: string;
+    notifyReplies: boolean;
+    /** Whether this address holds an active newsletter subscription. */
+    subscribed: boolean;
+}
+export interface ReaderMeResult {
+    reader: ReaderMe | null;
+}
+/** The confirm button's POST — plans/blog-comments.md "Lazy verification". */
+export interface ReaderVerifyInput {
+    token: string;
+    /** Ticked "also subscribe" in the post-comment nudge. Activates the
+        subscription in the same POST — one email, one click, both confirmations. */
+    subscribe?: boolean;
+}
+export declare const READER_VERIFY_OUTCOMES: readonly ['confirmed', 'already_confirmed', 'expired', 'invalid'];
+export type ReaderVerifyOutcome = (typeof READER_VERIFY_OUTCOMES)[number];
+export interface ReaderVerifyResult {
+    outcome: ReaderVerifyOutcome;
+    reader: ReaderMe | null;
+}
+/** One conversation, quieted from the reply mail itself. The token is the
+    whole authentication: the reader is usually holding that mail on a device
+    that has never signed in here, and an off switch gated behind a sign-in is
+    one people reach by marking the sender spam instead. */
+export interface ReaderMuteInput {
+    token: string;
+    /** Omitted or true mutes; false is the undo the landing page offers. */
+    muted?: boolean;
+}
+export declare const READER_MUTE_OUTCOMES: readonly ['muted', 'unmuted', 'invalid'];
+export type ReaderMuteOutcome = (typeof READER_MUTE_OUTCOMES)[number];
+export interface ReaderMuteResult {
+    outcome: ReaderMuteOutcome;
+    /** Carried so the page can offer the wider switches without another call. */
+    postId?: string;
+}
+/** Re-send the verification mail. Rate-limited per address; always answers
+    the same shape regardless of whether the address has a comment on file,
+    so this can never be used to probe which addresses have commented. */
+export interface ReaderResendInput {
+    email: string;
+    /** Carries the original "notify me of replies" intent into the fresh
+        verification link, recovered from the stale token's payload. Optional;
+        a bare resend defaults to false. */
+    notifyReplies?: boolean;
+    locale?: CommentLocale;
+}
+export interface ReaderResendResult {
+    ok: boolean;
+}
+/** The two switches on the confirm page, and the only place a reader can move
+    them without an account. Session-authenticated (the cookie the verify POST
+    just set), so nothing here names an address. Both fields are optional: the
+    page sends only the one that was just toggled. */
+export interface ReaderPreferencesInput {
+    notifyReplies?: boolean;
+    subscribed?: boolean;
+}
+export interface ReaderPreferencesResult {
+    reader: ReaderMe | null;
+}
+export declare const REACTION_TARGET_TYPES: readonly ['post', 'comment'];
+export type ReactionTargetType = (typeof REACTION_TARGET_TYPES)[number];
+/** The only reaction shipped at launch. The storage layer is emoji-keyed anyway. */
+export declare const DEFAULT_REACTION_EMOJI = "\u2764\uFE0F";
+/** A face in the avatar stack beside a reaction count. Only identified
+    reactors (L1/L2, or an L0 reactor whose claimed email resolves) ever
+    appear here — see "Reactions: anonymous counts, identified faces". */
+export interface ReactorChip {
+    name: string;
+    avatarUrl: string | null;
+}
+export interface ReactionSummary {
+    emoji: string;
+    count: number;
+    /** Whether the calling browser (session or reader) holds this reaction. */
+    reacted: boolean;
+    /** Most recent identified reactors, newest first, capped server-side. */
+    reactors: ReactorChip[];
+}
+/** `${targetType}:${targetId}`, e.g. `post:abc123` or `comment:xyz789`. */
+export type ReactionTargetKey = string;
+export interface ReactionBatchResult {
+    reactions: Record<ReactionTargetKey, ReactionSummary[]>;
+}
+export interface ReactionToggleInput {
+    targetType: ReactionTargetType;
+    targetId: string;
+    emoji?: string;
+    /** Desired final state. Repeating the same request is safe. */
+    reacted: boolean;
+    /** `expectedAction: 'blog_reaction'` -- plans/blog-comments.md "The risk
+        stack" step 2. The widget solves invisibly (managed mode), so this
+        never costs the reader a prompt or a round trip of their own. */
+    turnstileToken: string;
+}
+export interface ReactionToggleResult {
+    reaction: ReactionSummary;
+}
+/** Public author view on a comment row. Never includes email or email_hash. */
+export interface CommentAuthor {
+    name: string;
+    /** Same-origin proxy path to the writer's cached avatar, or empty when no
+        avatar has resolved for their address (or they left none). Empty means
+        "draw your own": the endpoint behind this path answers an identicon for
+        any key it does not know, so a path emitted for every address would make
+        every face an identicon. */
+    avatarUrl: string;
+    /** True when this row's writer is the blog owner. */
+    byAuthor: boolean;
+}
+export interface Comment {
+    id: string;
+    /** Ghost's post.id, stable across slug renames. */
+    postId: string;
+    /** Always a root comment id, or null. Threading is one level deep. */
+    parentId: string | null;
+    author: CommentAuthor;
+    /** Plain text, 1-2000 chars. Escaping and autolinking happen at render. */
+    body: string;
+    status: CommentStatus;
+    createdAt: string;
+    editedAt: string | null;
+    /** True when this browser wrote the row (verified reader match, or the
+        `reader_anon` session matches). Highlights the row as yours; mutation
+        rights are signalled by `editableUntil`/`deletable`, not by this. */
+    mine: boolean;
+    /** Server clock deadline for the 15-minute edit window, ms since epoch.
+        Present only when the viewer is the verified reader who owns the row
+        and the window has not closed. Always null for session-owned rows --
+        anonymous comments cannot be edited. */
+    editableUntil: number | null;
+    /** True when the viewer may delete this row: verified reader owns it and
+        it is not already a tombstone. Always false for session-owned rows. */
+    deletable: boolean;
+    /** Soft-deleted but kept as a shape-preserving placeholder because a reply
+        hangs underneath it. `body`/`author` are empty on a tombstone. */
+    tombstone: boolean;
+}
+export interface CommentListResult {
+    comments: Comment[];
+    hasMore: boolean;
+    /** Cursor for the next page, or null when `hasMore` is false. */
+    nextBefore: string | null;
+    /** Published comments on the post (excludes held/rejected/deleted). */
+    total: number;
+}
+export interface CommentCreateInput {
+    postId: string;
+    body: string;
+    /** Root comment id this replies to. Omitted or null for a root comment. */
+    parentId?: string | null;
+    displayName: string;
+    /** Optional. Supplied: must be valid; triggers lazy verification and
+        enables claiming and a Gravatar-backed avatar.
+        Omitted or empty: the comment is owned by its anon session only and
+        the client renders an identicon. */
+    email?: string;
+    turnstileToken: string;
+    /** Visually-hidden honeypot field. Must arrive empty. */
+    website?: string;
+    /** Signed server timestamp minted at first interaction with the compose
+        box — see "The risk stack" step 4 (dwell time). */
+    dwellToken: string;
+    /** Reader accepted the post-comment subscribe offer. Only takes effect
+        once the address is verified. */
+    notifyReplies?: boolean;
+    locale?: CommentLocale;
+}
+export declare const COMMENT_CREATE_OUTCOMES: readonly ['published', 'held'];
+export type CommentCreateOutcome = (typeof COMMENT_CREATE_OUTCOMES)[number];
+export interface CommentCreateResult {
+    outcome: CommentCreateOutcome;
+    comment: Comment;
+    /** True when a supplied `email` was not already a verified reader — the
+        client shows the verification nudge (and, when accepted, the subscribe
+        offer). Always false when no email was supplied; the add-an-email
+        nudge is driven client-side by the missing address, not by this flag. */
+    unverifiedEmail: boolean;
+}
+export interface CommentEditInput {
+    body: string;
+}
+export interface CommentEditResult {
+    comment: Comment;
+}
+export interface CommentDeleteResult {
+    ok: true;
+    /** True when the row became a tombstone instead of disappearing, because
+        a reply hangs underneath it. */
+    tombstone: boolean;
+}
+/** What the comment section does on a post.
+ *
+ *    open     — the ordinary thread: read, write, reply.
+ *    readonly — everything already written stays readable; nothing new is
+ *               accepted. The section says so instead of offering a box.
+ *    off      — no comment section at all.
+ *
+ * `off` and `readonly` differ only in what the page draws; to the API both
+ * mean "this post takes no writes" (see `acceptsComments`). */
+export declare const COMMENTS_MODES: readonly ['open', 'readonly', 'off'];
+export type CommentsMode = (typeof COMMENTS_MODES)[number];
+export interface CommentPolicy {
+    mode: CommentsMode;
+    /** Whether the heart can be pressed — on the post and on its comments.
+        Independent of `mode`: a post can take reactions with comments off, and
+        an open thread can refuse them. */
+    reactions: boolean;
+    /** Accept a comment only from an address that has been verified. Anonymous
+        and unverified-email writers are refused rather than held. */
+    requireVerifiedEmail: boolean;
+}
+export declare const DEFAULT_COMMENT_POLICY: CommentPolicy;
+/** Ghost internal tags that override the site-wide default, one knob each.
+ *
+ * Internal tags are the switch because they are the only per-post field the
+ * author already edits in Ghost, and both halves of the system can read them:
+ * the site sees them through the Admin API at build time, site-api through the
+ * Content API at request time (`include=tags` returns internal tags). One
+ * source of truth, no settings table, no admin screen to keep in sync.
+ *
+ * `#no-comments` predates the others and is kept: it always meant "this post
+ * takes no more comments", which is `readonly`. */
+export declare const COMMENT_POLICY_TAGS: {
+    readonly 'comments-off': (policy: CommentPolicy) => {
+        /** Whether the heart can be pressed — on the post and on its comments.
+            Independent of `mode`: a post can take reactions with comments off, and
+            an open thread can refuse them. */
+        reactions: boolean;
+        /** Accept a comment only from an address that has been verified. Anonymous
+            and unverified-email writers are refused rather than held. */
+        requireVerifiedEmail: boolean;
+        mode: CommentsMode;
+    };
+    readonly 'comments-readonly': (policy: CommentPolicy) => {
+        /** Whether the heart can be pressed — on the post and on its comments.
+            Independent of `mode`: a post can take reactions with comments off, and
+            an open thread can refuse them. */
+        reactions: boolean;
+        /** Accept a comment only from an address that has been verified. Anonymous
+            and unverified-email writers are refused rather than held. */
+        requireVerifiedEmail: boolean;
+        mode: CommentsMode;
+    };
+    readonly 'no-comments': (policy: CommentPolicy) => {
+        /** Whether the heart can be pressed — on the post and on its comments.
+            Independent of `mode`: a post can take reactions with comments off, and
+            an open thread can refuse them. */
+        reactions: boolean;
+        /** Accept a comment only from an address that has been verified. Anonymous
+            and unverified-email writers are refused rather than held. */
+        requireVerifiedEmail: boolean;
+        mode: CommentsMode;
+    };
+    readonly 'reactions-off': (policy: CommentPolicy) => {
+        mode: CommentsMode;
+        /** Accept a comment only from an address that has been verified. Anonymous
+            and unverified-email writers are refused rather than held. */
+        requireVerifiedEmail: boolean;
+        reactions: false;
+    };
+    readonly 'comments-verified': (policy: CommentPolicy) => {
+        mode: CommentsMode;
+        /** Whether the heart can be pressed — on the post and on its comments.
+            Independent of `mode`: a post can take reactions with comments off, and
+            an open thread can refuse them. */
+        reactions: boolean;
+        requireVerifiedEmail: true;
+    };
+};
+/** A tag as either half of Ghost's pair: `#no-comments` is the name a person
+    types, `hash-no-comments` the slug the API returns beside it. */
+export interface CommentPolicyTagLike {
+    name?: string | null;
+    slug?: string | null;
+}
+/** Fold a post's tags onto the site-wide default. Order does not matter:
+    every tag sets one field, and a tag the map does not know is ignored. */
+export declare function commentPolicyFromTags(tags: readonly CommentPolicyTagLike[] | null | undefined, base?: CommentPolicy): CommentPolicy;
+/** Whether the post takes new comments — the one question the API asks. Both
+    `readonly` and `off` answer no; the difference between them is drawn, not
+    enforced. */
+export declare const acceptsComments: (policy: CommentPolicy) => boolean;

package/dist/comments.js

@@ -0,0 +1,72 @@
+// src/comments.ts
+var READER_PROVIDERS = ["email", "github", "google"];
+var COMMENT_LOCALES = ["zh", "en"];
+var READER_GRADES = ["l0", "l1", "l2"];
+var COMMENT_STATUSES = ["published", "held", "rejected", "deleted"];
+var MODERATION_ACTIONS = ["publish", "hold", "reject", "unsure"];
+var MODERATION_REASONS = [
+  "ok",
+  "spam",
+  "promotional",
+  "abuse",
+  "off_topic",
+  "personal_info"
+];
+var READER_VERIFY_OUTCOMES = ["confirmed", "already_confirmed", "expired", "invalid"];
+var READER_MUTE_OUTCOMES = ["muted", "unmuted", "invalid"];
+var REACTION_TARGET_TYPES = ["post", "comment"];
+var DEFAULT_REACTION_EMOJI = "❤️";
+var COMMENT_CREATE_OUTCOMES = ["published", "held"];
+var COMMENTS_MODES = ["open", "readonly", "off"];
+var DEFAULT_COMMENT_POLICY = {
+  mode: "open",
+  reactions: true,
+  requireVerifiedEmail: false
+};
+var COMMENT_POLICY_TAGS = {
+  "comments-off": (policy) => ({ ...policy, mode: "off" }),
+  "comments-readonly": (policy) => ({ ...policy, mode: "readonly" }),
+  "no-comments": (policy) => ({ ...policy, mode: "readonly" }),
+  "reactions-off": (policy) => ({ ...policy, reactions: false }),
+  "comments-verified": (policy) => ({ ...policy, requireVerifiedEmail: true })
+};
+var policyKeyOf = (tag) => {
+  const name = tag.name?.trim();
+  if (name?.startsWith("#"))
+    return name.slice(1).toLowerCase();
+  const slug = tag.slug?.trim().toLowerCase();
+  if (slug?.startsWith("hash-"))
+    return slug.slice(5);
+  return null;
+};
+function commentPolicyFromTags(tags, base = DEFAULT_COMMENT_POLICY) {
+  let policy = { ...base };
+  for (const tag of tags ?? []) {
+    const key = policyKeyOf(tag);
+    if (!key)
+      continue;
+    const apply = COMMENT_POLICY_TAGS[key];
+    if (apply)
+      policy = apply(policy);
+  }
+  return policy;
+}
+var acceptsComments = (policy) => policy.mode === "open";
+export {
+  COMMENTS_MODES,
+  COMMENT_CREATE_OUTCOMES,
+  COMMENT_LOCALES,
+  COMMENT_POLICY_TAGS,
+  COMMENT_STATUSES,
+  DEFAULT_COMMENT_POLICY,
+  DEFAULT_REACTION_EMOJI,
+  MODERATION_ACTIONS,
+  MODERATION_REASONS,
+  REACTION_TARGET_TYPES,
+  READER_GRADES,
+  READER_MUTE_OUTCOMES,
+  READER_PROVIDERS,
+  READER_VERIFY_OUTCOMES,
+  acceptsComments,
+  commentPolicyFromTags
+};

package/dist/content.js

@@ -18,6 +18,6 @@ function parsePostLocaleTag(tagName) {
   return canonicalSlug ? { locale, canonicalSlug } : { locale };
 }
 export {
-  parsePostLocaleTag,
-  CONTENT_DOCUMENT_SOURCES
+  CONTENT_DOCUMENT_SOURCES,
+  parsePostLocaleTag
 };

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 export * from './analytics';
 export * from './admin';
+export * from './comments';
 export * from './content';
 export * from './listening';
+export * from './messages';
 export * from './mood';
 export * from './notify';
 export * from './routes';

package/dist/index.js

@@ -11,6 +11,61 @@ var BLOG_ANALYTICS_READ_THRESHOLD_MS = 5000;
 var BLOG_ANALYTICS_COMPLETION_SCROLL_DEPTH = 0.9;
 var BLOG_ANALYTICS_RANGE_OPTIONS = [7, 30, 90];
 
+// src/comments.ts
+var READER_PROVIDERS = ["email", "github", "google"];
+var COMMENT_LOCALES = ["zh", "en"];
+var READER_GRADES = ["l0", "l1", "l2"];
+var COMMENT_STATUSES = ["published", "held", "rejected", "deleted"];
+var MODERATION_ACTIONS = ["publish", "hold", "reject", "unsure"];
+var MODERATION_REASONS = [
+  "ok",
+  "spam",
+  "promotional",
+  "abuse",
+  "off_topic",
+  "personal_info"
+];
+var READER_VERIFY_OUTCOMES = ["confirmed", "already_confirmed", "expired", "invalid"];
+var READER_MUTE_OUTCOMES = ["muted", "unmuted", "invalid"];
+var REACTION_TARGET_TYPES = ["post", "comment"];
+var DEFAULT_REACTION_EMOJI = "❤️";
+var COMMENT_CREATE_OUTCOMES = ["published", "held"];
+var COMMENTS_MODES = ["open", "readonly", "off"];
+var DEFAULT_COMMENT_POLICY = {
+  mode: "open",
+  reactions: true,
+  requireVerifiedEmail: false
+};
+var COMMENT_POLICY_TAGS = {
+  "comments-off": (policy) => ({ ...policy, mode: "off" }),
+  "comments-readonly": (policy) => ({ ...policy, mode: "readonly" }),
+  "no-comments": (policy) => ({ ...policy, mode: "readonly" }),
+  "reactions-off": (policy) => ({ ...policy, reactions: false }),
+  "comments-verified": (policy) => ({ ...policy, requireVerifiedEmail: true })
+};
+var policyKeyOf = (tag) => {
+  const name = tag.name?.trim();
+  if (name?.startsWith("#"))
+    return name.slice(1).toLowerCase();
+  const slug = tag.slug?.trim().toLowerCase();
+  if (slug?.startsWith("hash-"))
+    return slug.slice(5);
+  return null;
+};
+function commentPolicyFromTags(tags, base = DEFAULT_COMMENT_POLICY) {
+  let policy = { ...base };
+  for (const tag of tags ?? []) {
+    const key = policyKeyOf(tag);
+    if (!key)
+      continue;
+    const apply = COMMENT_POLICY_TAGS[key];
+    if (apply)
+      policy = apply(policy);
+  }
+  return policy;
+}
+var acceptsComments = (policy) => policy.mode === "open";
+
 // src/content.ts
 var CONTENT_DOCUMENT_SOURCES = ["mood", "post"];
 var POST_LOCALE_RE = /^[a-z]{2,8}(?:-[a-z0-9]{1,8})*$/;
@@ -30,6 +85,13 @@ function parsePostLocaleTag(tagName) {
   }
   return canonicalSlug ? { locale, canonicalSlug } : { locale };
 }
+// src/messages.ts
+var MESSAGE_LOCALES = ["zh", "en"];
+var MESSAGE_MIN_BODY_LENGTH = 2;
+var MESSAGE_MAX_BODY_LENGTH = 4000;
+var MESSAGE_MAX_NAME_LENGTH = 32;
+var MESSAGE_STATES = ["new", "read", "replied", "archived", "spam"];
+
 // src/mood.ts
 var MOOD_SENTIMENT_LABELS = ["joy", "calm", "melancholy", "anger", "anxiety", "neutral"];
 var MOOD_AI_MODELS = ["gpt-5.5", "gpt-5", "claude-sonnet-4.6"];
@@ -52,6 +114,20 @@ var MOOD_SEARCH_PATH = "/v2/mood/search";
 var MOOD_IMAGE_PROXY_BASE_PATH = "/v2/images";
 var MOOD_MEDIA_PROXY_BASE_PATH = "/v2/media";
 var LISTENING_PATH = "/v2/listening";
+var COMMENTS_PATH = "/v2/comments";
+var COMMENT_PATH_PREFIX = "/v2/comments/";
+var OWNER_MESSAGES_PATH = "/v2/messages";
+var REACTIONS_PATH = "/v2/reactions";
+var REACTIONS_TOGGLE_PATH = "/v2/reactions/toggle";
+var READER_ME_PATH = "/v2/reader/me";
+var READER_VERIFY_PATH = "/v2/reader/verify";
+var READER_RESEND_PATH = "/v2/reader/resend";
+var READER_PREFERENCES_PATH = "/v2/reader/preferences";
+var READER_MUTE_PATH = "/v2/reader/mute";
+var READER_AVATAR_PATH_PREFIX = "/v2/reader/avatar/";
+var READER_OAUTH_PATH_PREFIX = "/oauth/reader/";
+var READER_CONFIRM_PATH = "/reader/confirm";
+var READER_MUTE_PAGE_PATH = "/reader/mute";
 var ADMIN_BASE_PATH = "/admin";
 var NOTIFY_BASE_PATH = "/notify";
 var GHOST_WEBHOOK_PATH = "/webhooks/ghost";
@@ -114,67 +190,102 @@ var TELEGRAM_OPS_BROADCAST_STATUSES = [
   "failed"
 ];
 export {
-  telegramOpsSubscriberPath,
-  telegramOpsReminderDeliveredPath,
-  telegramOpsEventPath,
-  telegramOpsEventActionPath,
-  parsePostLocaleTag,
-  TELEGRAM_WEBHOOK_PATH,
-  TELEGRAM_OPS_WEBHOOK_PATH,
-  TELEGRAM_OPS_SUBSCRIBER_STATUSES,
-  TELEGRAM_OPS_SUBSCRIBERS_PATH,
-  TELEGRAM_OPS_REMINDERS_PATH,
-  TELEGRAM_OPS_REMINDERS_DUE_PATH,
-  TELEGRAM_OPS_OVERVIEW_PATH,
-  TELEGRAM_OPS_EVENTS_PATH,
-  TELEGRAM_OPS_BROADCAST_STATUSES,
-  TELEGRAM_OPS_BROADCAST_SEND_PATH,
-  TELEGRAM_OPS_BROADCAST_PREVIEW_PATH,
-  TELEGRAM_OPS_BROADCAST_DELIVERY_MODES,
-  TELEGRAM_OPS_BROADCAST_CHANNELS,
-  TELEGRAM_OPS_BROADCASTS_PATH,
-  TELEGRAM_OPS_BASE_PATH,
-  PING_PATH,
-  NOTIFY_GATE_STATES,
-  NOTIFY_GATE_RELEASE_PATH,
-  NOTIFY_GATE_PATH,
-  NOTIFY_GATE_DECISIONS,
-  NOTIFY_CHANNELS,
-  NOTIFY_BASE_PATH,
-  NEWSLETTER_ANALYTICS_OPEN_ENDPOINT,
-  NEWSLETTER_ANALYTICS_CLICK_ENDPOINT,
-  MUSICKIT_TOKEN_PATH,
-  MOOD_SENTIMENT_LABELS,
-  MOOD_SEARCH_PATH,
-  MOOD_PUBLIC_FEED_PATH,
-  MOOD_PUBLIC_COMMENTS_PATH,
-  MOOD_MEDIA_PROXY_BASE_PATH,
-  MOOD_LIVE_META_PATH,
-  MOOD_LIVE_FEED_PATH,
-  MOOD_LIVE_COUNTS_PATH,
-  MOOD_IMAGE_PROXY_BASE_PATH,
-  MOOD_ARCHIVE_STATS_PATH,
-  MOOD_ARCHIVE_FEED_PATH,
-  MOOD_AI_MODELS,
-  LISTENING_PATH,
-  LISTENING_ANALYTICS_EVENT_ENDPOINT,
-  LEGACY_NOTIFY_BASE_PATH,
-  LEGACY_MUSICKIT_TOKEN_PATH,
-  LEGACY_HEALTH_PATH,
-  LEGACY_GHOST_WEBHOOK_PATH,
-  LEGACY_ADMIN_BASE_PATH,
-  HEALTH_PATH,
-  GHOST_WEBHOOK_PATH,
-  EVENT_STATUSES,
-  CONTENT_DOCUMENT_SOURCES,
-  BLOG_ANALYTICS_SUMMARY_ENDPOINT,
-  BLOG_ANALYTICS_READ_THRESHOLD_MS,
-  BLOG_ANALYTICS_RANGE_OPTIONS,
-  BLOG_ANALYTICS_EVENT_ENDPOINT,
-  BLOG_ANALYTICS_EVENTS_ENDPOINT,
-  BLOG_ANALYTICS_EVENTS_DEFAULT_LIMIT,
-  BLOG_ANALYTICS_COMPLETION_SCROLL_DEPTH,
-  BLOG_ANALYTICS_ARTICLE_ENDPOINT,
+  ADMIN_BASE_PATH,
   API_PREFIX,
-  ADMIN_BASE_PATH
+  BLOG_ANALYTICS_ARTICLE_ENDPOINT,
+  BLOG_ANALYTICS_COMPLETION_SCROLL_DEPTH,
+  BLOG_ANALYTICS_EVENTS_DEFAULT_LIMIT,
+  BLOG_ANALYTICS_EVENTS_ENDPOINT,
+  BLOG_ANALYTICS_EVENT_ENDPOINT,
+  BLOG_ANALYTICS_RANGE_OPTIONS,
+  BLOG_ANALYTICS_READ_THRESHOLD_MS,
+  BLOG_ANALYTICS_SUMMARY_ENDPOINT,
+  COMMENTS_MODES,
+  COMMENTS_PATH,
+  COMMENT_CREATE_OUTCOMES,
+  COMMENT_LOCALES,
+  COMMENT_PATH_PREFIX,
+  COMMENT_POLICY_TAGS,
+  COMMENT_STATUSES,
+  CONTENT_DOCUMENT_SOURCES,
+  DEFAULT_COMMENT_POLICY,
+  DEFAULT_REACTION_EMOJI,
+  EVENT_STATUSES,
+  GHOST_WEBHOOK_PATH,
+  HEALTH_PATH,
+  LEGACY_ADMIN_BASE_PATH,
+  LEGACY_GHOST_WEBHOOK_PATH,
+  LEGACY_HEALTH_PATH,
+  LEGACY_MUSICKIT_TOKEN_PATH,
+  LEGACY_NOTIFY_BASE_PATH,
+  LISTENING_ANALYTICS_EVENT_ENDPOINT,
+  LISTENING_PATH,
+  MESSAGE_LOCALES,
+  MESSAGE_MAX_BODY_LENGTH,
+  MESSAGE_MAX_NAME_LENGTH,
+  MESSAGE_MIN_BODY_LENGTH,
+  MESSAGE_STATES,
+  MODERATION_ACTIONS,
+  MODERATION_REASONS,
+  MOOD_AI_MODELS,
+  MOOD_ARCHIVE_FEED_PATH,
+  MOOD_ARCHIVE_STATS_PATH,
+  MOOD_IMAGE_PROXY_BASE_PATH,
+  MOOD_LIVE_COUNTS_PATH,
+  MOOD_LIVE_FEED_PATH,
+  MOOD_LIVE_META_PATH,
+  MOOD_MEDIA_PROXY_BASE_PATH,
+  MOOD_PUBLIC_COMMENTS_PATH,
+  MOOD_PUBLIC_FEED_PATH,
+  MOOD_SEARCH_PATH,
+  MOOD_SENTIMENT_LABELS,
+  MUSICKIT_TOKEN_PATH,
+  NEWSLETTER_ANALYTICS_CLICK_ENDPOINT,
+  NEWSLETTER_ANALYTICS_OPEN_ENDPOINT,
+  NOTIFY_BASE_PATH,
+  NOTIFY_CHANNELS,
+  NOTIFY_GATE_DECISIONS,
+  NOTIFY_GATE_PATH,
+  NOTIFY_GATE_RELEASE_PATH,
+  NOTIFY_GATE_STATES,
+  OWNER_MESSAGES_PATH,
+  PING_PATH,
+  REACTIONS_PATH,
+  REACTIONS_TOGGLE_PATH,
+  REACTION_TARGET_TYPES,
+  READER_AVATAR_PATH_PREFIX,
+  READER_CONFIRM_PATH,
+  READER_GRADES,
+  READER_ME_PATH,
+  READER_MUTE_OUTCOMES,
+  READER_MUTE_PAGE_PATH,
+  READER_MUTE_PATH,
+  READER_OAUTH_PATH_PREFIX,
+  READER_PREFERENCES_PATH,
+  READER_PROVIDERS,
+  READER_RESEND_PATH,
+  READER_VERIFY_OUTCOMES,
+  READER_VERIFY_PATH,
+  TELEGRAM_OPS_BASE_PATH,
+  TELEGRAM_OPS_BROADCASTS_PATH,
+  TELEGRAM_OPS_BROADCAST_CHANNELS,
+  TELEGRAM_OPS_BROADCAST_DELIVERY_MODES,
+  TELEGRAM_OPS_BROADCAST_PREVIEW_PATH,
+  TELEGRAM_OPS_BROADCAST_SEND_PATH,
+  TELEGRAM_OPS_BROADCAST_STATUSES,
+  TELEGRAM_OPS_EVENTS_PATH,
+  TELEGRAM_OPS_OVERVIEW_PATH,
+  TELEGRAM_OPS_REMINDERS_DUE_PATH,
+  TELEGRAM_OPS_REMINDERS_PATH,
+  TELEGRAM_OPS_SUBSCRIBERS_PATH,
+  TELEGRAM_OPS_SUBSCRIBER_STATUSES,
+  TELEGRAM_OPS_WEBHOOK_PATH,
+  TELEGRAM_WEBHOOK_PATH,
+  acceptsComments,
+  commentPolicyFromTags,
+  parsePostLocaleTag,
+  telegramOpsEventActionPath,
+  telegramOpsEventPath,
+  telegramOpsReminderDeliveredPath,
+  telegramOpsSubscriberPath
 };

package/dist/messages.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Owner messages — the standalone form at /message.
+ *
+ * This is deliberately NOT the comments contract. A message is private by
+ * construction, not by moderation state: there is no `published`, no thread,
+ * no parent, no reactions, and no public read endpoint anywhere in this file.
+ * The comments stack answers "who may see this row"; here the answer is fixed
+ * at the storage layer, so a mis-written WHERE clause cannot leak one.
+ *
+ * What it does share with comments is everything that lives above the table:
+ * Turnstile, the honeypot and dwell tripwires, Akismet, the risk heuristics,
+ * reader identity, and the ops-bot notification. See site-api's
+ * features/messages/server/message-service.ts.
+ */
+export declare const MESSAGE_LOCALES: readonly ['zh', 'en'];
+export type MessageLocale = (typeof MESSAGE_LOCALES)[number];
+/** Body bounds, shared by the form's client-side validation and the service. */
+export declare const MESSAGE_MIN_BODY_LENGTH = 2;
+export declare const MESSAGE_MAX_BODY_LENGTH = 4000;
+export declare const MESSAGE_MAX_NAME_LENGTH = 32;
+/**
+ * Triage, not moderation. Every value here is private; none of them makes a
+ * message visible to anyone but the owner, which is why there is no
+ * `published` member to accidentally set.
+ *
+ *   new      — landed, not yet looked at
+ *   read     — the owner has seen it
+ *   replied  — answered from Telegram; `repliedAt` is set
+ *   archived — filed away by the owner
+ *   spam     — the risk stack or Akismet called it; never notified loudly
+ */
+export declare const MESSAGE_STATES: readonly ['new', 'read', 'replied', 'archived', 'spam'];
+export type MessageState = (typeof MESSAGE_STATES)[number];
+export interface OwnerMessageCreateInput {
+    /** Plain text, MESSAGE_MIN_BODY_LENGTH–MESSAGE_MAX_BODY_LENGTH characters. */
+    body: string;
+    displayName: string;
+    /**
+     * Optional, and optional on purpose — the same "channeling beats blocking"
+     * call the comment box makes. Supplied, it must be valid: it triggers the
+     * shared lazy-verification mail, and only a verified address can ever
+     * receive the owner's reply.
+     */
+    email?: string;
+    turnstileToken: string;
+    /** Minted by the form on load; proves the submit was not instant. */
+    dwellToken: string;
+    /** Honeypot. Any non-empty value is a silent drop. */
+    website?: string;
+    locale?: MessageLocale;
+}
+export interface OwnerMessageCreateResult {
+    id: string;
+    createdAt: string;
+    /**
+     * Whether the owner's reply can actually reach the sender. True only when
+     * the address belongs to a verified reader — an address typed into a public
+     * form is not proof that its owner sent anything, so an unverified one is
+     * never mailed. False also when no address was given at all; the form uses
+     * this to decide whether the receipt promises a reply or not.
+     */
+    replyable: boolean;
+    /**
+     * A verification mail just went out to a not-yet-verified address. The
+     * receipt tells the sender to click it if they want an answer.
+     */
+    verificationSent: boolean;
+}

package/dist/messages.js

@@ -0,0 +1,13 @@
+// src/messages.ts
+var MESSAGE_LOCALES = ["zh", "en"];
+var MESSAGE_MIN_BODY_LENGTH = 2;
+var MESSAGE_MAX_BODY_LENGTH = 4000;
+var MESSAGE_MAX_NAME_LENGTH = 32;
+var MESSAGE_STATES = ["new", "read", "replied", "archived", "spam"];
+export {
+  MESSAGE_LOCALES,
+  MESSAGE_MAX_BODY_LENGTH,
+  MESSAGE_MAX_NAME_LENGTH,
+  MESSAGE_MIN_BODY_LENGTH,
+  MESSAGE_STATES
+};

package/dist/mood.js

@@ -2,6 +2,6 @@
 var MOOD_SENTIMENT_LABELS = ["joy", "calm", "melancholy", "anger", "anxiety", "neutral"];
 var MOOD_AI_MODELS = ["gpt-5.5", "gpt-5", "claude-sonnet-4.6"];
 export {
-  MOOD_SENTIMENT_LABELS,
-  MOOD_AI_MODELS
+  MOOD_AI_MODELS,
+  MOOD_SENTIMENT_LABELS
 };

package/dist/routes.d.ts

@@ -12,6 +12,20 @@ export declare const MOOD_SEARCH_PATH: '/v2/mood/search';
 export declare const MOOD_IMAGE_PROXY_BASE_PATH: '/v2/images';
 export declare const MOOD_MEDIA_PROXY_BASE_PATH: '/v2/media';
 export declare const LISTENING_PATH: '/v2/listening';
+export declare const COMMENTS_PATH: '/v2/comments';
+export declare const COMMENT_PATH_PREFIX: '/v2/comments/';
+export declare const OWNER_MESSAGES_PATH: '/v2/messages';
+export declare const REACTIONS_PATH: '/v2/reactions';
+export declare const REACTIONS_TOGGLE_PATH: '/v2/reactions/toggle';
+export declare const READER_ME_PATH: '/v2/reader/me';
+export declare const READER_VERIFY_PATH: '/v2/reader/verify';
+export declare const READER_RESEND_PATH: '/v2/reader/resend';
+export declare const READER_PREFERENCES_PATH: '/v2/reader/preferences';
+export declare const READER_MUTE_PATH: '/v2/reader/mute';
+export declare const READER_AVATAR_PATH_PREFIX: '/v2/reader/avatar/';
+export declare const READER_OAUTH_PATH_PREFIX: '/oauth/reader/';
+export declare const READER_CONFIRM_PATH: '/reader/confirm';
+export declare const READER_MUTE_PAGE_PATH: '/reader/mute';
 export declare const ADMIN_BASE_PATH: '/admin';
 export declare const NOTIFY_BASE_PATH: '/notify';
 export declare const GHOST_WEBHOOK_PATH: '/webhooks/ghost';

package/dist/routes.js

@@ -13,6 +13,20 @@ var MOOD_SEARCH_PATH = "/v2/mood/search";
 var MOOD_IMAGE_PROXY_BASE_PATH = "/v2/images";
 var MOOD_MEDIA_PROXY_BASE_PATH = "/v2/media";
 var LISTENING_PATH = "/v2/listening";
+var COMMENTS_PATH = "/v2/comments";
+var COMMENT_PATH_PREFIX = "/v2/comments/";
+var OWNER_MESSAGES_PATH = "/v2/messages";
+var REACTIONS_PATH = "/v2/reactions";
+var REACTIONS_TOGGLE_PATH = "/v2/reactions/toggle";
+var READER_ME_PATH = "/v2/reader/me";
+var READER_VERIFY_PATH = "/v2/reader/verify";
+var READER_RESEND_PATH = "/v2/reader/resend";
+var READER_PREFERENCES_PATH = "/v2/reader/preferences";
+var READER_MUTE_PATH = "/v2/reader/mute";
+var READER_AVATAR_PATH_PREFIX = "/v2/reader/avatar/";
+var READER_OAUTH_PATH_PREFIX = "/oauth/reader/";
+var READER_CONFIRM_PATH = "/reader/confirm";
+var READER_MUTE_PAGE_PATH = "/reader/mute";
 var ADMIN_BASE_PATH = "/admin";
 var NOTIFY_BASE_PATH = "/notify";
 var GHOST_WEBHOOK_PATH = "/webhooks/ghost";
@@ -24,28 +38,42 @@ var LEGACY_GHOST_WEBHOOK_PATH = "/v2/ghost/webhook";
 var LEGACY_MUSICKIT_TOKEN_PATH = "/v2/musickit/token";
 var LEGACY_HEALTH_PATH = "/v2/health";
 export {
-  TELEGRAM_WEBHOOK_PATH,
-  PING_PATH,
-  NOTIFY_BASE_PATH,
-  MUSICKIT_TOKEN_PATH,
-  MOOD_SEARCH_PATH,
-  MOOD_PUBLIC_FEED_PATH,
-  MOOD_PUBLIC_COMMENTS_PATH,
-  MOOD_MEDIA_PROXY_BASE_PATH,
-  MOOD_LIVE_META_PATH,
-  MOOD_LIVE_FEED_PATH,
-  MOOD_LIVE_COUNTS_PATH,
-  MOOD_IMAGE_PROXY_BASE_PATH,
-  MOOD_ARCHIVE_STATS_PATH,
-  MOOD_ARCHIVE_FEED_PATH,
-  LISTENING_PATH,
-  LEGACY_NOTIFY_BASE_PATH,
-  LEGACY_MUSICKIT_TOKEN_PATH,
-  LEGACY_HEALTH_PATH,
-  LEGACY_GHOST_WEBHOOK_PATH,
-  LEGACY_ADMIN_BASE_PATH,
-  HEALTH_PATH,
-  GHOST_WEBHOOK_PATH,
+  ADMIN_BASE_PATH,
   API_PREFIX,
-  ADMIN_BASE_PATH
+  COMMENTS_PATH,
+  COMMENT_PATH_PREFIX,
+  GHOST_WEBHOOK_PATH,
+  HEALTH_PATH,
+  LEGACY_ADMIN_BASE_PATH,
+  LEGACY_GHOST_WEBHOOK_PATH,
+  LEGACY_HEALTH_PATH,
+  LEGACY_MUSICKIT_TOKEN_PATH,
+  LEGACY_NOTIFY_BASE_PATH,
+  LISTENING_PATH,
+  MOOD_ARCHIVE_FEED_PATH,
+  MOOD_ARCHIVE_STATS_PATH,
+  MOOD_IMAGE_PROXY_BASE_PATH,
+  MOOD_LIVE_COUNTS_PATH,
+  MOOD_LIVE_FEED_PATH,
+  MOOD_LIVE_META_PATH,
+  MOOD_MEDIA_PROXY_BASE_PATH,
+  MOOD_PUBLIC_COMMENTS_PATH,
+  MOOD_PUBLIC_FEED_PATH,
+  MOOD_SEARCH_PATH,
+  MUSICKIT_TOKEN_PATH,
+  NOTIFY_BASE_PATH,
+  OWNER_MESSAGES_PATH,
+  PING_PATH,
+  REACTIONS_PATH,
+  REACTIONS_TOGGLE_PATH,
+  READER_AVATAR_PATH_PREFIX,
+  READER_CONFIRM_PATH,
+  READER_ME_PATH,
+  READER_MUTE_PAGE_PATH,
+  READER_MUTE_PATH,
+  READER_OAUTH_PATH_PREFIX,
+  READER_PREFERENCES_PATH,
+  READER_RESEND_PATH,
+  READER_VERIFY_PATH,
+  TELEGRAM_WEBHOOK_PATH
 };

package/dist/telegram-ops.js

@@ -49,27 +49,27 @@ var TELEGRAM_OPS_BROADCAST_STATUSES = [
   "failed"
 ];
 export {
-  telegramOpsSubscriberPath,
-  telegramOpsReminderDeliveredPath,
-  telegramOpsEventPath,
-  telegramOpsEventActionPath,
-  TELEGRAM_OPS_WEBHOOK_PATH,
-  TELEGRAM_OPS_SUBSCRIBER_STATUSES,
-  TELEGRAM_OPS_SUBSCRIBERS_PATH,
-  TELEGRAM_OPS_REMINDERS_PATH,
-  TELEGRAM_OPS_REMINDERS_DUE_PATH,
-  TELEGRAM_OPS_OVERVIEW_PATH,
-  TELEGRAM_OPS_EVENTS_PATH,
-  TELEGRAM_OPS_BROADCAST_STATUSES,
-  TELEGRAM_OPS_BROADCAST_SEND_PATH,
-  TELEGRAM_OPS_BROADCAST_PREVIEW_PATH,
-  TELEGRAM_OPS_BROADCAST_DELIVERY_MODES,
-  TELEGRAM_OPS_BROADCAST_CHANNELS,
-  TELEGRAM_OPS_BROADCASTS_PATH,
-  TELEGRAM_OPS_BASE_PATH,
-  NOTIFY_GATE_STATES,
-  NOTIFY_GATE_RELEASE_PATH,
-  NOTIFY_GATE_PATH,
+  EVENT_STATUSES,
   NOTIFY_GATE_DECISIONS,
-  EVENT_STATUSES
+  NOTIFY_GATE_PATH,
+  NOTIFY_GATE_RELEASE_PATH,
+  NOTIFY_GATE_STATES,
+  TELEGRAM_OPS_BASE_PATH,
+  TELEGRAM_OPS_BROADCASTS_PATH,
+  TELEGRAM_OPS_BROADCAST_CHANNELS,
+  TELEGRAM_OPS_BROADCAST_DELIVERY_MODES,
+  TELEGRAM_OPS_BROADCAST_PREVIEW_PATH,
+  TELEGRAM_OPS_BROADCAST_SEND_PATH,
+  TELEGRAM_OPS_BROADCAST_STATUSES,
+  TELEGRAM_OPS_EVENTS_PATH,
+  TELEGRAM_OPS_OVERVIEW_PATH,
+  TELEGRAM_OPS_REMINDERS_DUE_PATH,
+  TELEGRAM_OPS_REMINDERS_PATH,
+  TELEGRAM_OPS_SUBSCRIBERS_PATH,
+  TELEGRAM_OPS_SUBSCRIBER_STATUSES,
+  TELEGRAM_OPS_WEBHOOK_PATH,
+  telegramOpsEventActionPath,
+  telegramOpsEventPath,
+  telegramOpsReminderDeliveredPath,
+  telegramOpsSubscriberPath
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunizao/contracts",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "Shared TypeScript contracts for buxx.me services and clients.",
   "type": "module",
   "sideEffects": false,
@@ -38,6 +38,11 @@
       "import": "./dist/admin.js",
       "default": "./dist/admin.js"
     },
+    "./comments": {
+      "types": "./dist/comments.d.ts",
+      "import": "./dist/comments.js",
+      "default": "./dist/comments.js"
+    },
     "./content": {
       "types": "./dist/content.d.ts",
       "import": "./dist/content.js",
@@ -48,6 +53,11 @@
       "import": "./dist/listening.js",
       "default": "./dist/listening.js"
     },
+    "./messages": {
+      "types": "./dist/messages.d.ts",
+      "import": "./dist/messages.js",
+      "default": "./dist/messages.js"
+    },
     "./mood": {
       "types": "./dist/mood.d.ts",
       "import": "./dist/mood.js",