@bunizao/contracts 0.4.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.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",
@@ -95,6 +103,7 @@ 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"];
@@ -141,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"];
@@ -202,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,
@@ -230,6 +248,7 @@ export {
   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,
@@ -273,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,
@@ -282,6 +302,7 @@ export {
   TELEGRAM_OPS_WEBHOOK_PATH,
   TELEGRAM_WEBHOOK_PATH,
   acceptsComments,
+  commentAnchorToken,
   commentPolicyFromTags,
   parsePostLocaleTag,
   telegramOpsEventActionPath,

package/dist/messages.d.ts

@@ -36,12 +36,13 @@ export interface OwnerMessageCreateInput {
     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.
+     * 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;
+    email: string;
     turnstileToken: string;
     /** Minted by the form on load; proves the submit was not instant. */
     dwellToken: string;

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/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.4.0",
+  "version": "0.5.0",
   "description": "Shared TypeScript contracts for buxx.me services and clients.",
   "type": "module",
   "sideEffects": false,