@bunizao/contracts 0.11.0 → 0.13.0

package/dist/admin.d.ts

@@ -1,6 +1,6 @@
 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';
+import type { DeliveryMode, NotifyAuditEventType, NotifyChannel, SubscriberRecord, SubscriberStatus, SubscriptionSource } from './notify';
 export interface SubscriberChannelCount {
     total: number;
     pendingCount: number;
@@ -24,6 +24,8 @@ export interface SubscriberListResult {
     activeCount: number;
     unsubscribedCount: number;
     channelCounts?: SubscriberChannelCounts;
+    /** Acquisition counts, kept separate from the subscribed channels. */
+    acquisitionCounts?: Record<SubscriptionSource | 'unknown', SubscriberChannelCount>;
 }
 export interface AuditEntry {
     id: number;

package/dist/comments.d.ts

@@ -64,7 +64,8 @@ export interface ReaderMe {
         has been handed out -- the client then draws from the name. */
     avatarSeed: number | null;
     notifyReplies: boolean;
-    /** Whether this address holds an active newsletter subscription. */
+    /** Whether this address holds an active subscription that includes the blog
+        channel -- the reader switch is "latest posts", so mood alone reads false. */
     subscribed: boolean;
 }
 export interface ReaderMeResult {
@@ -453,8 +454,9 @@ export interface CommentPolicy {
         Independent of `mode`: a post can take reactions with comments off, and
         an open thread can refuse them. */
     reactions: boolean;
-    /** Accept a comment only from an address that has been verified. Anonymous
-        and unverified-email writers are refused rather than held. */
+    /** Publish a comment only from an address that has been verified. An
+        anonymous writer must give an address, and the comment is held until
+        they confirm it; one with no address is refused. */
     requireVerifiedEmail: boolean;
 }
 export declare const DEFAULT_COMMENT_POLICY: CommentPolicy;
@@ -464,8 +466,9 @@ export declare const COMMENT_POLICY_TAGS: {
     readonly 'no-comments': (policy: CommentPolicy) => CommentPolicy;
     readonly 'reactions-off': (policy: CommentPolicy) => {
         mode: CommentsMode;
-        /** Accept a comment only from an address that has been verified. Anonymous
-            and unverified-email writers are refused rather than held. */
+        /** Publish a comment only from an address that has been verified. An
+            anonymous writer must give an address, and the comment is held until
+            they confirm it; one with no address is refused. */
         requireVerifiedEmail: boolean;
         reactions: false;
     };

package/dist/content.d.ts

@@ -1,5 +1,22 @@
 export declare const CONTENT_DOCUMENT_SOURCES: readonly ['mood', 'post'];
 export type ContentDocumentSource = (typeof CONTENT_DOCUMENT_SOURCES)[number];
+/** Public read aggregates since analytics collection began. */
+export interface BlogStats {
+    generatedAt: string;
+    /** Null until the first event has been recorded. */
+    since: string | null;
+    totals: {
+        reads: number;
+        readers: number;
+        completed: number;
+    };
+    posts: {
+        slug: string;
+        reads: number;
+        completed: number;
+        medianDwellMs: number;
+    }[];
+}
 export interface PostLocaleTag {
     locale: string;
     canonicalSlug?: string;

package/dist/index.js

@@ -131,6 +131,7 @@ 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"];
+var SUBSCRIPTION_SOURCES = ["desk", "blog", "mood"];
 // src/routes.ts
 var API_PREFIX = "/api";
 var HEALTH_PATH = "/health";
@@ -319,6 +320,7 @@ export {
   READER_RESEND_PATH,
   READER_VERIFY_OUTCOMES,
   READER_VERIFY_PATH,
+  SUBSCRIPTION_SOURCES,
   TELEGRAM_OPS_BASE_PATH,
   TELEGRAM_OPS_BROADCASTS_PATH,
   TELEGRAM_OPS_BROADCAST_CHANNELS,

package/dist/listening.d.ts

@@ -1,3 +1,18 @@
+/** Site playback totals in a rolling seven-day window, not Apple Music history. */
+export interface ListeningStats {
+    generatedAt: string;
+    window: {
+        from: string;
+        to: string;
+    };
+    totals: {
+        plays: number;
+    };
+    topArtist: {
+        name: string;
+        plays: number;
+    } | null;
+}
 export interface ListeningAccent {
     hue: number;
     chromaLight: number;

package/dist/mood.d.ts

@@ -22,16 +22,9 @@ export interface MoodStatsActivityBucket {
     date: string;
     count: number;
 }
-export interface MoodStatsSentimentBucket {
-    bucketStart: string;
-    avgValence: number | null;
-    dominantLabel: MoodSentimentLabel | null;
-    scoredCount: number;
-}
 export interface MoodStatsSnapshot {
     activity: MoodStatsActivityBucket[];
     rhythm: number[][];
-    sentimentTimeline: MoodStatsSentimentBucket[];
     streaks: {
         current: number;
         longest: number;

package/dist/notify.d.ts

@@ -1,8 +1,32 @@
+import type { ClientEvidence } from './comments';
 export type SubscriberStatus = 'pending' | 'active' | 'unsubscribed';
 export type DeliveryMode = 'immediate' | 'every_5h' | 'daily';
 export type NotifyChannel = 'mood' | 'blog' | 'privacy' | 'announcement';
 export type NotifyAuditEventType = 'subscribe_requested' | 'subscription_confirmed' | 'unsubscribed' | 'email_change_requested' | 'email_changed' | 'admin_create' | 'admin_update' | 'admin_delete' | 'admin_resend_confirm' | 'broadcast_sent';
 export declare const NOTIFY_CHANNELS: readonly NotifyChannel[];
+export declare const SUBSCRIPTION_SOURCES: readonly ['desk', 'blog', 'mood'];
+export type SubscriptionSource = (typeof SUBSCRIPTION_SOURCES)[number];
+/** Public counts of active, confirmed, deliverable email subscriptions. */
+export interface SubscriberCounts {
+    generatedAt: string;
+    channels: {
+        blog: number;
+        mood: number;
+    };
+}
+/** Optional risk evidence preserves compatibility with existing clients. */
+export interface SubscribeRequest extends ClientEvidence {
+    email: string;
+    turnstileToken?: string;
+    channels?: NotifyChannel[];
+    deliveryMode?: DeliveryMode;
+    timezone?: string;
+    dailyHour?: number;
+    website?: string;
+    dwellToken?: string;
+    /** First subscription surface. Unknown values are ignored by the server. */
+    source?: SubscriptionSource;
+}
 export interface SubscriberRecord {
     email: string;
     emailHash: string;
@@ -20,6 +44,8 @@ export interface SubscriberRecord {
     updatedAt: string;
     confirmedAt?: string;
     lastConfirmSentAt?: string;
+    /** First recorded subscription surface; absent for historical subscribers. */
+    source?: SubscriptionSource;
 }
 export interface RetryRecord {
     postId: string;

package/dist/notify.js

@@ -1,5 +1,7 @@
 // src/notify.ts
 var NOTIFY_CHANNELS = ["mood", "blog", "privacy", "announcement"];
+var SUBSCRIPTION_SOURCES = ["desk", "blog", "mood"];
 export {
-  NOTIFY_CHANNELS
+  NOTIFY_CHANNELS,
+  SUBSCRIPTION_SOURCES
 };

package/package.json

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