@bunizao/contracts 0.6.1 → 0.7.0

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,6 +301,47 @@ 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[];
@@ -308,6 +353,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 +379,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 +387,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 +423,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

@@ -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/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"];
@@ -73,7 +72,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 +97,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 +142,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.0",
   "description": "Shared TypeScript contracts for buxx.me services and clients.",
   "type": "module",
   "sideEffects": false,