@mushi-mushi/core 1.23.0 → 1.25.0

package/dist/index.d.cts

@@ -1390,6 +1390,10 @@ interface MushiApiClient {
     postDiscoveryEvent(event: MushiDiscoveryEventPayload): Promise<MushiApiResponse<{
         accepted: boolean;
     }>>;
+    /** POST /v1/sdk/session — lightweight session lifecycle event (best-effort). */
+    postSessionEvent(payload: MushiSessionEventPayload): Promise<MushiApiResponse<{
+        accepted: boolean;
+    }>>;
     listReporterReports(reporterToken: string): Promise<MushiApiResponse<{
         reports: MushiReporterReport[];
     }>>;
@@ -1520,6 +1524,28 @@ interface MushiDiscoveryEventPayload {
     sdk_version?: string;
     observed_at: string;
 }
+/** Payload for /v1/sdk/session — lightweight session lifecycle tracking.
+ *  Best-effort, no offline queue. Privacy-safe: no PII by default;
+ *  `user_id_hash` is the same device-fingerprint hash used elsewhere. */
+interface MushiSessionEventPayload {
+    /** Lifecycle event kind. */
+    kind: 'session_start' | 'session_heartbeat' | 'session_end' | 'page_view';
+    session_id: string;
+    /** ISO timestamp of the event. */
+    ts: string;
+    /** Entry route for session_start; current route for page_view. */
+    route?: string | null;
+    /** document.referrer on session_start. */
+    referrer?: string | null;
+    /** Total page views in this session so far (updated on heartbeat/end). */
+    page_view_count?: number;
+    /** Device fingerprint hash — same token used in reports. */
+    reporter_token_hash?: string | null;
+    /** user_id_hash when the host app called Mushi.identify(). */
+    user_id_hash?: string | null;
+    user_agent?: string | null;
+    sdk_version?: string;
+}
 interface MushiApiResponse<T> {
     ok: boolean;
     data?: T;
@@ -1932,6 +1958,48 @@ declare function getDeviceFingerprintHash(): Promise<string | null>;
 
 declare function getSessionId(): string;
 
+/**
+ * FILE: packages/core/src/session-tracker.ts
+ * PURPOSE: Lightweight session-lifecycle tracking for the Mushi SDK.
+ *
+ * Emits best-effort events to /v1/sdk/session so the console can show per-
+ * project activity analytics (DAU/WAU, page views, identified vs. anonymous
+ * user split, top routes). Mirrors the postDiscoveryEvent pattern: 1 retry,
+ * no offline queue, fire-and-forget after visibility-change.
+ *
+ * Privacy:
+ *   - No PII by default. `reporter_token_hash` is the same opaque device
+ *     fingerprint already used in reports. `user_id_hash` is only set when
+ *     the host app calls Mushi.identify().
+ *   - Respects the SDK-level `trackSessions: false` opt-out option.
+ *   - Respects a DNT / Global Privacy Control header at the SDK init layer;
+ *     callers should check `shouldRespectDnt()` before calling `initSession`.
+ */
+
+interface SessionTrackerOptions {
+    client: MushiApiClient;
+    sdkVersion?: string;
+    reporterTokenHash?: string | null;
+    userIdHash?: string | null;
+}
+/**
+ * Initialise the session tracker. Call once at SDK init for web environments.
+ * Subsequent calls on the same page are no-ops (idempotent).
+ *
+ * Emits: session_start immediately, heartbeats every minute, session_end on
+ * visibilitychange/pagehide, and page_view on history API navigation.
+ */
+declare function initSessionTracker(opts: SessionTrackerOptions): void;
+/**
+ * Record a page view manually — call from framework router hooks where the
+ * history patch may fire too early (e.g. React Router v7 loader transitions).
+ */
+declare function trackPageView(route?: string): void;
+/** Update the user identity after a Mushi.identify() call. */
+declare function updateSessionIdentity(userIdHash: string | null): void;
+/** Tear down timers (e.g. in tests or SSR environments). */
+declare function destroySessionTracker(): void;
+
 interface RateLimiterConfig {
     maxBurst?: number;
     refillRate?: number;
@@ -2435,4 +2503,4 @@ declare function projectInitialsThemeIndex(projectId: string): number;
  */
 declare function readPageFaviconHref(): string | null;
 
-export { type ApiClientOptions, type BreadcrumbBuffer, type BreadcrumbBufferOptions, DEFAULT_API_ENDPOINT, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, type EnvConfigDiagnostics, type EnvNearMiss, type LogEntry, type LogFormat, type LogLevel, type Logger, type LoggerOptions, MAX_REPORT_PAYLOAD_BYTES, MAX_SCREENSHOT_DATA_URL_BYTES, MUSHI_ACCENT_SHADOW, MUSHI_BANNER_BRAND_BORDER, MUSHI_BANNER_NEON, MUSHI_COLORS_DARK, MUSHI_COLORS_LIGHT, MUSHI_COPY, MUSHI_GEOMETRY, MUSHI_IDENTITY_TOKEN_PREFIX, MUSHI_INTERNAL_HEADER, MUSHI_INTERNAL_INIT_MARKER, MUSHI_INVERSE, MUSHI_MOTION, MUSHI_ON_ACCENT, MUSHI_PROJECT_HEADER, MUSHI_RADIUS, MUSHI_REPORTER_STATUS, MUSHI_SDK_PACKAGE_HEADER, MUSHI_SDK_VERSION_HEADER, MUSHI_SPACING, MUSHI_TIER_COLORS, MUSHI_TYPE, MUSHI_USER_TOKEN_HEADER, MUSHI_Z, type MushiActivityEvent, type MushiApiCascadeConfig, type MushiApiClient, type MushiApiResponse, type MushiAssistantConfig, type MushiAssistantReply, type MushiAssistantStep, type MushiBannerConfig, type MushiBannerLink, type MushiBetaChangelogEntry, type MushiBetaModeConfig, type MushiBreadcrumb, type MushiCaptureConfig, type MushiCaptureEventInput, type MushiCaptureExceptionOptions, type MushiColorPalette, type MushiConfig, type MushiConsoleEntry, type MushiCooldownConfig, type MushiCrossAppReport, type MushiCustomCategory, type MushiDiagnosticsResult, type MushiDiscoverInventoryConfig, type MushiDiscoveryEventPayload, type MushiEnvironment, type MushiEventHandler, type MushiEventType, type MushiHallOfFameEntry, type MushiIdentityClaims, type MushiIntegrationsConfig, type MushiInternalRequestKind, type MushiLeaderboardEntry, type MushiNetworkEntry, type MushiOfflineConfig, type MushiOnDeviceClassifier, type MushiOnDeviceClassifierInput, type MushiOnDeviceClassifierResult, type MushiPageContext, type MushiPerformanceMetrics, type MushiPreFilterConfig, type MushiPreset, type MushiPrivacyConfig, type MushiProactiveConfig, type MushiRegion, type MushiReport, type MushiReportBuilder, type MushiReportCategory, type MushiReportStatus, type MushiReporterComment, type MushiReporterReport, type MushiReputationResult, type MushiRewardsConfig, type MushiRuntimeSdkConfig, type MushiSDKInstance, type MushiSdkVersionInfo, type MushiSelectedElement, type MushiSentryConfig, type MushiSentryContext, type MushiTesterReputation, type MushiThemeMode, type MushiTierResult, type MushiTimelineEntry, type MushiTimelineKind, type MushiTokenSnapshot, type MushiTracePropagationConfig, type MushiUrlMatcher, type MushiWidgetAnchor, type MushiWidgetConfig, type NormalisedException, type OfflineQueue, type PayloadGuardResult, type PiiScrubberConfig, type PreFilterResult, type ProjectFaviconSource, REGION_ENDPOINTS, type RateLimiter, type RateLimiterConfig, type ResolvedEnvConfig, buildIdentityClaims, buildSdkIngestHeaders, captureEnvironment, checkReportPayloadSize, createApiClient, createBreadcrumbBuffer, createLogger, createOfflineQueue, createPiiScrubber, createPreFilter, createRateLimiter, diagnoseEnvConfig, estimateJsonBytes, expandPreset, faviconUrlCandidates, formatBytes, getDeviceFingerprintHash, getReporterToken, getSessionId, githubRepoDomainHint, hmacSha256Hex, isLikelyGenericFavicon, isUntrustedFaviconUrl, mushiPalette, mushiTokens, newUuid, noopLogger, normaliseThrown, originToDomain, parseIdentityToken, projectFaviconUrlCandidates, projectInitials, projectInitialsThemeIndex, readPageFaviconHref, resolveEnvConfig, resolveProjectDomain, resolveProjectFaviconDomains, resolveRegionEndpoint, resolveWidgetAccent, safeWidgetHex, scrubPii, sha256Hex, validateConfig };
+export { type ApiClientOptions, type BreadcrumbBuffer, type BreadcrumbBufferOptions, DEFAULT_API_ENDPOINT, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, type EnvConfigDiagnostics, type EnvNearMiss, type LogEntry, type LogFormat, type LogLevel, type Logger, type LoggerOptions, MAX_REPORT_PAYLOAD_BYTES, MAX_SCREENSHOT_DATA_URL_BYTES, MUSHI_ACCENT_SHADOW, MUSHI_BANNER_BRAND_BORDER, MUSHI_BANNER_NEON, MUSHI_COLORS_DARK, MUSHI_COLORS_LIGHT, MUSHI_COPY, MUSHI_GEOMETRY, MUSHI_IDENTITY_TOKEN_PREFIX, MUSHI_INTERNAL_HEADER, MUSHI_INTERNAL_INIT_MARKER, MUSHI_INVERSE, MUSHI_MOTION, MUSHI_ON_ACCENT, MUSHI_PROJECT_HEADER, MUSHI_RADIUS, MUSHI_REPORTER_STATUS, MUSHI_SDK_PACKAGE_HEADER, MUSHI_SDK_VERSION_HEADER, MUSHI_SPACING, MUSHI_TIER_COLORS, MUSHI_TYPE, MUSHI_USER_TOKEN_HEADER, MUSHI_Z, type MushiActivityEvent, type MushiApiCascadeConfig, type MushiApiClient, type MushiApiResponse, type MushiAssistantConfig, type MushiAssistantReply, type MushiAssistantStep, type MushiBannerConfig, type MushiBannerLink, type MushiBetaChangelogEntry, type MushiBetaModeConfig, type MushiBreadcrumb, type MushiCaptureConfig, type MushiCaptureEventInput, type MushiCaptureExceptionOptions, type MushiColorPalette, type MushiConfig, type MushiConsoleEntry, type MushiCooldownConfig, type MushiCrossAppReport, type MushiCustomCategory, type MushiDiagnosticsResult, type MushiDiscoverInventoryConfig, type MushiDiscoveryEventPayload, type MushiEnvironment, type MushiEventHandler, type MushiEventType, type MushiHallOfFameEntry, type MushiIdentityClaims, type MushiIntegrationsConfig, type MushiInternalRequestKind, type MushiLeaderboardEntry, type MushiNetworkEntry, type MushiOfflineConfig, type MushiOnDeviceClassifier, type MushiOnDeviceClassifierInput, type MushiOnDeviceClassifierResult, type MushiPageContext, type MushiPerformanceMetrics, type MushiPreFilterConfig, type MushiPreset, type MushiPrivacyConfig, type MushiProactiveConfig, type MushiRegion, type MushiReport, type MushiReportBuilder, type MushiReportCategory, type MushiReportStatus, type MushiReporterComment, type MushiReporterReport, type MushiReputationResult, type MushiRewardsConfig, type MushiRuntimeSdkConfig, type MushiSDKInstance, type MushiSdkVersionInfo, type MushiSelectedElement, type MushiSentryConfig, type MushiSentryContext, type MushiSessionEventPayload, type MushiTesterReputation, type MushiThemeMode, type MushiTierResult, type MushiTimelineEntry, type MushiTimelineKind, type MushiTokenSnapshot, type MushiTracePropagationConfig, type MushiUrlMatcher, type MushiWidgetAnchor, type MushiWidgetConfig, type NormalisedException, type OfflineQueue, type PayloadGuardResult, type PiiScrubberConfig, type PreFilterResult, type ProjectFaviconSource, REGION_ENDPOINTS, type RateLimiter, type RateLimiterConfig, type ResolvedEnvConfig, type SessionTrackerOptions, buildIdentityClaims, buildSdkIngestHeaders, captureEnvironment, checkReportPayloadSize, createApiClient, createBreadcrumbBuffer, createLogger, createOfflineQueue, createPiiScrubber, createPreFilter, createRateLimiter, destroySessionTracker, diagnoseEnvConfig, estimateJsonBytes, expandPreset, faviconUrlCandidates, formatBytes, getDeviceFingerprintHash, getReporterToken, getSessionId, githubRepoDomainHint, hmacSha256Hex, initSessionTracker, isLikelyGenericFavicon, isUntrustedFaviconUrl, mushiPalette, mushiTokens, newUuid, noopLogger, normaliseThrown, originToDomain, parseIdentityToken, projectFaviconUrlCandidates, projectInitials, projectInitialsThemeIndex, readPageFaviconHref, resolveEnvConfig, resolveProjectDomain, resolveProjectFaviconDomains, resolveRegionEndpoint, resolveWidgetAccent, safeWidgetHex, scrubPii, sha256Hex, trackPageView, updateSessionIdentity, validateConfig };

package/dist/index.d.ts

@@ -1390,6 +1390,10 @@ interface MushiApiClient {
     postDiscoveryEvent(event: MushiDiscoveryEventPayload): Promise<MushiApiResponse<{
         accepted: boolean;
     }>>;
+    /** POST /v1/sdk/session — lightweight session lifecycle event (best-effort). */
+    postSessionEvent(payload: MushiSessionEventPayload): Promise<MushiApiResponse<{
+        accepted: boolean;
+    }>>;
     listReporterReports(reporterToken: string): Promise<MushiApiResponse<{
         reports: MushiReporterReport[];
     }>>;
@@ -1520,6 +1524,28 @@ interface MushiDiscoveryEventPayload {
     sdk_version?: string;
     observed_at: string;
 }
+/** Payload for /v1/sdk/session — lightweight session lifecycle tracking.
+ *  Best-effort, no offline queue. Privacy-safe: no PII by default;
+ *  `user_id_hash` is the same device-fingerprint hash used elsewhere. */
+interface MushiSessionEventPayload {
+    /** Lifecycle event kind. */
+    kind: 'session_start' | 'session_heartbeat' | 'session_end' | 'page_view';
+    session_id: string;
+    /** ISO timestamp of the event. */
+    ts: string;
+    /** Entry route for session_start; current route for page_view. */
+    route?: string | null;
+    /** document.referrer on session_start. */
+    referrer?: string | null;
+    /** Total page views in this session so far (updated on heartbeat/end). */
+    page_view_count?: number;
+    /** Device fingerprint hash — same token used in reports. */
+    reporter_token_hash?: string | null;
+    /** user_id_hash when the host app called Mushi.identify(). */
+    user_id_hash?: string | null;
+    user_agent?: string | null;
+    sdk_version?: string;
+}
 interface MushiApiResponse<T> {
     ok: boolean;
     data?: T;
@@ -1932,6 +1958,48 @@ declare function getDeviceFingerprintHash(): Promise<string | null>;
 
 declare function getSessionId(): string;
 
+/**
+ * FILE: packages/core/src/session-tracker.ts
+ * PURPOSE: Lightweight session-lifecycle tracking for the Mushi SDK.
+ *
+ * Emits best-effort events to /v1/sdk/session so the console can show per-
+ * project activity analytics (DAU/WAU, page views, identified vs. anonymous
+ * user split, top routes). Mirrors the postDiscoveryEvent pattern: 1 retry,
+ * no offline queue, fire-and-forget after visibility-change.
+ *
+ * Privacy:
+ *   - No PII by default. `reporter_token_hash` is the same opaque device
+ *     fingerprint already used in reports. `user_id_hash` is only set when
+ *     the host app calls Mushi.identify().
+ *   - Respects the SDK-level `trackSessions: false` opt-out option.
+ *   - Respects a DNT / Global Privacy Control header at the SDK init layer;
+ *     callers should check `shouldRespectDnt()` before calling `initSession`.
+ */
+
+interface SessionTrackerOptions {
+    client: MushiApiClient;
+    sdkVersion?: string;
+    reporterTokenHash?: string | null;
+    userIdHash?: string | null;
+}
+/**
+ * Initialise the session tracker. Call once at SDK init for web environments.
+ * Subsequent calls on the same page are no-ops (idempotent).
+ *
+ * Emits: session_start immediately, heartbeats every minute, session_end on
+ * visibilitychange/pagehide, and page_view on history API navigation.
+ */
+declare function initSessionTracker(opts: SessionTrackerOptions): void;
+/**
+ * Record a page view manually — call from framework router hooks where the
+ * history patch may fire too early (e.g. React Router v7 loader transitions).
+ */
+declare function trackPageView(route?: string): void;
+/** Update the user identity after a Mushi.identify() call. */
+declare function updateSessionIdentity(userIdHash: string | null): void;
+/** Tear down timers (e.g. in tests or SSR environments). */
+declare function destroySessionTracker(): void;
+
 interface RateLimiterConfig {
     maxBurst?: number;
     refillRate?: number;
@@ -2435,4 +2503,4 @@ declare function projectInitialsThemeIndex(projectId: string): number;
  */
 declare function readPageFaviconHref(): string | null;
 
-export { type ApiClientOptions, type BreadcrumbBuffer, type BreadcrumbBufferOptions, DEFAULT_API_ENDPOINT, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, type EnvConfigDiagnostics, type EnvNearMiss, type LogEntry, type LogFormat, type LogLevel, type Logger, type LoggerOptions, MAX_REPORT_PAYLOAD_BYTES, MAX_SCREENSHOT_DATA_URL_BYTES, MUSHI_ACCENT_SHADOW, MUSHI_BANNER_BRAND_BORDER, MUSHI_BANNER_NEON, MUSHI_COLORS_DARK, MUSHI_COLORS_LIGHT, MUSHI_COPY, MUSHI_GEOMETRY, MUSHI_IDENTITY_TOKEN_PREFIX, MUSHI_INTERNAL_HEADER, MUSHI_INTERNAL_INIT_MARKER, MUSHI_INVERSE, MUSHI_MOTION, MUSHI_ON_ACCENT, MUSHI_PROJECT_HEADER, MUSHI_RADIUS, MUSHI_REPORTER_STATUS, MUSHI_SDK_PACKAGE_HEADER, MUSHI_SDK_VERSION_HEADER, MUSHI_SPACING, MUSHI_TIER_COLORS, MUSHI_TYPE, MUSHI_USER_TOKEN_HEADER, MUSHI_Z, type MushiActivityEvent, type MushiApiCascadeConfig, type MushiApiClient, type MushiApiResponse, type MushiAssistantConfig, type MushiAssistantReply, type MushiAssistantStep, type MushiBannerConfig, type MushiBannerLink, type MushiBetaChangelogEntry, type MushiBetaModeConfig, type MushiBreadcrumb, type MushiCaptureConfig, type MushiCaptureEventInput, type MushiCaptureExceptionOptions, type MushiColorPalette, type MushiConfig, type MushiConsoleEntry, type MushiCooldownConfig, type MushiCrossAppReport, type MushiCustomCategory, type MushiDiagnosticsResult, type MushiDiscoverInventoryConfig, type MushiDiscoveryEventPayload, type MushiEnvironment, type MushiEventHandler, type MushiEventType, type MushiHallOfFameEntry, type MushiIdentityClaims, type MushiIntegrationsConfig, type MushiInternalRequestKind, type MushiLeaderboardEntry, type MushiNetworkEntry, type MushiOfflineConfig, type MushiOnDeviceClassifier, type MushiOnDeviceClassifierInput, type MushiOnDeviceClassifierResult, type MushiPageContext, type MushiPerformanceMetrics, type MushiPreFilterConfig, type MushiPreset, type MushiPrivacyConfig, type MushiProactiveConfig, type MushiRegion, type MushiReport, type MushiReportBuilder, type MushiReportCategory, type MushiReportStatus, type MushiReporterComment, type MushiReporterReport, type MushiReputationResult, type MushiRewardsConfig, type MushiRuntimeSdkConfig, type MushiSDKInstance, type MushiSdkVersionInfo, type MushiSelectedElement, type MushiSentryConfig, type MushiSentryContext, type MushiTesterReputation, type MushiThemeMode, type MushiTierResult, type MushiTimelineEntry, type MushiTimelineKind, type MushiTokenSnapshot, type MushiTracePropagationConfig, type MushiUrlMatcher, type MushiWidgetAnchor, type MushiWidgetConfig, type NormalisedException, type OfflineQueue, type PayloadGuardResult, type PiiScrubberConfig, type PreFilterResult, type ProjectFaviconSource, REGION_ENDPOINTS, type RateLimiter, type RateLimiterConfig, type ResolvedEnvConfig, buildIdentityClaims, buildSdkIngestHeaders, captureEnvironment, checkReportPayloadSize, createApiClient, createBreadcrumbBuffer, createLogger, createOfflineQueue, createPiiScrubber, createPreFilter, createRateLimiter, diagnoseEnvConfig, estimateJsonBytes, expandPreset, faviconUrlCandidates, formatBytes, getDeviceFingerprintHash, getReporterToken, getSessionId, githubRepoDomainHint, hmacSha256Hex, isLikelyGenericFavicon, isUntrustedFaviconUrl, mushiPalette, mushiTokens, newUuid, noopLogger, normaliseThrown, originToDomain, parseIdentityToken, projectFaviconUrlCandidates, projectInitials, projectInitialsThemeIndex, readPageFaviconHref, resolveEnvConfig, resolveProjectDomain, resolveProjectFaviconDomains, resolveRegionEndpoint, resolveWidgetAccent, safeWidgetHex, scrubPii, sha256Hex, validateConfig };
+export { type ApiClientOptions, type BreadcrumbBuffer, type BreadcrumbBufferOptions, DEFAULT_API_ENDPOINT, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, type EnvConfigDiagnostics, type EnvNearMiss, type LogEntry, type LogFormat, type LogLevel, type Logger, type LoggerOptions, MAX_REPORT_PAYLOAD_BYTES, MAX_SCREENSHOT_DATA_URL_BYTES, MUSHI_ACCENT_SHADOW, MUSHI_BANNER_BRAND_BORDER, MUSHI_BANNER_NEON, MUSHI_COLORS_DARK, MUSHI_COLORS_LIGHT, MUSHI_COPY, MUSHI_GEOMETRY, MUSHI_IDENTITY_TOKEN_PREFIX, MUSHI_INTERNAL_HEADER, MUSHI_INTERNAL_INIT_MARKER, MUSHI_INVERSE, MUSHI_MOTION, MUSHI_ON_ACCENT, MUSHI_PROJECT_HEADER, MUSHI_RADIUS, MUSHI_REPORTER_STATUS, MUSHI_SDK_PACKAGE_HEADER, MUSHI_SDK_VERSION_HEADER, MUSHI_SPACING, MUSHI_TIER_COLORS, MUSHI_TYPE, MUSHI_USER_TOKEN_HEADER, MUSHI_Z, type MushiActivityEvent, type MushiApiCascadeConfig, type MushiApiClient, type MushiApiResponse, type MushiAssistantConfig, type MushiAssistantReply, type MushiAssistantStep, type MushiBannerConfig, type MushiBannerLink, type MushiBetaChangelogEntry, type MushiBetaModeConfig, type MushiBreadcrumb, type MushiCaptureConfig, type MushiCaptureEventInput, type MushiCaptureExceptionOptions, type MushiColorPalette, type MushiConfig, type MushiConsoleEntry, type MushiCooldownConfig, type MushiCrossAppReport, type MushiCustomCategory, type MushiDiagnosticsResult, type MushiDiscoverInventoryConfig, type MushiDiscoveryEventPayload, type MushiEnvironment, type MushiEventHandler, type MushiEventType, type MushiHallOfFameEntry, type MushiIdentityClaims, type MushiIntegrationsConfig, type MushiInternalRequestKind, type MushiLeaderboardEntry, type MushiNetworkEntry, type MushiOfflineConfig, type MushiOnDeviceClassifier, type MushiOnDeviceClassifierInput, type MushiOnDeviceClassifierResult, type MushiPageContext, type MushiPerformanceMetrics, type MushiPreFilterConfig, type MushiPreset, type MushiPrivacyConfig, type MushiProactiveConfig, type MushiRegion, type MushiReport, type MushiReportBuilder, type MushiReportCategory, type MushiReportStatus, type MushiReporterComment, type MushiReporterReport, type MushiReputationResult, type MushiRewardsConfig, type MushiRuntimeSdkConfig, type MushiSDKInstance, type MushiSdkVersionInfo, type MushiSelectedElement, type MushiSentryConfig, type MushiSentryContext, type MushiSessionEventPayload, type MushiTesterReputation, type MushiThemeMode, type MushiTierResult, type MushiTimelineEntry, type MushiTimelineKind, type MushiTokenSnapshot, type MushiTracePropagationConfig, type MushiUrlMatcher, type MushiWidgetAnchor, type MushiWidgetConfig, type NormalisedException, type OfflineQueue, type PayloadGuardResult, type PiiScrubberConfig, type PreFilterResult, type ProjectFaviconSource, REGION_ENDPOINTS, type RateLimiter, type RateLimiterConfig, type ResolvedEnvConfig, type SessionTrackerOptions, buildIdentityClaims, buildSdkIngestHeaders, captureEnvironment, checkReportPayloadSize, createApiClient, createBreadcrumbBuffer, createLogger, createOfflineQueue, createPiiScrubber, createPreFilter, createRateLimiter, destroySessionTracker, diagnoseEnvConfig, estimateJsonBytes, expandPreset, faviconUrlCandidates, formatBytes, getDeviceFingerprintHash, getReporterToken, getSessionId, githubRepoDomainHint, hmacSha256Hex, initSessionTracker, isLikelyGenericFavicon, isUntrustedFaviconUrl, mushiPalette, mushiTokens, newUuid, noopLogger, normaliseThrown, originToDomain, parseIdentityToken, projectFaviconUrlCandidates, projectInitials, projectInitialsThemeIndex, readPageFaviconHref, resolveEnvConfig, resolveProjectDomain, resolveProjectFaviconDomains, resolveRegionEndpoint, resolveWidgetAccent, safeWidgetHex, scrubPii, sha256Hex, trackPageView, updateSessionIdentity, validateConfig };

package/dist/index.js

@@ -358,6 +358,17 @@ function createApiClient(options) {
       );
     },
     // ─── Rewards program (P1) ──────────────────────────────────
+    /** POST /v1/sdk/session — lightweight session lifecycle events.
+     *  Best-effort (1 retry, no offline queue) — mirrors postDiscoveryEvent. */
+    async postSessionEvent(payload) {
+      return request(
+        "POST",
+        "/v1/sdk/session",
+        payload,
+        1,
+        "discovery"
+      );
+    },
     async submitActivity(userId, events, opts) {
       return request(
         "POST",
@@ -1167,12 +1178,12 @@ function createOfflineQueue(config = {}) {
     const n = row.attempts;
     return typeof n === "number" && Number.isFinite(n) ? n : 0;
   }
-  function isExpired(row, now) {
+  function isExpired(row, now2) {
     const queuedAt = row.queuedAt;
     if (!queuedAt) return false;
     const ts = Date.parse(queuedAt);
     if (Number.isNaN(ts)) return false;
-    return now - ts > MAX_QUEUE_AGE_MS;
+    return now2 - ts > MAX_QUEUE_AGE_MS;
   }
   function detectBackend() {
     if (backendType) return backendType;
@@ -1351,10 +1362,10 @@ function createOfflineQueue(config = {}) {
     } else {
       rows = lsRead();
     }
-    const now = Date.now();
+    const now2 = Date.now();
     const fresh = [];
     for (const row of rows) {
-      if (isExpired(row, now)) {
+      if (isExpired(row, now2)) {
         const rowId = row.id;
         await removeRow(backend, rowId);
         queueLog.debug("Offline queue: evicting stale report", { id: rowId });
@@ -1819,6 +1830,111 @@ function randomSuffix() {
   return n.toString(36).padStart(6, "0").slice(0, 6);
 }
 
+// src/session-tracker.ts
+var HEARTBEAT_INTERVAL_MS = 6e4;
+var _client = null;
+var _sdkVersion;
+var _userIdHash = null;
+var _reporterTokenHash = null;
+var _pageViewCount = 0;
+var _heartbeatTimer = null;
+var _initialized = false;
+function now() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function currentRoute() {
+  if (typeof window === "undefined") return "";
+  return window.location.pathname + window.location.search;
+}
+function userAgent() {
+  if (typeof navigator === "undefined") return null;
+  return navigator.userAgent ?? null;
+}
+function buildPayload(kind, extra) {
+  return {
+    kind,
+    session_id: getSessionId(),
+    ts: now(),
+    page_view_count: _pageViewCount,
+    reporter_token_hash: _reporterTokenHash,
+    user_id_hash: _userIdHash,
+    user_agent: userAgent(),
+    sdk_version: _sdkVersion,
+    ...extra
+  };
+}
+function send(payload) {
+  if (!_client) return;
+  _client.postSessionEvent(payload).catch(() => {
+  });
+}
+function initSessionTracker(opts) {
+  if (_initialized || typeof window === "undefined") return;
+  _initialized = true;
+  _client = opts.client;
+  _sdkVersion = opts.sdkVersion;
+  _reporterTokenHash = opts.reporterTokenHash ?? null;
+  _userIdHash = opts.userIdHash ?? null;
+  const entryRoute = currentRoute();
+  _pageViewCount = 1;
+  send(buildPayload("session_start", {
+    route: entryRoute,
+    referrer: typeof document !== "undefined" ? document.referrer ?? null : null
+  }));
+  _heartbeatTimer = setInterval(() => {
+    send(buildPayload("session_heartbeat", { route: currentRoute() }));
+  }, HEARTBEAT_INTERVAL_MS);
+  const onHide = () => {
+    if (typeof document !== "undefined" && document.visibilityState === "hidden") {
+      send(buildPayload("session_end", { route: currentRoute() }));
+    }
+  };
+  if (typeof document !== "undefined") {
+    document.addEventListener("visibilitychange", onHide, { passive: true });
+  }
+  if (typeof window !== "undefined") {
+    window.addEventListener("pagehide", () => {
+      send(buildPayload("session_end", { route: currentRoute() }));
+    }, { passive: true });
+  }
+  patchHistoryForPageViews();
+}
+function trackPageView(route) {
+  if (!_initialized || !_client) return;
+  _pageViewCount += 1;
+  send(buildPayload("page_view", { route: route ?? currentRoute() }));
+}
+function updateSessionIdentity(userIdHash) {
+  _userIdHash = userIdHash;
+}
+function destroySessionTracker() {
+  if (_heartbeatTimer != null) {
+    clearInterval(_heartbeatTimer);
+    _heartbeatTimer = null;
+  }
+  _initialized = false;
+  _client = null;
+}
+var _historyPatched = false;
+function patchHistoryForPageViews() {
+  if (_historyPatched || typeof history === "undefined") return;
+  _historyPatched = true;
+  const wrap = (original) => function(...args) {
+    const result = original.apply(this, args);
+    if (original === history.pushState) {
+      _pageViewCount += 1;
+      send(buildPayload("page_view", { route: currentRoute() }));
+    }
+    return result;
+  };
+  history.pushState = wrap(history.pushState);
+  history.replaceState = wrap(history.replaceState);
+  window.addEventListener("popstate", () => {
+    _pageViewCount += 1;
+    send(buildPayload("page_view", { route: currentRoute() }));
+  }, { passive: true });
+}
+
 // src/rate-limiter.ts
 var DEFAULT_MAX_BURST = 10;
 var DEFAULT_REFILL_RATE = 1;
@@ -1832,12 +1948,12 @@ function createRateLimiter(config = {}) {
   let tokens = maxBurst;
   let lastRefill = Date.now();
   function refill() {
-    const now = Date.now();
-    const elapsed = now - lastRefill;
+    const now2 = Date.now();
+    const elapsed = now2 - lastRefill;
     const refills = Math.floor(elapsed / refillIntervalMs);
     if (refills > 0) {
       tokens = Math.min(maxBurst, tokens + refills * refillRate);
-      lastRefill = now;
+      lastRefill = now2;
     }
   }
   function tryConsume() {
@@ -2151,15 +2267,15 @@ function mushiTokens(mode) {
 // src/identity.ts
 var MUSHI_IDENTITY_TOKEN_PREFIX = "mushi.identity";
 function buildIdentityClaims(input) {
-  const now = Math.floor(Date.now() / 1e3);
+  const now2 = Math.floor(Date.now() / 1e3);
   const ttl = input.ttlSeconds && input.ttlSeconds > 0 ? Math.min(input.ttlSeconds, 3600) : 600;
   return {
     projectId: input.projectId,
     sub: input.userId,
     ...input.email ? { email: input.email } : {},
     ...input.name ? { name: input.name } : {},
-    iat: now,
-    exp: now + ttl
+    iat: now2,
+    exp: now2 + ttl
   };
 }
 function base64UrlDecode(segment) {
@@ -2198,12 +2314,12 @@ var MULTI_TENANT_PARENT_HOSTS = /* @__PURE__ */ new Set(["kensaur.us", "www.kens
 var SLUG_DOMAIN_HINTS = {
   "glot-it": "glot.it",
   glotit: "glot.it",
-  "solo-boss-cloud": "sbc-front.vercel.app",
+  "solo-boss-cloud": "solo-boss.kensaur.us",
   "mushi-mushi": "kensaur.us"
 };
 var SLUG_ICON_URL_HINTS = {
   "mushi-mushi": "https://kensaur.us/mushi-mushi/admin/favicon.svg",
-  "solo-boss-cloud": "https://sbc-front.vercel.app/favicon.svg",
+  "solo-boss-cloud": "https://solo-boss.kensaur.us/favicon.svg",
   "glot-it": "https://kensaur.us/glot-it/apple-touch-icon.png",
   glotit: "https://kensaur.us/glot-it/apple-touch-icon.png"
 };
@@ -2377,6 +2493,6 @@ function isSafeFaviconHref(href) {
   }
 }
 
-export { DEFAULT_API_ENDPOINT, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, MAX_REPORT_PAYLOAD_BYTES, MAX_SCREENSHOT_DATA_URL_BYTES, MUSHI_ACCENT_SHADOW, MUSHI_BANNER_BRAND_BORDER, MUSHI_BANNER_NEON, MUSHI_COLORS_DARK, MUSHI_COLORS_LIGHT, MUSHI_COPY, MUSHI_GEOMETRY, MUSHI_IDENTITY_TOKEN_PREFIX, MUSHI_INTERNAL_HEADER, MUSHI_INTERNAL_INIT_MARKER, MUSHI_INVERSE, MUSHI_MOTION, MUSHI_ON_ACCENT, MUSHI_PROJECT_HEADER, MUSHI_RADIUS, MUSHI_REPORTER_STATUS, MUSHI_SDK_PACKAGE_HEADER, MUSHI_SDK_VERSION_HEADER, MUSHI_SPACING, MUSHI_TIER_COLORS, MUSHI_TYPE, MUSHI_USER_TOKEN_HEADER, MUSHI_Z, REGION_ENDPOINTS, buildIdentityClaims, buildSdkIngestHeaders, captureEnvironment, checkReportPayloadSize, createApiClient, createBreadcrumbBuffer, createLogger, createOfflineQueue, createPiiScrubber, createPreFilter, createRateLimiter, diagnoseEnvConfig, estimateJsonBytes, expandPreset, faviconUrlCandidates, formatBytes, getDeviceFingerprintHash, getReporterToken, getSessionId, githubRepoDomainHint, hmacSha256Hex, isLikelyGenericFavicon, isUntrustedFaviconUrl, mushiPalette, mushiTokens, newUuid, noopLogger, normaliseThrown, originToDomain, parseIdentityToken, projectFaviconUrlCandidates, projectInitials, projectInitialsThemeIndex, readPageFaviconHref, resolveEnvConfig, resolveProjectDomain, resolveProjectFaviconDomains, resolveRegionEndpoint, resolveWidgetAccent, safeWidgetHex, scrubPii, sha256Hex, validateConfig };
+export { DEFAULT_API_ENDPOINT, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, MAX_REPORT_PAYLOAD_BYTES, MAX_SCREENSHOT_DATA_URL_BYTES, MUSHI_ACCENT_SHADOW, MUSHI_BANNER_BRAND_BORDER, MUSHI_BANNER_NEON, MUSHI_COLORS_DARK, MUSHI_COLORS_LIGHT, MUSHI_COPY, MUSHI_GEOMETRY, MUSHI_IDENTITY_TOKEN_PREFIX, MUSHI_INTERNAL_HEADER, MUSHI_INTERNAL_INIT_MARKER, MUSHI_INVERSE, MUSHI_MOTION, MUSHI_ON_ACCENT, MUSHI_PROJECT_HEADER, MUSHI_RADIUS, MUSHI_REPORTER_STATUS, MUSHI_SDK_PACKAGE_HEADER, MUSHI_SDK_VERSION_HEADER, MUSHI_SPACING, MUSHI_TIER_COLORS, MUSHI_TYPE, MUSHI_USER_TOKEN_HEADER, MUSHI_Z, REGION_ENDPOINTS, buildIdentityClaims, buildSdkIngestHeaders, captureEnvironment, checkReportPayloadSize, createApiClient, createBreadcrumbBuffer, createLogger, createOfflineQueue, createPiiScrubber, createPreFilter, createRateLimiter, destroySessionTracker, diagnoseEnvConfig, estimateJsonBytes, expandPreset, faviconUrlCandidates, formatBytes, getDeviceFingerprintHash, getReporterToken, getSessionId, githubRepoDomainHint, hmacSha256Hex, initSessionTracker, isLikelyGenericFavicon, isUntrustedFaviconUrl, mushiPalette, mushiTokens, newUuid, noopLogger, normaliseThrown, originToDomain, parseIdentityToken, projectFaviconUrlCandidates, projectInitials, projectInitialsThemeIndex, readPageFaviconHref, resolveEnvConfig, resolveProjectDomain, resolveProjectFaviconDomains, resolveRegionEndpoint, resolveWidgetAccent, safeWidgetHex, scrubPii, sha256Hex, trackPageView, updateSessionIdentity, validateConfig };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map