@bunizao/contracts 0.12.0 → 0.14.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/analytics.d.ts

@@ -206,3 +206,156 @@ export interface BlogAnalyticsArticleDetailResult {
     countries: BlogAnalyticsBreakdown[];
     scrollBuckets: BlogAnalyticsScrollBucket[];
 }
+export declare const SITE_ANALYTICS_COLLECT_ENDPOINT: '/api/analytics/collect';
+export declare const SITE_ANALYTICS_REPORT_ENDPOINT: '/api/analytics/site';
+export declare const SITE_ANALYTICS_ENGAGED_DWELL_MS = 10000;
+export declare const SITE_ANALYTICS_SESSION_IDLE_MS: number;
+export declare const SITE_ANALYTICS_SURFACES: readonly ['home', 'legacy', 'not_found', 'blog_index', 'blog_tags', 'blog_tag', 'blog_post', 'mood_feed', 'mood_post', 'mood_embed', 'projects', 'message', 'privacy', 'subscribe_manage', 'reader', 'docs', 'components', 'other'];
+export type SiteAnalyticsSurface = typeof SITE_ANALYTICS_SURFACES[number];
+export type SiteAnalyticsClickKind = 'link_internal' | 'link_outbound' | 'button' | 'panel';
+export type SiteAnalyticsTrafficClass = 'human' | 'bot' | 'owner';
+export interface SiteAnalyticsClick {
+    name: string;
+    kind: SiteAnalyticsClickKind;
+    href: string;
+    region: string;
+    label: string;
+    position: number;
+    tMs: number;
+}
+export interface SiteAnalyticsCollectInput {
+    v: 1;
+    viewId: string;
+    visitorId: string;
+    sessionId: string;
+    seq: number;
+    owner?: true;
+    page: {
+        surface: SiteAnalyticsSurface;
+        entity: string;
+        path: string;
+        locale: string;
+        referrer: string;
+        utm: [string, string, string];
+    };
+    client: {
+        tz: string;
+        langs: string[];
+        vw: number;
+        vh: number;
+        dpr: number;
+        navType: 0 | 1 | 2 | 3;
+        isEntry: boolean;
+        isNewVisitor: boolean;
+        webdriver: boolean;
+    };
+    progress: {
+        dwellMs: number;
+        scrollDepth: number;
+        interactions: number;
+        firstInputMs: number;
+        hiddenCount: number;
+        metric1: number;
+        metric2: number;
+    };
+    clicks: SiteAnalyticsClick[];
+}
+export declare const SITE_ANALYTICS_REPORTS: readonly ['overview', 'pages', 'clicks', 'sources', 'audience', 'quality', 'log', 'visitor'];
+export type SiteAnalyticsReportName = typeof SITE_ANALYTICS_REPORTS[number];
+export interface SiteAnalyticsMetrics {
+    views: number;
+    engaged: number;
+    visitors: number;
+    sessions: number;
+    bounces: number;
+    entries: number;
+    exits: number;
+    reads: number;
+    completions: number;
+    clicks: number;
+    medianDwellMs: number;
+    scrollDepth: number;
+    metric1: number;
+    metric2: number;
+}
+export interface SiteAnalyticsPageRow extends SiteAnalyticsMetrics {
+    day: string;
+    surface: string;
+    entity: string;
+}
+export interface SiteAnalyticsClickRow {
+    day: string;
+    surface: string;
+    entity: string;
+    name: string;
+    href: string;
+    clicks: number;
+    visitors: number;
+    medianTimeMs: number | null;
+    clickThrough: number;
+}
+export interface SiteAnalyticsDimensionRow {
+    day: string;
+    surface: string;
+    dim: string;
+    key: string;
+    views: number;
+    visitors: number;
+    engaged: number;
+    dwellMsSum: number;
+}
+export interface SiteAnalyticsTrafficRow {
+    day: string;
+    surface: string;
+    class: SiteAnalyticsTrafficClass;
+    reason: string;
+    views: number;
+    visitors: number;
+}
+export interface SiteAnalyticsViewRecord {
+    viewId: string;
+    visitorId: string;
+    sessionId: string;
+    startedAt: string;
+    updatedAt: string;
+    class: SiteAnalyticsTrafficClass;
+    reason: string;
+    weight: number;
+    page: SiteAnalyticsCollectInput['page'];
+    client: SiteAnalyticsCollectInput['client'];
+    progress: SiteAnalyticsCollectInput['progress'];
+    clicks: SiteAnalyticsClick[];
+    country: string;
+    region: string;
+    city: string;
+    ip: string;
+    ua: string;
+    browser: string;
+    os: string;
+    device: string;
+    platform: string;
+    network: string;
+    refSource: string;
+    refHost: string;
+    clickCount: number;
+}
+export interface SiteAnalyticsReportResult {
+    report: SiteAnalyticsReportName;
+    from: string;
+    to: string;
+    timezone: 'Australia/Melbourne';
+    sampled: boolean;
+    visitors: number | null;
+    visitorBasis: 'distinct' | 'sampled_distinct' | 'sum_monthly' | 'unavailable';
+    pages: SiteAnalyticsPageRow[];
+    clicks: SiteAnalyticsClickRow[];
+    dimensions: SiteAnalyticsDimensionRow[];
+    traffic: SiteAnalyticsTrafficRow[];
+    events: SiteAnalyticsViewRecord[];
+    nextCursor: string | null;
+    rum: Array<{
+        surface: string;
+        loads: number;
+    }> | null;
+    notices: string[];
+}

