@bunizao/contracts 0.10.0 → 0.11.0

package/dist/admin.d.ts

@@ -1,4 +1,5 @@
-import type { ClientFingerprint, CommentAuthAtWrite, CommentClaimMethod, CommentStatus, Interaction } from './comments';
+import type { ClientFingerprint, CommentAuthAtWrite, CommentClaimMethod, CommentsMode, CommentStatus, CommentSurface, Interaction } from './comments';
+import type { MessageLocale, MessageState } from './messages';
 import type { DeliveryMode, NotifyAuditEventType, NotifyChannel, SubscriberRecord, SubscriberStatus } from './notify';
 export interface SubscriberChannelCount {
     total: number;
@@ -108,10 +109,30 @@ export interface AdminCommentRecord {
     country: string | null;
     createdAt: string;
     editedAt: string | null;
-    /** Filled from the post registry; null when it could not say. */
+    /** Filled from the post registry; null when it could not say. A mood
+        post has no slug: `postSlug` is always null for one, and `postPath`
+        carries the link. */
     postTitle: string | null;
     postSlug: string | null;
     actor: AdminCommentActor;
+    surface?: CommentSurface;
+    /** When the latest verdict, automatic or the owner's, was written. */
+    moderatedAt?: string | null;
+    updatedAt?: string;
+    /** A deleted row the owner can still restore: the last instant it can.
+        Null for every other row. */
+    restorableUntil?: string | null;
+    /** When the owner pinned this root to the top of its post. A pin on a
+        row that is no longer published stays set and shows again with it. */
+    pinnedAt?: string | null;
+    /** When the owner locked replies under this root. */
+    lockedAt?: string | null;
+    /** The post's page on the public site, as a path: `/blog/<slug>` or
+        `/mood/<id>`. Null when the post could not be looked up. */
+    postPath?: string | null;
+    /** The owner wrote it: the public `CommentAuthor.byAuthor` rule, a row
+        written signed in by the reader whose address is the owner's. */
+    byAuthor?: boolean;
 }
 /** One page of the moderation queue. */
 export interface AdminCommentListResult {
@@ -121,6 +142,274 @@ export interface AdminCommentListResult {
     /** `offset + comments.length`, or null on the last page. */
     nextOffset: number | null;
 }
+/** The numbers drawn above the queue. */
+export interface AdminCommentSummary {
+    byStatus: Record<AdminCommentStatus, number>;
+    /** Comments written in the last 24 hours. */
+    today: number;
+    oldestHeldAt: string | null;
+    reasons: Array<{
+        reason: string;
+        count: number;
+    }>;
+    /** `slug` and `path` as on AdminCommentRecord's `postSlug` and
+        `postPath`; `path` is optional only for the portal's demo api. */
+    topPosts: Array<{
+        surface: CommentSurface;
+        postId: string;
+        count: number;
+        title: string | null;
+        slug: string | null;
+        path?: string | null;
+    }>;
+    daily: Array<{
+        date: string;
+        count: number;
+    }>;
+}
+export type AdminCommentQueueSort = 'newest' | 'oldest' | 'risk';
+/** `akismet` alone, `llm` for Akismet plus the second opinion, `none` for
+    rows no model judged. */
+export type AdminCommentModelFilter = 'akismet' | 'llm' | 'none';
+/** The created-at window a queue page was read over. Search and the risk
+    sort always read one (30 days unless asked, 90 at most). */
+export interface AdminCommentQueueWindow {
+    from: string | null;
+    to: string | null;
+    /** True when the window asked for was wider than 90 days and was cut to
+        the 90 before its end; `from` is then where the read started. */
+    clamped?: boolean;
+}
+/** GET /admin/comments. */
+export interface AdminCommentQueueResult extends AdminCommentListResult {
+    summary: AdminCommentSummary;
+    window: AdminCommentQueueWindow | null;
+}
+export type AdminCommentAction = 'approve' | 'hide' | 'reject' | 'delete' | 'restore';
+export declare const ADMIN_COMMENT_REJECT_REASONS: readonly ['spam', 'promotional', 'abuse', 'off_topic', 'personal_info'];
+export type AdminCommentRejectReason = (typeof ADMIN_COMMENT_REJECT_REASONS)[number];
+/** What one act did to one row. `already_*` is a repeat that changed
+    nothing; `not_restorable` is a deleted row past its window or removed in
+    a way restore cannot undo; `not_available` is a row gone, or in a state
+    the act cannot leave. */
+export type AdminCommentActionResult = 'approved' | 'hidden' | 'rejected' | 'deleted' | 'restored' | 'already_approved' | 'already_hidden' | 'already_rejected' | 'already_deleted' | 'not_restorable' | 'not_available';
+/** POST /admin/comments/:id. `reason` is required for `reject`. */
+export interface AdminCommentActionRequest {
+    action: AdminCommentAction;
+    reason?: AdminCommentRejectReason;
+}
+export interface AdminCommentActionResponse {
+    result: AdminCommentActionResult;
+    comment: {
+        id: string;
+        status: AdminCommentStatus;
+    };
+}
+/** POST /admin/comments/bulk: at most 20 ids, applied as one batch. */
+export interface AdminCommentBulkRequest {
+    ids: string[];
+    action: AdminCommentAction;
+    reason?: AdminCommentRejectReason;
+}
+/** One result per id, in the order sent. `status` is the row's status
+    after the call whatever the result, so a `not_available` row says where
+    it actually is; it is null only when no row has that id. */
+export interface AdminCommentBulkResponse {
+    results: Array<{
+        id: string;
+        result: AdminCommentActionResult;
+        status: AdminCommentStatus | null;
+    }>;
+}
+/** POST /admin/comments/:id/reply. */
+export interface AdminCommentReplyRequest {
+    body: string;
+    /** A UUID made once per reply and sent again on every retry: it becomes
+        the reply's id, so a retry answers the first reply instead of posting
+        a second. The same id with another body or comment is a 409
+        `reply_id_collision`. Omitted, every call posts a new reply. */
+    replyId?: string;
+}
+/** `parentId` is the thread root the reply joined. */
+export interface AdminCommentReplyResponse {
+    comment: {
+        id: string;
+        parentId: string;
+        status: AdminCommentStatus;
+    };
+}
+/** The site-wide lockdown: every anonymous comment waits for an email
+    until `until`. */
+export interface AdminCommentLockdown {
+    reason: string;
+    since: string;
+    until: string;
+    by: 'auto' | 'owner';
+}
+/** POST /admin/comments/lockdown: 1 to 10080 minutes, note up to 200
+    characters. */
+export interface AdminCommentLockdownRequest {
+    minutes: number;
+    note?: string;
+}
+/** GET, POST and DELETE /admin/comments/lockdown. */
+export interface AdminCommentLockdownResponse {
+    lockdown: AdminCommentLockdown | null;
+}
+/** A site-wide mode: every post at least this strict. */
+export type AdminCommentSiteMode = Exclude<CommentsMode, 'open'>;
+/** The owner's standing site-wide comment switches, on top of every post's
+    own mode (tags, then the portal's per-post override). Neither expires. */
+export interface AdminCommentSitePolicy {
+    /** Null: each post's own mode decides. Otherwise every post, on every
+        surface, is at least this strict (open < readonly < off); a post that
+        is already stricter stays so. */
+    mode: AdminCommentSiteMode | null;
+    /** When `mode` was last set; null while it is null. */
+    modeSince: string | null;
+    /** Every anonymous comment waits for its writer to confirm an email, as
+        in a lockdown, until switched off. A writer who gives no address is
+        asked for one. Signed-in readers post as usual. */
+    requireEmail: boolean;
+    /** When `requireEmail` was turned on; null while it is off. */
+    requireEmailSince: string | null;
+}
+/** PUT /admin/comments/site-policy: the fields to change, at least one. */
+export interface AdminCommentSitePolicyRequest {
+    mode?: AdminCommentSiteMode | null;
+    requireEmail?: boolean;
+}
+/** GET and PUT /admin/comments/site-policy. */
+export interface AdminCommentSitePolicyResponse {
+    policy: AdminCommentSitePolicy;
+}
+/** PUT and DELETE /admin/comments/:id/pin. `replaced` is the comment the
+    PUT took the post's pin from, or null; always null on DELETE. */
+export interface AdminCommentPinResponse {
+    comment: {
+        id: string;
+        surface: CommentSurface;
+        postId: string;
+        pinnedAt: string | null;
+    };
+    replaced: string | null;
+}
+/** PUT and DELETE /admin/comments/:id/lock. `comment` is the thread root,
+    which is not the id in the path when that was a reply. */
+export interface AdminCommentLockResponse {
+    comment: {
+        id: string;
+        surface: CommentSurface;
+        postId: string;
+        lockedAt: string | null;
+    };
+}
+/** One post's comment mode as the portal shows it: the portal's override
+    beside what the post's tags give (the site default for a mood post). */
+export interface AdminCommentModeState {
+    surface: CommentSurface;
+    postId: string;
+    /** Null when the tags decide. */
+    override: CommentsMode | null;
+    /** Null when the post could not be looked up. */
+    tagMode: CommentsMode | null;
+    /** What readers get: `override`, else `tagMode`. */
+    effectiveMode: CommentsMode | null;
+    /** When the override was last set; null without one. */
+    updatedAt: string | null;
+    title: string | null;
+    /** Blog only; null for a mood post, which has no slug. */
+    slug: string | null;
+    /** The post's page as a path, `/blog/<slug>` or `/mood/<id>`; null when
+        the post could not be looked up. Optional only for the portal's demo
+        api; site-api sends it. */
+    path?: string | null;
+}
+/** GET /admin/comment-modes: every overridden post. */
+export interface AdminCommentModeListResult {
+    modes: AdminCommentModeState[];
+}
+/** PUT /admin/comment-modes/:surface/:postId. */
+export interface AdminCommentModeRequest {
+    mode: CommentsMode;
+}
+/** GET, PUT and DELETE /admin/comment-modes/:surface/:postId. */
+export interface AdminCommentModeResponse {
+    mode: AdminCommentModeState;
+}
+/** One message sent through /message, as the owner's inbox shows it. The
+    body is private: it never leaves the admin routes. */
+export interface AdminOwnerMessage {
+    id: string;
+    state: MessageState;
+    displayName: string;
+    body: string;
+    locale: MessageLocale;
+    /** The reader the address resolves to. It proves who wrote the message
+        only when `authAtWrite` is `verified`. */
+    readerId: string | null;
+    /** `verified` when a signed-in reader's session sent it; `anonymous` when
+        the address was typed. Missing on older responses means unknown. */
+    authAtWrite?: CommentAuthAtWrite;
+    /** Null when the sender left no address. */
+    emailHash: string | null;
+    /** Why the risk stack filed it as spam, and which model said so. */
+    spamNote: string | null;
+    spamModel: string | null;
+    repliedAt: string | null;
+    country: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** GET /admin/messages `state`: one state, or `inbox` for new, read and
+    replied together -- everything not archived or spam. */
+export type AdminOwnerMessageFilter = MessageState | 'inbox';
+/** GET /admin/messages. `counts` covers the whole inbox whatever the
+    filter; `total` is the filtered count. */
+export interface AdminOwnerMessageListResult {
+    messages: AdminOwnerMessage[];
+    counts: Record<MessageState, number>;
+    total: number;
+    nextOffset: number | null;
+}
+/** Whether a reply would reach the sender, and if not, why. */
+export type AdminOwnerMessageReplyability = 'ok' | 'no_address' | 'unverified' | 'suppressed';
+/** GET /admin/messages/:id. `history` is what else the same address sent,
+    newest first; `sender.email` is set only when a reply can reach it. */
+export interface AdminOwnerMessageDetail {
+    message: AdminOwnerMessage;
+    sender: {
+        replyable: AdminOwnerMessageReplyability;
+        email: string | null;
+        readerId: string | null;
+    };
+    history: AdminOwnerMessage[];
+    /** The sender's keys and signals, in the comment writer's shape; `cluster`
+        counts comments, reactions and messages. Absent from a site-api that
+        predates it. */
+    actor?: AdminCommentActor;
+}
+export type AdminOwnerMessageAction = 'read' | 'archive' | 'unarchive' | 'spam' | 'unspam';
+/** POST /admin/messages/:id. */
+export interface AdminOwnerMessageActionRequest {
+    action: AdminOwnerMessageAction;
+}
+/** `changed` is false when the message was already past the act; `message`
+    is then what it is now. */
+export interface AdminOwnerMessageActionResponse {
+    message: AdminOwnerMessage;
+    changed: boolean;
+}
+/** POST /admin/messages/:id/reply: 2 to 4000 characters. */
+export interface AdminOwnerMessageReplyRequest {
+    body: string;
+}
+/** `recipientEmail` is masked. */
+export interface AdminOwnerMessageReplyResponse {
+    message: AdminOwnerMessage;
+    recipientName: string;
+    recipientEmail: string;
+}
 /** 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
@@ -205,6 +494,8 @@ export interface AdminClusterCount {
     comments: number;
     held: number;
     reactions: number;
+    /** Owner messages sharing the key. Absent from a site-api that predates it. */
+    messages?: 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
@@ -293,8 +584,21 @@ export interface AdminBanInput {
     note?: string;
     expiresAt?: string | null;
     purge?: boolean;
+    /** Keys a purge also matches without banning them, such as the writer's
+        device fingerprint. Ignored unless `purge` is set. */
+    sweepKeys?: Array<{
+        type: AdminBanKeyType;
+        value: string;
+    }>;
+    /** The comment the ban was raised from. It is removed in the same
+        restorable operation whatever `purge` says, and its writer is the one
+        signed-in reader a purge may remove published comments from. */
+    removeCommentId?: string | null;
     revokeReaderId?: string | null;
 }
+/** `POST /admin/bans/preview`: the scope `POST /admin/bans` would reach with
+    the same fields. */
+export type AdminBanPreviewInput = Pick<AdminBanInput, 'keys' | 'revokeReaderId' | 'purge' | 'sweepKeys' | 'removeCommentId'>;
 export interface AdminBanResult {
     bans: AdminBan[];
     purged: {
@@ -308,10 +612,21 @@ export interface AdminBanPreview {
     sessions: number;
     comments: Record<AdminCommentStatus | 'total', number>;
     reactions: number;
+    /** What the ban would really remove. The optional fields are absent from
+        a site-api that predates them. */
     purge: {
         comments: number;
         reactions: number;
+        /** Of `comments`, the ones readers can see now. */
+        published?: number;
+        /** Distinct sessions the removed rows came from. */
+        sessions?: number;
+        /** Reader accounts, other than the target comment's own, that lose a row. */
+        otherAccounts?: number;
     };
+    /** Published comments a purge leaves alone because another signed-in
+        reader wrote them. Absent from a site-api that predates the rule. */
+    spared?: number;
     windowDays: 90;
     purgeLimit: number;
     purgeAllowed: boolean;
@@ -346,8 +661,13 @@ export interface AdminBanRestoreResult {
 export interface AdminBanListResult {
     bans: AdminBan[];
 }
+/** A reader a ban revoked -- `GET /admin/readers/revoked`. `emailHash` is
+    the value of an `email` ban key, for finding the key bans that outlive
+    a restore. `updatedAt` is when the row last changed: the revocation,
+    unless something touched the reader since. */
 export interface AdminBannedReader {
     readerId: string;
+    emailHash: string;
     email: string;
     displayName: string | null;
     updatedAt: string;
@@ -355,8 +675,31 @@ export interface AdminBannedReader {
 export interface AdminBannedReaderListResult {
     readers: AdminBannedReader[];
 }
+/** POST /admin/readers/:readerId/restore. */
+export interface AdminReaderRestoreResult {
+    readerId: string;
+    restoredAt: string;
+}
 /** Everything about one key in one response --
     `GET /admin/sources/:type/:value`. */
+export interface AdminSourceAddress {
+    emailHash: string;
+    /** Plaintext while a row still holds it. */
+    email: string | null;
+    confirmed: boolean;
+    comments: number;
+    messages: number;
+    lastSeenAt: string;
+}
+export interface AdminSourceDevice {
+    clientFp: string;
+    browser: string | null;
+    os: string | null;
+    comments: number;
+    reactions: number;
+    messages: number;
+    lastSeenAt: string;
+}
 export interface AdminSourceProfile {
     key: {
         type: AdminSourceKeyType;
@@ -406,6 +749,19 @@ export interface AdminSourceProfile {
         held: number;
         reactions: number;
     };
+    /** Owner messages under this key. Absent from a site-api that predates it. */
+    messages?: {
+        total: number;
+        byState: Record<MessageState, number>;
+        /** Newest 50. */
+        rows: AdminOwnerMessage[];
+    };
+    /** Addresses written under this key, newest first, at most 10. `confirmed`
+        means a signed-in reader wrote with it; a typed address is evidence of
+        what this key claimed, never a link to that reader. */
+    addresses?: AdminSourceAddress[];
+    /** Device fingerprints seen under this key, newest first, at most 10. */
+    devices?: AdminSourceDevice[];
     /** Writes per hour over the source's last 7 days. */
     hourly: Array<{
         hour: string;
@@ -640,3 +996,46 @@ export interface AdminReactionInsights {
         sessions: number;
     }>;
 }
+/** Reject and restore are logged as `comment.moderate`, with the status
+    they left the row in. */
+export declare const ADMIN_ACTIVITY_EVENTS: readonly ['comment.create', 'comment.edit', 'comment.remove', 'comment.moderate', 'comment.approve', 'comment.hide', 'comment.delete', 'reaction.add', 'reaction.remove'];
+export type AdminActivityEvent = (typeof ADMIN_ACTIVITY_EVENTS)[number];
+export type AdminActivityActor = 'reader' | 'model' | 'owner';
+export type AdminActivitySource = 'web' | 'portal' | 'telegram' | 'cron';
+export type AdminActivityTargetType = 'comment' | 'post';
+export type AdminActivityFamily = 'comments' | 'reactions';
+export interface AdminActivityRecord {
+    id: string;
+    createdAt: string;
+    event: AdminActivityEvent;
+    actor: AdminActivityActor;
+    source: AdminActivitySource;
+    targetType: AdminActivityTargetType;
+    targetId: string;
+    postId: string | null;
+    postTitle: string | null;
+    postSlug: string | null;
+    displayName: string | null;
+    readerId: string | null;
+    anonymous: boolean;
+    emoji: string | null;
+    status: string | null;
+    reason: string | null;
+    note: string | null;
+}
+export interface AdminActivitySummary {
+    byEvent: Record<AdminActivityEvent, number>;
+    today: number;
+    reactionsNet: number;
+    daily: Array<{
+        date: string;
+        comments: number;
+        reactions: number;
+    }>;
+}
+export interface AdminActivityListResult {
+    summary: AdminActivitySummary;
+    entries: AdminActivityRecord[];
+    total: number;
+    nextOffset: number | null;
+}

package/dist/admin.js

@@ -0,0 +1,17 @@
+// src/admin.ts
+var ADMIN_COMMENT_REJECT_REASONS = ["spam", "promotional", "abuse", "off_topic", "personal_info"];
+var ADMIN_ACTIVITY_EVENTS = [
+  "comment.create",
+  "comment.edit",
+  "comment.remove",
+  "comment.moderate",
+  "comment.approve",
+  "comment.hide",
+  "comment.delete",
+  "reaction.add",
+  "reaction.remove"
+];
+export {
+  ADMIN_ACTIVITY_EVENTS,
+  ADMIN_COMMENT_REJECT_REASONS
+};

package/dist/comments.d.ts

@@ -348,14 +348,31 @@ export interface Comment {
     /** Soft-deleted but kept as a shape-preserving placeholder because a reply
         hangs underneath it. `body`/`author` are empty on a tombstone. */
     tombstone: boolean;
+    /** The owner pinned this root above the thread. At most one per post;
+        absent on every other row, replies included, and on every row from a
+        server that predates pins. */
+    pinned?: boolean;
+    /** The owner closed this root's thread to new replies; a reply under it
+        is refused with `403 thread_locked`. Set on the root only; absent
+        means open. */
+    locked?: boolean;
 }
 export interface CommentListResult {
+    /** The page's roots, newest first, then their replies. The first page
+        (no `before`) puts the post's pinned root ahead of the other roots when
+        it has one, on top of `limit` roots; no later page repeats it. */
     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;
+    /** The post's policy when the owner overrode its mode in the portal or a
+        site-wide switch applies, on the first page only. Absent means the post
+        follows its tags, which the page was drawn from -- nothing to
+        reconcile. The page acts on `mode`, and on `requireVerifiedEmail` by
+        drawing the address as required. */
+    policy?: CommentPolicy;
 }
 export interface CommentCreateInput {
     /** Defaults to `blog`. `mood` requires the post to have a linked

package/dist/index.js

@@ -10,6 +10,19 @@ var BLOG_ANALYTICS_EVENTS_DEFAULT_LIMIT = 50;
 var BLOG_ANALYTICS_READ_THRESHOLD_MS = 5000;
 var BLOG_ANALYTICS_COMPLETION_SCROLL_DEPTH = 0.9;
 var BLOG_ANALYTICS_RANGE_OPTIONS = [7, 30, 90];
+// src/admin.ts
+var ADMIN_COMMENT_REJECT_REASONS = ["spam", "promotional", "abuse", "off_topic", "personal_info"];
+var ADMIN_ACTIVITY_EVENTS = [
+  "comment.create",
+  "comment.edit",
+  "comment.remove",
+  "comment.moderate",
+  "comment.approve",
+  "comment.hide",
+  "comment.delete",
+  "reaction.add",
+  "reaction.remove"
+];
 // src/comments.ts
 var READER_PROVIDERS = ["email", "github", "google"];
 var COMMENT_LOCALES = ["zh", "en"];
@@ -218,7 +231,9 @@ var TELEGRAM_OPS_BROADCAST_STATUSES = [
   "failed"
 ];
 export {
+  ADMIN_ACTIVITY_EVENTS,
   ADMIN_BASE_PATH,
+  ADMIN_COMMENT_REJECT_REASONS,
   API_PREFIX,
   AVATAR_CLASSES,
   AVATAR_OFFER_SIZE,

package/dist/messages.d.ts

@@ -12,6 +12,7 @@
  * reader identity, and the ops-bot notification. See site-api's
  * features/messages/server/message-service.ts.
  */
+import type { ClientEvidence } from './comments';
 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. */
@@ -31,7 +32,9 @@ export declare const MESSAGE_MAX_NAME_LENGTH = 32;
  */
 export declare const MESSAGE_STATES: readonly ['new', 'read', 'replied', 'archived', 'spam'];
 export type MessageState = (typeof MESSAGE_STATES)[number];
-export interface OwnerMessageCreateInput {
+/** The fingerprint fields are the comment box's own evidence
+    (`ClientEvidence`): optional, bounded, and never a gate. */
+export interface OwnerMessageCreateInput extends ClientEvidence {
     /** Plain text, MESSAGE_MIN_BODY_LENGTH–MESSAGE_MAX_BODY_LENGTH characters. */
     body: string;
     displayName: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bunizao/contracts",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Shared TypeScript contracts for buxx.me services and clients.",
   "type": "module",
   "sideEffects": false,