@bunizao/contracts 0.3.0 → 0.5.0

package/dist/comments.d.ts

@@ -21,6 +21,25 @@ 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];
+/** Where a comment was written. `blog` rows key on Ghost post ids; `mood`
+    rows key on the Telegram channel message id and are bridged into the
+    channel's discussion group by the ops bot — plans/mood-comments-bridge.md. */
+export declare const COMMENT_SURFACES: readonly ['blog', 'mood'];
+export type CommentSurface = (typeof COMMENT_SURFACES)[number];
+/** Length of the anchor token derived from a comment id. */
+export declare const COMMENT_ANCHOR_TOKEN_LENGTH = 12;
+/**
+ * Stable, unguessable-enough anchor for a comment: the first 12 hex chars of
+ * sha256(commentId). It rides in the bridged Telegram message's link
+ * (`/mood/<postId>#c-<token>`), in the owner card's View URL, and as the
+ * `id="c-<token>"` of the rendered row. The read path matches bridged
+ * messages back to their rows by this string, so it must be computed the
+ * same way everywhere — hence one helper here. Async because it uses Web
+ * Crypto, which is what Workers, Node >= 20, and browsers share.
+ */
+export declare function commentAnchorToken(commentId: string): Promise<string>;
+/** Matches `#c-<token>` anywhere in a URL or text; group 1 is the token. */
+export declare const COMMENT_ANCHOR_PATTERN: RegExp;
 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'];