package/dist/analytics.js

@@ -10,6 +10,31 @@ 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];
+var SITE_ANALYTICS_COLLECT_ENDPOINT = "/api/analytics/collect";
+var SITE_ANALYTICS_REPORT_ENDPOINT = "/api/analytics/site";
+var SITE_ANALYTICS_ENGAGED_DWELL_MS = 1e4;
+var SITE_ANALYTICS_SESSION_IDLE_MS = 30 * 60000;
+var SITE_ANALYTICS_SURFACES = [
+  "home",
+  "legacy",
+  "not_found",
+  "blog_index",
+  "blog_tags",
+  "blog_tag",
+  "blog_post",
+  "mood_feed",
+  "mood_post",
+  "mood_embed",
+  "projects",
+  "message",
+  "privacy",
+  "subscribe_manage",
+  "reader",
+  "docs",
+  "components",
+  "other"
+];
+var SITE_ANALYTICS_REPORTS = ["overview", "pages", "clicks", "sources", "audience", "quality", "log", "visitor"];
 export {
   BLOG_ANALYTICS_ARTICLE_ENDPOINT,
   BLOG_ANALYTICS_COMPLETION_SCROLL_DEPTH,
@@ -21,5 +46,11 @@ export {
   BLOG_ANALYTICS_SUMMARY_ENDPOINT,
   LISTENING_ANALYTICS_EVENT_ENDPOINT,
   NEWSLETTER_ANALYTICS_CLICK_ENDPOINT,
-  NEWSLETTER_ANALYTICS_OPEN_ENDPOINT
+  NEWSLETTER_ANALYTICS_OPEN_ENDPOINT,
+  SITE_ANALYTICS_COLLECT_ENDPOINT,
+  SITE_ANALYTICS_ENGAGED_DWELL_MS,
+  SITE_ANALYTICS_REPORTS,
+  SITE_ANALYTICS_REPORT_ENDPOINT,
+  SITE_ANALYTICS_SESSION_IDLE_MS,
+  SITE_ANALYTICS_SURFACES
 };

package/dist/index.js

@@ -10,6 +10,31 @@ 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];
+var SITE_ANALYTICS_COLLECT_ENDPOINT = "/api/analytics/collect";
+var SITE_ANALYTICS_REPORT_ENDPOINT = "/api/analytics/site";
+var SITE_ANALYTICS_ENGAGED_DWELL_MS = 1e4;
+var SITE_ANALYTICS_SESSION_IDLE_MS = 30 * 60000;
+var SITE_ANALYTICS_SURFACES = [
+  "home",
+  "legacy",
+  "not_found",
+  "blog_index",
+  "blog_tags",
+  "blog_tag",
+  "blog_post",
+  "mood_feed",
+  "mood_post",
+  "mood_embed",
+  "projects",
+  "message",
+  "privacy",
+  "subscribe_manage",
+  "reader",
+  "docs",
+  "components",
+  "other"
+];
+var SITE_ANALYTICS_REPORTS = ["overview", "pages", "clicks", "sources", "audience", "quality", "log", "visitor"];
 // src/admin.ts
 var ADMIN_COMMENT_REJECT_REASONS = ["spam", "promotional", "abuse", "off_topic", "personal_info"];
 var ADMIN_ACTIVITY_EVENTS = [
@@ -131,6 +156,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 +345,13 @@ export {
   READER_RESEND_PATH,
   READER_VERIFY_OUTCOMES,
   READER_VERIFY_PATH,
+  SITE_ANALYTICS_COLLECT_ENDPOINT,
+  SITE_ANALYTICS_ENGAGED_DWELL_MS,
+  SITE_ANALYTICS_REPORTS,
+  SITE_ANALYTICS_REPORT_ENDPOINT,
+  SITE_ANALYTICS_SESSION_IDLE_MS,
+  SITE_ANALYTICS_SURFACES,
+  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/notify.d.ts

@@ -4,6 +4,16 @@ 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;
@@ -14,6 +24,8 @@ export interface SubscribeRequest extends ClientEvidence {
     dailyHour?: number;
     website?: string;
     dwellToken?: string;
+    /** First subscription surface. Unknown values are ignored by the server. */
+    source?: SubscriptionSource;
 }
 export interface SubscriberRecord {
     email: string;
@@ -32,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.12.0",
+  "version": "0.14.0",
   "description": "Shared TypeScript contracts for buxx.me services and clients.",
   "type": "module",
   "sideEffects": false,