@bunizao/contracts 0.4.0 → 0.6.1

package/dist/admin.d.ts

@@ -1,3 +1,4 @@
+import type { ClientFingerprint, CommentStatus, Interaction } from './comments';
 import type { DeliveryMode, NotifyAuditEventType, NotifyChannel, SubscriberRecord, SubscriberStatus } from './notify';
 export interface SubscriberChannelCount {
     total: number;
@@ -85,3 +86,459 @@ export interface BroadcastSendResult {
     failedCount: number;
     status: BroadcastRecord['status'];
 }
+/** The queue's status filter; the same four values as `CommentStatus`, in
+    the order the portal tabs show them. */
+export type AdminCommentStatus = CommentStatus;
+/** One row of the comment queue. The public `Comment` never carries the
+    writer's standing or the moderation verdict; this does, and adds the
+    actor block that says where the row came from. */
+export interface AdminCommentRecord {
+    id: string;
+    postId: string;
+    parentId: string | null;
+    author: string;
+    /** True when the writer had a confirmed identity at the time of writing. */
+    verified: boolean;
+    body: string;
+    status: AdminCommentStatus;
+    moderationAction: string | null;
+    moderationReason: string | null;
+    moderationNote: string | null;
+    moderationModel: string | null;
+    country: string | null;
+    createdAt: string;
+    editedAt: string | null;
+    /** Filled from the post registry; null when it could not say. */
+    postTitle: string | null;
+    postSlug: string | null;
+    actor: AdminCommentActor;
+}
+/** One page of the moderation queue. */
+export interface AdminCommentListResult {
+    comments: AdminCommentRecord[];
+    /** Rows matching the filter, ignoring the page window. */
+    total: number;
+    /** `offset + comments.length`, or null on the last page. */
+    nextOffset: number | null;
+}
+/** What a ban can hold onto. Values are hashes (or the ASN as text) for
+    every kind but the two domain kinds, which are stored raw -- a domain is
+    not personal data. `client_fp` matches either the exact or the stable
+    device hash. */
+export type AdminBanKeyType = 'email' | 'session' | 'ip' | 'ip24' | 'fp' | 'asn' | 'client_fp' | 'domain' | 'email_domain';
+export type AdminBanSource = 'portal' | 'telegram' | 'script';
+/** One key a queue row, a reaction, or a source profile can be pivoted on:
+    `GET /admin/comments?key=&value=`, `GET /admin/reactions?key=&value=`
+    and `GET /admin/sources/:type/:value` all take one of these. Every ban
+    key type is also a source key type; the rest are cluster keys that can be
+    looked at but not banned. */
+export type AdminSourceKeyType = AdminBanKeyType | 'client_fp_stable' | 'storage_id' | 'body_hash';
+/** The `signals` blob on a row: the request's network and header set,
+    serialised once at insert and nulled by the 90-day sweep. */
+export interface ActorDetail {
+    colo: string | null;
+    region: string | null;
+    timezone: string | null;
+    httpProtocol: string | null;
+    tlsVersion: string | null;
+    tlsCipher: string | null;
+    tlsCiphersSha1: string | null;
+    tlsExtensionsSha1: string | null;
+    tlsHelloLength: number | null;
+    rttMs: number | null;
+    /** From the static hosting-ASN list; a vpn hint, not a bot hint. */
+    asnKind: 'hosting' | 'other' | null;
+    acceptLanguage: string | null;
+    acceptEncoding: string | null;
+    chUa: string | null;
+    chPlatform: string | null;
+    chMobile: string | null;
+    /** `sec-fetch-dest/mode/site` joined with `/`. */
+    secFetch: string | null;
+    priority: string | null;
+    referer: string | null;
+    origin: string | null;
+    /** `cf-worker` header present: the request came out of another Worker. */
+    viaWorker: boolean;
+}
+/** The `client` blob on a row: the fingerprint components and interaction
+    aggregates exactly as the browser sent them (bounded), plus the hint
+    lists the server derived from them and the headers together. */
+export interface ActorClient {
+    components: ClientFingerprint | null;
+    interaction: Interaction | null;
+    /** Contradictions that count into the row's `botHints` total. */
+    botHints: string[];
+    /** Contradictions shown and not counted: what a VPN looks like. */
+    vpnHints: string[];
+}
+/** Behavioural integers, kept past the sweep. Comments carry dwell, the
+    Turnstile age, the link count and the MX result; reactions carry the
+    Turnstile age and which door the heart came through. */
+export interface AdminActorBehaviour {
+    dwellMs?: number | null;
+    turnstileAgeMs?: number | null;
+    linkCount?: number | null;
+    emailMx?: boolean | null;
+    emailGravatar?: boolean | null;
+    auth?: 'turnstile' | 'pass' | 'verified' | null;
+}
+/** The row's keys, at full length: the portal shortens a hash to its first
+    eight characters for the eye and keeps the whole value for the pivot
+    link. Domains are raw, and `session` is '' when the row predates
+    sessions. */
+export interface AdminActorKeys {
+    session: string;
+    ip: string | null;
+    ip24: string | null;
+    fp: string | null;
+    email: string | null;
+    clientFp: string | null;
+    clientFpStable: string | null;
+    storageId: string | null;
+    emailDomain: string | null;
+    bodyHash: string | null;
+    linkDomains: string[];
+}
+export type AdminClusterKey = 'session' | 'ip' | 'ip24' | 'fp' | 'email' | 'clientFp' | 'clientFpStable' | 'storageId' | 'emailDomain' | 'bodyHash';
+export interface AdminClusterCount {
+    comments: number;
+    held: number;
+    reactions: number;
+}
+/** Where a row came from, as far as the write path could tell. Shared by
+    comments and reactions; a reaction's block has no email, no link domains
+    and no body hash. */
+export interface AdminCommentActor {
+    readerId: string | null;
+    /** Plaintext while the row still holds it (verified: with the row;
+        unverified: seven days). */
+    email: string | null;
+    /** Plaintext while inside the 90-day window. */
+    ip: string | null;
+    ua: string | null;
+    browser: string | null;
+    os: string | null;
+    country: string | null;
+    city: string | null;
+    asn: number | null;
+    asOrg: string | null;
+    /** This write minted the anonymous session cookie. */
+    sessionNew: boolean;
+    /** Count of tripped bot hints; the names are in `client.botHints`. */
+    botHints: number;
+    /** The `signals` blob, parsed. Null once the sweep has run. */
+    detail: ActorDetail | null;
+    /** The `client` blob, parsed. Null when the write carried neither
+        fingerprint nor interaction, or once the sweep has run. */
+    client: ActorClient | null;
+    behaviour: AdminActorBehaviour;
+    keys: AdminActorKeys;
+    /** Which of this row's keys are on the ban list right now. */
+    banned: AdminBanKeyType[];
+    /** Other rows sharing each key in the last 90 days, excluding this one. */
+    cluster: Record<AdminClusterKey, AdminClusterCount>;
+    /** Same, per link domain on this row. */
+    domainCluster: Array<{
+        domain: string;
+        comments: number;
+        held: number;
+        banned: boolean;
+    }>;
+    /** Published comments at this email domain in the last 90 days.
+        Missing or null means the broad domain ban cannot be evaluated. */
+    emailDomainPublishedComments?: number | null;
+}
+/** One reaction row as the reactions list shows it. */
+export interface AdminReactionRecord {
+    /** ULID, like a comment id. */
+    id: string;
+    targetType: 'post' | 'comment';
+    targetId: string;
+    postId: string | null;
+    postTitle: string | null;
+    postSlug: string | null;
+    emoji: string;
+    createdAt: string;
+    actor: AdminCommentActor;
+}
+export interface AdminReactionListResult {
+    reactions: AdminReactionRecord[];
+    total: number;
+    nextOffset: number | null;
+}
+export interface AdminBan {
+    keyType: AdminBanKeyType;
+    keyValue: string;
+    note: string | null;
+    source: AdminBanSource;
+    createdAt: string;
+    expiresAt: string | null;
+    /** Rows in the last 90 days, both tables, matching this key. */
+    hits: number;
+}
+/** `POST /admin/bans`: every key in one write. With `purge`, the source's
+    comments from the last 90 days are soft-deleted and its reaction rows
+    removed, each logged. `revokeReaderId` flips `notify_subscribers.banned`
+    for a verified writer -- the account lever, offered on verified rows. */
+export interface AdminBanInput {
+    keys: Array<{
+        type: AdminBanKeyType;
+        value: string;
+    }>;
+    note?: string;
+    expiresAt?: string | null;
+    purge?: boolean;
+    revokeReaderId?: string | null;
+}
+export interface AdminBanResult {
+    bans: AdminBan[];
+    purged: {
+        comments: number;
+        reactions: number;
+    };
+}
+export interface AdminBanListResult {
+    bans: AdminBan[];
+}
+/** Everything about one key in one response --
+    `GET /admin/sources/:type/:value`. */
+export interface AdminSourceProfile {
+    key: {
+        type: AdminSourceKeyType;
+        value: string;
+    };
+    firstSeenAt: string | null;
+    lastSeenAt: string | null;
+    comments: {
+        total: number;
+        byStatus: Record<AdminCommentStatus, number>;
+        /** Newest 50. */
+        rows: AdminCommentRecord[];
+    };
+    reactions: {
+        total: number;
+        byTarget: Array<{
+            targetType: 'post' | 'comment';
+            targetId: string;
+            postTitle: string | null;
+            count: number;
+        }>;
+        /** Newest 50. */
+        rows: AdminReactionRecord[];
+    };
+    /** Distinct values of every other key this source has used. The spread is
+        the churn: one fingerprint over 40 sessions and 12 IPs is a bot; one
+        session over 3 IPs is a phone that changed networks. */
+    spread: Record<'session' | 'ip' | 'ip24' | 'fp' | 'clientFp' | 'clientFpStable' | 'storageId' | 'email' | 'asn' | 'ua', number>;
+    /** Every bot and vpn hint this source has tripped, with how often. */
+    hints: Array<{
+        hint: string;
+        kind: 'bot' | 'vpn';
+        count: number;
+    }>;
+    /** Two hops over strong keys only (session, email, clientFpStable,
+        storageId): the sessions this source links to, and what those sessions
+        carried. Never `ip24`, `asn` or `ua` as a hop. */
+    linked: {
+        sessions: number;
+        via: Record<'email' | 'clientFpStable' | 'storageId', number>;
+        carried: Record<'ip24' | 'clientFpStable' | 'email' | 'storageId', number>;
+        comments: number;
+        held: number;
+        reactions: number;
+    };
+    /** Writes per hour over the source's last 7 days. */
+    hourly: Array<{
+        hour: string;
+        comments: number;
+        reactions: number;
+    }>;
+    behaviour: {
+        dwellMsMedian: number | null;
+        turnstileAgeMsMedian: number | null;
+        /** 0..1 */
+        newSessionShare: number;
+        authMix: Record<'turnstile' | 'pass' | 'verified', number>;
+    };
+    bans: AdminBan[];
+}
+/** One grouped row in an insights table. `held` and `heldRate` (0..1) are
+    null on the reaction tables, where nothing is held. */
+export interface AdminInsightRow {
+    count: number;
+    held: number | null;
+    heldRate: number | null;
+    /** Distinct sessions behind the count. */
+    sessions: number;
+}
+export type AdminCommentInsightsWindow = '7d' | '30d' | '90d';
+export type AdminReactionInsightsWindow = '48h' | '7d';
+/** `GET /admin/comments/insights?window=`. Every table carries a held rate,
+    because a source is only interesting relative to how the automatic pass
+    treats it. NULL groups show as their own row, never dropped. */
+export interface AdminCommentInsights {
+    window: AdminCommentInsightsWindow;
+    since: string;
+    networks: Array<AdminInsightRow & {
+        asn: number | null;
+        asOrg: string | null;
+    }>;
+    countries: Array<AdminInsightRow & {
+        country: string | null;
+    }>;
+    subnets: Array<AdminInsightRow & {
+        ip24: string | null;
+        sampleIp: string | null;
+    }>;
+    browsers: Array<AdminInsightRow & {
+        browser: string | null;
+        os: string | null;
+    }>;
+    devices: Array<AdminInsightRow & {
+        clientFp: string | null;
+        renderer: string | null;
+        screen: string | null;
+        platform: string | null;
+        subnets: number;
+    }>;
+    botHints: Array<{
+        hint: string;
+        count: number;
+        held: number;
+        heldRate: number;
+    }>;
+    vpnHints: Array<{
+        hint: string;
+        count: number;
+        held: number;
+        heldRate: number;
+    }>;
+    linkDomains: Array<AdminInsightRow & {
+        domain: string;
+        banned: boolean;
+    }>;
+    duplicates: Array<AdminInsightRow & {
+        bodyHash: string;
+        sample: string;
+    }>;
+    emailDomains: Array<AdminInsightRow & {
+        domain: string;
+        mxShare: number | null;
+        banned: boolean;
+    }>;
+    tlsStacks: Array<{
+        browser: string | null;
+        ciphersSha1: string | null;
+        count: number;
+        held: number;
+        heldRate: number;
+    }>;
+    typing: Array<{
+        bucket: string;
+        count: number;
+        held: number;
+        heldRate: number;
+    }>;
+    dailyByStatus: Array<{
+        day: string;
+        published: number;
+        held: number;
+        rejected: number;
+        deleted: number;
+    }>;
+    dwell: Array<{
+        bucket: string;
+        count: number;
+        held: number;
+        heldRate: number;
+    }>;
+    sessionAge: Array<{
+        day: string;
+        writes: number;
+        newShare: number;
+    }>;
+    email: Array<{
+        kind: 'without' | 'verified' | 'unverified' | 'disposable';
+        count: number;
+        held: number;
+        heldRate: number;
+    }>;
+    overturns: Array<{
+        week: string;
+        falsePositives: number;
+        falseNegatives: number;
+    }>;
+    banHits: Array<{
+        keyType: AdminBanKeyType;
+        keyValue: string;
+        note: string | null;
+        hits: number;
+    }>;
+}
+/** `GET /admin/reactions/insights?window=`. */
+export interface AdminReactionInsights {
+    window: AdminReactionInsightsWindow;
+    since: string;
+    hourly: Array<{
+        hour: string;
+        reactions: number;
+        sessions: number;
+        subnets: number;
+    }>;
+    authMix: Array<{
+        day: string;
+        turnstile: number;
+        pass: number;
+        verified: number;
+    }>;
+    targets: Array<{
+        targetType: 'post' | 'comment';
+        targetId: string;
+        postTitle: string | null;
+        reactions: number;
+        subnets: number;
+        fps: number;
+    }>;
+    networks: Array<AdminInsightRow & {
+        asn: number | null;
+        asOrg: string | null;
+    }>;
+    countries: Array<AdminInsightRow & {
+        country: string | null;
+    }>;
+    subnets: Array<AdminInsightRow & {
+        ip24: string | null;
+        sampleIp: string | null;
+    }>;
+    browsers: Array<AdminInsightRow & {
+        browser: string | null;
+        os: string | null;
+    }>;
+    devices: Array<AdminInsightRow & {
+        clientFp: string | null;
+        renderer: string | null;
+        screen: string | null;
+        platform: string | null;
+        subnets: number;
+    }>;
+    botHints: Array<{
+        hint: string;
+        count: number;
+    }>;
+    tlsStacks: Array<{
+        browser: string | null;
+        ciphersSha1: string | null;
+        count: number;
+    }>;
+    sessionAge: Array<{
+        day: string;
+        writes: number;
+        newShare: number;
+    }>;
+    timeToTap: Array<{
+        bucket: string;
+        count: number;
+        sessions: number;
+    }>;
+}

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'];
@@ -126,6 +145,131 @@ export type ReactionTargetKey = string;
 export interface ReactionBatchResult {
     reactions: Record<ReactionTargetKey, ReactionSummary[]>;
 }
+/** What the browser says about itself, collected by the lazily loaded
+    `fingerprint.ts` module on the first interaction with a compose box or a
+    reaction bar and sent as `clientFp` on both write bodies. Every field is
+    optional; the server treats a missing or malformed object as no object
+    and never refuses the write for it -- these are evidence, not a door.
+    Bounds the server enforces: strings at most 128 characters, `fonts` at
+    most 32 entries, every number a bounded integer (`timezoneOffset` is the
+    one that may be negative), the whole object under 4 KiB. The server
+    hashes the canonical component JSON itself; the client never names its
+    own hash. See plans/comment-actor-identity.md "Client fingerprint". */
+export interface ClientFingerprint {
+    navigator?: {
+        platform?: string;
+        languages?: string[];
+        hardwareConcurrency?: number;
+        deviceMemory?: number;
+        maxTouchPoints?: number;
+        webdriver?: boolean;
+        pdfViewerEnabled?: boolean;
+        /** `navigator.plugins.length`. */
+        plugins?: number;
+        cookieEnabled?: boolean;
+        /** `userAgentData.brands` as `"Chromium 128"` strings. */
+        uaBrands?: string[];
+        uaPlatform?: string;
+        uaMobile?: boolean;
+        uaPlatformVersion?: string;
+        uaArchitecture?: string;
+        uaModel?: string;
+    };
+    screen?: {
+        width?: number;
+        height?: number;
+        availWidth?: number;
+        availHeight?: number;
+        colorDepth?: number;
+        /** `devicePixelRatio` in percent (200 = 2x), so it stays an integer. */
+        dprPct?: number;
+        outerWidth?: number;
+        outerHeight?: number;
+    };
+    /** `Intl.DateTimeFormat().resolvedOptions().timeZone`. */
+    timezone?: string;
+    /** `Date#getTimezoneOffset()`, minutes, negative east of UTC. */
+    timezoneOffset?: number;
+    /** SHA-256 hex of an offscreen canvas `toDataURL()`. */
+    canvas?: string;
+    webgl?: {
+        vendor?: string;
+        renderer?: string;
+        maxTextureSize?: number;
+        maxViewport?: number;
+    };
+    /** Sum of `OfflineAudioContext` samples, formatted to a fixed precision. */
+    audio?: string;
+    /** Families detected by a width probe, in the probe list's order. */
+    fonts?: string[];
+    media?: {
+        colorScheme?: string;
+        reducedMotion?: string;
+        pointer?: string;
+        hover?: string;
+        colorGamut?: string;
+        dynamicRange?: string;
+    };
+    presence?: {
+        chrome?: boolean;
+        /** `Notification.permission`, or absent when the API is missing. */
+        notification?: string;
+        performanceMemory?: boolean;
+        indexedDb?: boolean;
+        localStorage?: boolean;
+    };
+}
+/** How the form was filled, as aggregates only: counts and one spread
+    figure, never the key sequence or the intervals themselves. Collected by
+    the same lazy module from listeners on the compose box and the reaction
+    bar, sent as `interaction` beside `clientFp`. Same bounds and the same
+    never-a-gate rule as `ClientFingerprint`. Comment-only and reaction-only
+    fields are marked; the rest apply to both. */
+export interface Interaction {
+    /** `performance.now()` at first compose focus (comments). */
+    loadToFocusMs?: number;
+    /** `performance.now()` at first heart tap (reactions). */
+    loadToTapMs?: number;
+    /** First focus to submit (comments). */
+    composeMs?: number;
+    /** Counts on the body field (comments). */
+    keyEvents?: number;
+    inputEvents?: number;
+    pasteEvents?: number;
+    /** Coefficient of variation of inter-key intervals, per mille (comments). */
+    keyIntervalCv?: number;
+    /** The submit or tap's `pointerType`. */
+    pointerType?: string;
+    /** `pointermove` count on the page before the submit or tap. */
+    pointerMoves?: number;
+    /** Distance from the button's centre, CSS px, of the submit click or tap. */
+    clickOffset?: number;
+    scrollEvents?: number;
+    /** Max `scrollY / (docHeight - innerHeight)` as a percentage. */
+    scrollDepth?: number;
+    /** `visibilitychange` to hidden before the submit or tap. */
+    hiddenCount?: number;
+    /** `document.hasFocus()` at submit. */
+    hasFocus?: boolean;
+    historyLength?: number;
+    /** Client-side rejections before the successful submit (comments). */
+    validationErrors?: number;
+    /** Widget render to token callback. */
+    turnstileSolveMs?: number;
+    /** Whether `before-interactive-callback` fired. */
+    turnstileInteractive?: boolean;
+    /** Reaction taps on this page so far (reactions). */
+    tapsThisPage?: number;
+}
+/** The optional client evidence both write bodies may carry. `storageId` is
+    a random 32-hex value the lazy module reads or creates in IndexedDB; the
+    server stores only its HMAC and never uses it to set, restore or extend
+    a cookie. */
+export interface ClientEvidence {
+    clientFp?: ClientFingerprint;
+    interaction?: Interaction;
+    storageId?: string;
+}
 export interface ReactionToggleInput {
     targetType: ReactionTargetType;
     targetId: string;
@@ -136,9 +280,20 @@ export interface ReactionToggleInput {
         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;
+    /** Client evidence, optional and never a gate -- see `ClientEvidence`. */
+    clientFp?: ClientFingerprint;
+    interaction?: Interaction;
+    storageId?: string;
 }
 export interface ReactionToggleResult {
     reaction: ReactionSummary;
+    /** Epoch ms until which this browser holds a reader pass: the server has
+        set a session-bound cookie that stands in for `turnstileToken` on
+        later reactions. A client that sees this can stop minting tokens until
+        then and send `turnstileToken: ''`; a `400 turnstile_failed` on such a
+        request means the pass is gone and a token is needed again. Absent
+        only when the server has no session secret to sign one. */
+    passUntil?: number;
 }
 /** Public author view on a comment row. Never includes email or email_hash. */
 export interface CommentAuthor {
@@ -154,8 +309,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 +348,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. */
@@ -209,6 +371,10 @@ export interface CommentCreateInput {
         once the address is verified. */
     notifyReplies?: boolean;
     locale?: CommentLocale;
+    /** Client evidence, optional and never a gate -- see `ClientEvidence`. */
+    clientFp?: ClientFingerprint;
+    interaction?: Interaction;
+    storageId?: string;
 }
 export declare const COMMENT_CREATE_OUTCOMES: readonly ['published', 'held'];
 export type CommentCreateOutcome = (typeof COMMENT_CREATE_OUTCOMES)[number];

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,13 @@ 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:",
+  ban: "comment:ban:"
+};
 var NOTIFY_GATE_PATH = "/admin/notify-gate";
 var NOTIFY_GATE_RELEASE_PATH = `${NOTIFY_GATE_PATH}/release`;
 var NOTIFY_GATE_STATES = ["open", "held"];
@@ -202,11 +218,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 +249,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 +293,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 +303,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,24 @@
 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:';
+    /** Bans the comment's pre-ticked source keys, no purge -- see
+        plans/comment-actor-identity.md "Actions by source". */
+    readonly ban: 'comment:ban:';
+};
 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,12 @@
 // 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:",
+  ban: "comment:ban:"
+};
 var NOTIFY_GATE_PATH = "/admin/notify-gate";
 var NOTIFY_GATE_RELEASE_PATH = `${NOTIFY_GATE_PATH}/release`;
 var NOTIFY_GATE_STATES = ["open", "held"];
@@ -61,6 +68,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.6.1",
   "description": "Shared TypeScript contracts for buxx.me services and clients.",
   "type": "module",
   "sideEffects": false,