@bunizao/contracts 0.6.1 → 0.7.1

package/dist/admin.d.ts

@@ -1,4 +1,4 @@
-import type { ClientFingerprint, CommentStatus, Interaction } from './comments';
+import type { ClientFingerprint, CommentAuthAtWrite, CommentClaimMethod, CommentStatus, Interaction } from './comments';
 import type { DeliveryMode, NotifyAuditEventType, NotifyChannel, SubscriberRecord, SubscriberStatus } from './notify';
 export interface SubscriberChannelCount {
     total: number;
@@ -211,6 +211,10 @@ export interface AdminClusterCount {
     and no body hash. */
 export interface AdminCommentActor {
     readerId: string | null;
+    /** Missing on older responses means unknown, not authenticated. */
+    authAtWrite?: CommentAuthAtWrite;
+    claimedAt?: string | null;
+    claimMethod?: CommentClaimMethod | null;
     /** Plaintext while the row still holds it (verified: with the row;
         unverified: seven days). */
     email: string | null;
@@ -297,10 +301,60 @@ export interface AdminBanResult {
         comments: number;
         reactions: number;
     };
+    operation?: AdminBanOperation | null;
+}
+export interface AdminBanPreview {
+    accounts: number;
+    sessions: number;
+    comments: Record<AdminCommentStatus | 'total', number>;
+    reactions: number;
+    purge: {
+        comments: number;
+        reactions: number;
+    };
+    windowDays: 90;
+    purgeLimit: number;
+    purgeAllowed: boolean;
+}
+export interface AdminBanOperation {
+    id: string;
+    createdAt: string;
+    source: AdminBanSource;
+    keys: AdminBanInput['keys'];
+    note: string | null;
+    purged: {
+        comments: number;
+        reactions: number;
+    };
+    restoredAt: string | null;
+    restorableUntil: string;
+    restored: {
+        comments: number;
+        reactions: number;
+    };
+    skipped: {
+        comments: number;
+        reactions: number;
+    };
+}
+export interface AdminBanOperationListResult {
+    operations: AdminBanOperation[];
+}
+export interface AdminBanRestoreResult {
+    operation: AdminBanOperation;
 }
 export interface AdminBanListResult {
     bans: AdminBan[];
 }
+export interface AdminBannedReader {
+    readerId: string;
+    email: string;
+    displayName: string | null;
+    updatedAt: string;
+}
+export interface AdminBannedReaderListResult {
+    readers: AdminBannedReader[];
+}
 /** Everything about one key in one response --
     `GET /admin/sources/:type/:value`. */
 export interface AdminSourceProfile {
@@ -308,6 +362,13 @@ export interface AdminSourceProfile {
         type: AdminSourceKeyType;
         value: string;
     };
+    identitySummary?: {
+        verifiedAccounts: number;
+        anonymousSessions: number;
+        claimedComments: number;
+        sharedStorage: boolean;
+        sharedFingerprint: boolean;
+    };
     firstSeenAt: string | null;
     lastSeenAt: string | null;
     comments: {
@@ -327,9 +388,7 @@ export interface AdminSourceProfile {
         /** 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. */
+    /** Distinct observed values. Shared environments do not establish a person. */
     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<{
@@ -337,9 +396,8 @@ export interface AdminSourceProfile {
         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. */
+    /** Links describe verified-at-write account evidence or shared storage.
+        clientFpStable remains zero for compatibility; it never creates links. */
     linked: {
         sessions: number;
         via: Record<'email' | 'clientFpStable' | 'storageId', number>;
@@ -374,12 +432,52 @@ export interface AdminInsightRow {
 }
 export type AdminCommentInsightsWindow = '7d' | '30d' | '90d';
 export type AdminReactionInsightsWindow = '48h' | '7d';
+export interface AdminCommentQuality {
+    since: string;
+    collectedSince: string | null;
+    available: {
+        moderation: boolean;
+        requests: boolean;
+        clientReports: boolean;
+    };
+    /** A cohort of automatically held comments and the first later owner decision. */
+    moderation: {
+        held: number;
+        reviewed: number;
+        released: number;
+        releasedShare: number | null;
+    };
+    /** Request outcomes include retries. Authenticated does not mean known benign. */
+    requests: {
+        attempts: number;
+        failures: number;
+        failureShare: number | null;
+        authenticatedAttempts: number;
+        authenticatedFailures: number;
+        authenticatedFailureShare: number | null;
+        outcomes: Array<{
+            kind: 'comment' | 'reaction';
+            outcome: string;
+            count: number;
+        }>;
+    };
+    /** Self-reported and incomplete when the browser cannot deliver telemetry. */
+    clientReports: {
+        reports: number;
+        failures: number;
+        networkFailures: number;
+        challengedAttempts: number;
+        repeatedChallenges: number;
+        untrusted: true;
+    };
+}
 /** `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;
+    quality?: AdminCommentQuality;
     networks: Array<AdminInsightRow & {
         asn: number | null;
         asOrg: string | null;

package/dist/comments.d.ts

@@ -42,7 +42,7 @@ export declare function commentAnchorToken(commentId: string): Promise<string>;
 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'];
+export declare const MODERATION_REASONS: readonly ['ok', 'spam', 'promotional', 'abuse', 'off_topic', 'personal_info', 'dwell_expired'];
 export type ModerationReason = (typeof MODERATION_REASONS)[number];
 /** Never sent to a reader. Rides along on the owner's Telegram notification. */
 export interface ModerationVerdict {
@@ -491,3 +491,30 @@ export declare function commentPolicyFromTags(tags: readonly CommentPolicyTagLik
     `readonly` and `off` answer no; the difference between them is drawn, not
     enforced. */
 export declare const acceptsComments: (policy: CommentPolicy) => boolean;
+/** Evidence recorded when the comment was written, never upgraded by claiming. */
+export type CommentAuthAtWrite = 'unknown' | 'anonymous' | 'verified';
+export type CommentClaimMethod = 'session' | 'confirmed';
+export interface ReaderClaimCandidate {
+    id: string;
+    surface: CommentSurface;
+    postId: string;
+    body: string;
+    createdAt: string;
+    authorName: string;
+}
+export interface ReaderClaimsResult {
+    comments: ReaderClaimCandidate[];
+    hasMore: boolean;
+}
+export interface ReaderClaimsInput {
+    commentIds: string[];
+}
+export interface ReaderClaimResult {
+    claimedIds: string[];
+}
+/** Optional client reports are operational observations, never identity evidence. */
+export interface CommentTelemetryInput {
+    kind: 'comment' | 'reaction';
+    outcome: 'accepted' | 'http_error' | 'network_error' | 'challenge_failed';
+    challenges: number;
+}

package/dist/comments.js

@@ -18,7 +18,8 @@ var MODERATION_REASONS = [
   "promotional",
   "abuse",
   "off_topic",
-  "personal_info"
+  "personal_info",
+  "dwell_expired"
 ];
 var READER_VERIFY_OUTCOMES = ["confirmed", "already_confirmed", "expired", "invalid"];
 var READER_MUTE_OUTCOMES = ["muted", "unmuted", "invalid"];

package/dist/index.js

@@ -10,7 +10,6 @@ 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/comments.ts
 var READER_PROVIDERS = ["email", "github", "google"];
 var COMMENT_LOCALES = ["zh", "en"];
@@ -31,7 +30,8 @@ var MODERATION_REASONS = [
   "promotional",
   "abuse",
   "off_topic",
-  "personal_info"
+  "personal_info",
+  "dwell_expired"
 ];
 var READER_VERIFY_OUTCOMES = ["confirmed", "already_confirmed", "expired", "invalid"];
 var READER_MUTE_OUTCOMES = ["muted", "unmuted", "invalid"];
@@ -73,7 +73,6 @@ function commentPolicyFromTags(tags, base = DEFAULT_COMMENT_POLICY) {
   return policy;
 }
 var acceptsComments = (policy) => policy.mode === "open";
-
 // src/content.ts
 var CONTENT_DOCUMENT_SOURCES = ["mood", "post"];
 var POST_LOCALE_RE = /^[a-z]{2,8}(?:-[a-z0-9]{1,8})*$/;
@@ -99,15 +98,12 @@ 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"];
-
 // src/routes.ts
 var API_PREFIX = "/api";
 var HEALTH_PATH = "/health";
@@ -147,7 +143,6 @@ var LEGACY_NOTIFY_BASE_PATH = "/v2/notify";
 var LEGACY_GHOST_WEBHOOK_PATH = "/v2/ghost/webhook";
 var LEGACY_MUSICKIT_TOKEN_PATH = "/v2/musickit/token";
 var LEGACY_HEALTH_PATH = "/v2/health";
-
 // src/telegram-ops.ts
 var TELEGRAM_OPS_WEBHOOK_PATH = "/webhooks/telegram-ops";
 var TELEGRAM_OPS_COMMENT_CALLBACK_PREFIXES = {

package/package.json

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