@@ -154,8 +173,12 @@ export interface CommentAuthor {
 }
 export interface Comment {
     id: string;
-    /** Ghost's post.id, stable across slug renames. */
+    surface: CommentSurface;
+    /** `blog`: Ghost's post.id, stable across slug renames. `mood`: the
+        Telegram channel message id, the same value `/mood/[id]` routes on. */
     postId: string;
+    /** `commentAnchorToken(id)`, precomputed so clients never hash. */
+    anchorToken: string;
     /** Always a root comment id, or null. Threading is one level deep. */
     parentId: string | null;
     author: CommentAuthor;
@@ -189,6 +212,9 @@ export interface CommentListResult {
     total: number;
 }
 export interface CommentCreateInput {
+    /** Defaults to `blog`. `mood` requires the post to have a linked
+        discussion thread (`MoodContentDocument.discussionLinked`). */
+    surface?: CommentSurface;
     postId: string;
     body: string;
     /** Root comment id this replies to. Omitted or null for a root comment. */

package/dist/comments.js

@@ -3,6 +3,14 @@ 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 COMMENT_SURFACES = ["blog", "mood"];
+var COMMENT_ANCHOR_TOKEN_LENGTH = 12;
+async function commentAnchorToken(commentId) {
+  const bytes = new TextEncoder().encode(commentId);
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("").slice(0, COMMENT_ANCHOR_TOKEN_LENGTH);
+}
+var COMMENT_ANCHOR_PATTERN = /#c-([0-9a-f]{12})\b/;
 var MODERATION_ACTIONS = ["publish", "hold", "reject", "unsure"];
 var MODERATION_REASONS = [
   "ok",
@@ -54,10 +62,13 @@ function commentPolicyFromTags(tags, base = DEFAULT_COMMENT_POLICY) {
 var acceptsComments = (policy) => policy.mode === "open";
 export {
   COMMENTS_MODES,
+  COMMENT_ANCHOR_PATTERN,
+  COMMENT_ANCHOR_TOKEN_LENGTH,
   COMMENT_CREATE_OUTCOMES,
   COMMENT_LOCALES,
   COMMENT_POLICY_TAGS,
   COMMENT_STATUSES,
+  COMMENT_SURFACES,
   DEFAULT_COMMENT_POLICY,
   DEFAULT_REACTION_EMOJI,
   MODERATION_ACTIONS,
@@ -68,5 +79,6 @@ export {
   READER_PROVIDERS,
   READER_VERIFY_OUTCOMES,
   acceptsComments,
+  commentAnchorToken,
   commentPolicyFromTags
 };

package/dist/content.d.ts

@@ -79,6 +79,17 @@ export interface MoodContentDocument extends ContentDocument {
     source: 'mood';
     groupIds?: string[];
     channel?: ContentChannelSummary;
+    /** True when the post's copy in the Telegram discussion group is known
+        (`mood_posts.discussion_message_id`) and mood comments are enabled, so
+        the compose box can post into the thread. False or absent: the page
+        keeps the "Leave a comment on Telegram" link instead. */
+    discussionLinked?: boolean;
+    /** True once the read path has verified, from live traffic, that the
+        embed's comment ids are the group's message ids, which is what a
+        web reply to a Telegram-origin comment needs to thread correctly.
+        Gates reply-to on `telegram` items only; replies to `web` items are
+        always allowed. */
+    discussionRepliesEnabled?: boolean;
 }
 export interface PostContentDocument extends ContentDocument {
     source: 'post';

package/dist/index.d.ts

@@ -3,6 +3,7 @@ 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

@@ -16,6 +16,14 @@ 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 COMMENT_SURFACES = ["blog", "mood"];
+var COMMENT_ANCHOR_TOKEN_LENGTH = 12;
+async function commentAnchorToken(commentId) {
+  const bytes = new TextEncoder().encode(commentId);
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("").slice(0, COMMENT_ANCHOR_TOKEN_LENGTH);
+}
+var COMMENT_ANCHOR_PATTERN = /#c-([0-9a-f]{12})\b/;
 var MODERATION_ACTIONS = ["publish", "hold", "reject", "unsure"];
 var MODERATION_REASONS = [
   "ok",
@@ -85,9 +93,17 @@ 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"];
+var MOOD_COMMENT_ORIGINS = ["telegram", "web"];
 
 // src/notify.ts
 var NOTIFY_CHANNELS = ["mood", "blog", "privacy", "announcement"];
@@ -109,6 +125,7 @@ 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";
@@ -133,6 +150,12 @@ var LEGACY_HEALTH_PATH = "/v2/health";
 
 // src/telegram-ops.ts
 var TELEGRAM_OPS_WEBHOOK_PATH = "/webhooks/telegram-ops";
+var TELEGRAM_OPS_COMMENT_CALLBACK_PREFIXES = {
+  reply: "comment:reply:",
+  approve: "comment:approve:",
+  hide: "comment:hide:",
+  delete: "comment:delete:"
+};
 var NOTIFY_GATE_PATH = "/admin/notify-gate";
 var NOTIFY_GATE_RELEASE_PATH = `${NOTIFY_GATE_PATH}/release`;
 var NOTIFY_GATE_STATES = ["open", "held"];
@@ -194,11 +217,14 @@ export {
   BLOG_ANALYTICS_SUMMARY_ENDPOINT,
   COMMENTS_MODES,
   COMMENTS_PATH,
+  COMMENT_ANCHOR_PATTERN,
+  COMMENT_ANCHOR_TOKEN_LENGTH,
   COMMENT_CREATE_OUTCOMES,
   COMMENT_LOCALES,
   COMMENT_PATH_PREFIX,
   COMMENT_POLICY_TAGS,
   COMMENT_STATUSES,
+  COMMENT_SURFACES,
   CONTENT_DOCUMENT_SOURCES,
   DEFAULT_COMMENT_POLICY,
   DEFAULT_REACTION_EMOJI,
@@ -212,11 +238,17 @@ export {
   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_COMMENT_ORIGINS,
   MOOD_IMAGE_PROXY_BASE_PATH,
   MOOD_LIVE_COUNTS_PATH,
   MOOD_LIVE_FEED_PATH,
@@ -235,6 +267,7 @@ export {
   NOTIFY_GATE_PATH,
   NOTIFY_GATE_RELEASE_PATH,
   NOTIFY_GATE_STATES,
+  OWNER_MESSAGES_PATH,
   PING_PATH,
   REACTIONS_PATH,
   REACTIONS_TOGGLE_PATH,
@@ -259,6 +292,7 @@ export {
   TELEGRAM_OPS_BROADCAST_PREVIEW_PATH,
   TELEGRAM_OPS_BROADCAST_SEND_PATH,
   TELEGRAM_OPS_BROADCAST_STATUSES,
+  TELEGRAM_OPS_COMMENT_CALLBACK_PREFIXES,
   TELEGRAM_OPS_EVENTS_PATH,
   TELEGRAM_OPS_OVERVIEW_PATH,
   TELEGRAM_OPS_REMINDERS_DUE_PATH,
@@ -268,6 +302,7 @@ export {
   TELEGRAM_OPS_WEBHOOK_PATH,
   TELEGRAM_WEBHOOK_PATH,
   acceptsComments,
+  commentAnchorToken,
   commentPolicyFromTags,
   parsePostLocaleTag,
   telegramOpsEventActionPath,

package/dist/messages.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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;
+    /**
+     * Required. The comment box channels rather than blocks, because a comment
+     * that nobody can answer is still worth publishing; a private message that
+     * nobody can answer is a dead letter. Supplying one triggers the shared
+     * lazy-verification mail, and only a verified address can ever receive the
+     * owner's reply — so this is necessary for a reply, not sufficient.
+     */
+    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.d.ts

@@ -188,13 +188,38 @@ export interface MoodLiveCount {
 export interface MoodLiveCountsResponse {
     counts: Record<string, MoodLiveCount>;
 }
+/**
+ * The parent a comment replies to, read from the t.me reply block.
+ * `id` is the parent comment id; `text` is a plain-text preview, not HTML.
+ */
+export interface MoodCommentReplyTo {
+    id: string;
+    author: string;
+    text: string;
+}
+/** Where a thread item came from. `telegram`: a group member wrote it in
+    the discussion thread. `web`: written on /mood/[id]; the group holds the
+    ops bot's bridged copy, and the read path re-attributes that copy to the
+    reader — plans/mood-comments-bridge.md "Read path: scrape plus overlay". */
+export declare const MOOD_COMMENT_ORIGINS: readonly ['telegram', 'web'];
+export type MoodCommentOrigin = (typeof MOOD_COMMENT_ORIGINS)[number];
 export interface MoodComment {
+    /** Discussion-group message id as the t.me embed reports it. */
     id: string;
     author: string;
     authorAvatar?: string;
     datetime: string;
     content: string;
     reactions: MoodReaction[];
+    replyTo?: MoodCommentReplyTo;
+    /** Omitted means `telegram`. */
+    origin?: MoodCommentOrigin;
+    /** The site comment row behind a `web` item (`Comment.id`). Lets the
+        browser mark rows it wrote and offer edit/delete through /v2/comments. */
+    commentId?: string;
+    /** `commentAnchorToken(commentId)`; the row renders as `id="c-<token>"`
+        so the bridged Telegram link and the owner card land on it. */
+    anchorToken?: string;
 }
 export interface MoodCommentsPage {
     comments: MoodComment[];

package/dist/mood.js

@@ -1,7 +1,9 @@
 // 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"];
+var MOOD_COMMENT_ORIGINS = ["telegram", "web"];
 export {
   MOOD_AI_MODELS,
+  MOOD_COMMENT_ORIGINS,
   MOOD_SENTIMENT_LABELS
 };

package/dist/routes.d.ts

@@ -14,6 +14,7 @@ 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';

package/dist/routes.js

@@ -15,6 +15,7 @@ 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";
@@ -61,6 +62,7 @@ export {
   MOOD_SEARCH_PATH,
   MUSICKIT_TOKEN_PATH,
   NOTIFY_BASE_PATH,
+  OWNER_MESSAGES_PATH,
   PING_PATH,
   REACTIONS_PATH,
   REACTIONS_TOGGLE_PATH,

package/dist/telegram-ops.d.ts

@@ -1,6 +1,21 @@
 import type { AdminSubscriberPatch, BroadcastInput, BroadcastPreviewResult, BroadcastRecord, BroadcastSendResult } from './admin';
 import type { DeliveryMode, NotifyChannel, SubscriberRecord, SubscriberStatus } from './notify';
 export declare const TELEGRAM_OPS_WEBHOOK_PATH: '/webhooks/telegram-ops';
+/**
+ * Callback data and message tokens the ops bot uses for comment cards. The
+ * comment id no longer lives in an expiring pending-action token: every
+ * card and every reply prompt carries `#c-<anchorToken>` in its View URL
+ * and as a text link, so replying to the card resolves the comment for as
+ * long as the card exists — plans/mood-comments-bridge.md "Owner reply
+ * flow". Group messages (the discussion group's automatic forwards and
+ * replies to the bot's bridged comments) are expected on this webhook too.
+ */
+export declare const TELEGRAM_OPS_COMMENT_CALLBACK_PREFIXES: {
+    readonly reply: 'comment:reply:';
+    readonly approve: 'comment:approve:';
+    readonly hide: 'comment:hide:';
+    readonly delete: 'comment:delete:';
+};
 export declare const NOTIFY_GATE_PATH: '/admin/notify-gate';
 export declare const NOTIFY_GATE_RELEASE_PATH: "/admin/notify-gate/release";
 export declare const NOTIFY_GATE_STATES: readonly ['open', 'held'];

package/dist/telegram-ops.js

@@ -1,5 +1,11 @@
 // src/telegram-ops.ts
 var TELEGRAM_OPS_WEBHOOK_PATH = "/webhooks/telegram-ops";
+var TELEGRAM_OPS_COMMENT_CALLBACK_PREFIXES = {
+  reply: "comment:reply:",
+  approve: "comment:approve:",
+  hide: "comment:hide:",
+  delete: "comment:delete:"
+};
 var NOTIFY_GATE_PATH = "/admin/notify-gate";
 var NOTIFY_GATE_RELEASE_PATH = `${NOTIFY_GATE_PATH}/release`;
 var NOTIFY_GATE_STATES = ["open", "held"];
@@ -61,6 +67,7 @@ export {
   TELEGRAM_OPS_BROADCAST_PREVIEW_PATH,
   TELEGRAM_OPS_BROADCAST_SEND_PATH,
   TELEGRAM_OPS_BROADCAST_STATUSES,
+  TELEGRAM_OPS_COMMENT_CALLBACK_PREFIXES,
   TELEGRAM_OPS_EVENTS_PATH,
   TELEGRAM_OPS_OVERVIEW_PATH,
   TELEGRAM_OPS_REMINDERS_DUE_PATH,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunizao/contracts",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Shared TypeScript contracts for buxx.me services and clients.",
   "type": "module",
   "sideEffects": false,
@@ -53,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",