@djangocfg/analytics 2.1.489 → 2.1.490

package/README.md

@@ -0,0 +1,46 @@
+# @djangocfg/analytics
+
+First-party product analytics for DjangoCFG. One client fans out pageviews and
+custom events to django-cfg and optional GA4 transports.
+
+## Product events
+
+Mount `AnalyticsProvider` once (Layouts `BaseApp` does this automatically),
+then use the typed React API:
+
+```tsx
+import { useAnalytics } from '@djangocfg/analytics'
+
+const { event } = useAnalytics()
+event('layouts.auth.step_viewed', { step: 'otp' })
+event('billing.checkout_started', { plan: 'pro' })
+```
+
+For browser integration code outside React, use the optional facade installed
+by the provider. It is the same client — not a second transport:
+
+```ts
+window.analytics?.event('billing.checkout_started', { plan: 'pro' })
+```
+
+Unknown product event names are accepted. Extend `AnalyticsEventMap` to make
+your product's names and properties type-safe everywhere:
+
+```ts
+declare module '@djangocfg/analytics' {
+  interface AnalyticsEventMap {
+    'billing.checkout_started': { plan: 'pro' | 'team' }
+  }
+}
+```
+
+Use stable event names as your analytics contract. Django goals and funnels are
+configured against those names; do not encode dynamic identifiers in names —
+put bounded, non-sensitive dimensions in `props` instead.
+
+## Identity and funnels
+
+Browser journeys are scoped to a host. A property can aggregate hosts, but it
+does not merge anonymous visitor identities across them. Server-confirmed auth
+events use the request-derived identity for their originating host, so an auth
+funnel on that host can join its UI and successful-login events safely.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/analytics",
-  "version": "2.1.489",
+  "version": "2.1.490",
   "description": "First-party analytics for django-cfg apps: one route listener, N transports (self-hosted + GA4). Pageviews, sessions, and authenticated-user attribution.",
   "keywords": [
     "django",
@@ -63,7 +63,7 @@
     }
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.489",
+    "@djangocfg/typescript-config": "^2.1.490",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",
     "next": "^15.5.9",

package/src/core/client.ts

@@ -14,6 +14,7 @@
  */
 
 import type { AnalyticsEventPayload, AnalyticsOptions, AnalyticsTransport } from './types'
+import type { AnalyticsEventName, AnalyticsEventProps } from '../events'
 
 export class AnalyticsClient {
   private transports: AnalyticsTransport[] = []
@@ -70,7 +71,10 @@ export class AnalyticsClient {
     this.fanOut((t) => t.pageview(payload))
   }
 
-  trackEvent(name: string, props: Record<string, unknown> = {}): void {
+  trackEvent<Name extends AnalyticsEventName>(
+    name: Name,
+    props: AnalyticsEventProps<Name> = {} as AnalyticsEventProps<Name>,
+  ): void {
     if (typeof window === 'undefined') return
 
     this.fanOut((t) =>

package/src/core/global.ts

@@ -0,0 +1,52 @@
+/**
+ * Imperative access to the one AnalyticsClient mounted by AnalyticsProvider.
+ *
+ * `window.analytics` is deliberately a thin optional facade, analogous to
+ * `window.dialog` but not a second event pipeline. React code uses
+ * `useAnalytics`; integration code without a React tree can use
+ * `getAnalytics()?.event(...)`.
+ */
+
+import type { AnalyticsEventName, AnalyticsEventProps } from '../events'
+import type { AnalyticsClient } from './client'
+
+export interface AnalyticsAPI {
+  event<Name extends AnalyticsEventName>(
+    name: Name,
+    props?: AnalyticsEventProps<Name>,
+  ): void
+  flush(): void
+}
+
+let activeApi: AnalyticsAPI | null = null
+
+export function getAnalytics(): AnalyticsAPI | null {
+  return activeApi
+}
+
+export function installAnalytics(client: AnalyticsClient): () => void {
+  const api: AnalyticsAPI = {
+    event: (name, props) => client.trackEvent(name, props),
+    flush: () => client.flush(),
+  }
+  activeApi = api
+
+  if (typeof window !== 'undefined') {
+    window.analytics = api
+  }
+
+  return () => {
+    if (activeApi !== api) return
+    activeApi = null
+    if (typeof window !== 'undefined' && window.analytics === api) {
+      delete window.analytics
+    }
+  }
+}
+
+declare global {
+  interface Window {
+    /** Installed only while an AnalyticsProvider is mounted. */
+    analytics?: AnalyticsAPI
+  }
+}

package/src/core/index.ts

@@ -6,6 +6,8 @@
  */
 
 export { AnalyticsClient } from './client'
+export { getAnalytics } from './global'
+export type { AnalyticsAPI } from './global'
 export type { AnalyticsEventPayload, AnalyticsOptions, AnalyticsTransport } from './types'
 
 /**

package/src/events.ts

@@ -1,8 +1,9 @@
 /**
- * Analytics Events Constants
+ * Product-event catalog.
  *
- * Predefined event names and categories for consistent tracking
- * across the entire application.
+ * This is the single TypeScript source of truth for framework event names and
+ * their properties. Products extend `AnalyticsEventMap` by declaration merging
+ * instead of maintaining a second enum, transport, or browser global.
  */
 
 /**
@@ -58,3 +59,52 @@ export const AnalyticsEvent = {
 
 export type AnalyticsCategoryType = typeof AnalyticsCategory[keyof typeof AnalyticsCategory];
 export type AnalyticsEventType = typeof AnalyticsEvent[keyof typeof AnalyticsEvent];
+
+export type AnalyticsPropertyValue = string | number | boolean | null;
+export type AnalyticsEventProperties = Record<string, AnalyticsPropertyValue>;
+
+/**
+ * Framework event names with their valid payloads.
+ *
+ * Apps can extend this interface:
+ *
+ * ```ts
+ * declare module '@djangocfg/analytics' {
+ *   interface AnalyticsEventMap {
+ *     'billing.checkout_started': { plan: 'pro' | 'team' }
+ *   }
+ * }
+ * ```
+ */
+export interface AnalyticsEventMap {
+  auth_otp_request: { method?: 'email' | 'phone' };
+  auth_login_success: { provider?: 'email' | 'github'; is_new_user?: boolean };
+  auth_otp_verify_fail: { reason?: string };
+  auth_session_expired: Record<string, never>;
+  auth_token_refresh: Record<string, never>;
+  auth_token_refresh_fail: { reason?: string };
+  auth_logout: Record<string, never>;
+  auth_oauth_start: { provider: 'github' };
+  auth_oauth_fail: { provider?: 'github'; reason?: string };
+  error_boundary: { boundary?: string };
+  error_api: { status?: number; operation?: string };
+  error_validation: { field?: string };
+  error_network: { operation?: string };
+  nav_admin_enter: Record<string, never>;
+  nav_dashboard_enter: Record<string, never>;
+  nav_page_view: Record<string, never>;
+  theme_change: { theme?: string };
+  sidebar_toggle: { open?: boolean };
+  mobile_menu_open: Record<string, never>;
+  user_profile_view: Record<string, never>;
+  user_profile_update: Record<string, never>;
+  'layouts.auth.step_viewed': { step: 'identifier' | 'otp' | '2fa' | '2fa-setup' | 'success' };
+}
+
+/** A catalog event is fully typed; arbitrary product events remain supported. */
+export type AnalyticsEventName = keyof AnalyticsEventMap | (string & {});
+
+export type AnalyticsEventProps<Name extends AnalyticsEventName> =
+  Name extends keyof AnalyticsEventMap
+    ? AnalyticsEventMap[Name]
+    : AnalyticsEventProperties;

package/src/index.ts

@@ -16,6 +16,8 @@
  */
 
 export { AnalyticsClient } from './core/client'
+export { getAnalytics } from './core/global'
+export type { AnalyticsAPI } from './core/global'
 export type {
   AnalyticsEventPayload,
   AnalyticsOptions,
@@ -34,4 +36,12 @@ export { PageviewTracker } from './next/PageviewTracker'
 export type { PageviewTrackerProps } from './next/PageviewTracker'
 
 export { AnalyticsCategory, AnalyticsEvent } from './events'
-export type { AnalyticsCategoryType, AnalyticsEventType } from './events'
+export type {
+  AnalyticsCategoryType,
+  AnalyticsEventMap,
+  AnalyticsEventName,
+  AnalyticsEventProps,
+  AnalyticsEventProperties,
+  AnalyticsEventType,
+  AnalyticsPropertyValue,
+} from './events'

package/src/react/context.tsx

@@ -8,7 +8,9 @@
 import { createContext, useContext, useEffect, useMemo, useRef, type ReactNode } from 'react'
 
 import { AnalyticsClient } from '../core/client'
+import { installAnalytics } from '../core/global'
 import type { AnalyticsOptions } from '../core/types'
+import type { AnalyticsEventName, AnalyticsEventProps } from '../events'
 
 const AnalyticsContext = createContext<AnalyticsClient | null>(null)
 
@@ -41,7 +43,11 @@ export function AnalyticsProvider({
 
   useEffect(() => {
     void client.init()
-    return () => client.destroy()
+    const uninstall = installAnalytics(client)
+    return () => {
+      uninstall()
+      client.destroy()
+    }
   }, [client])
 
   useEffect(() => {
@@ -63,7 +69,8 @@ export function useAnalytics() {
 
   return useMemo(
     () => ({
-      event: (name: string, props?: Record<string, unknown>) => client?.trackEvent(name, props),
+      event: <Name extends AnalyticsEventName>(name: Name, props?: AnalyticsEventProps<Name>) =>
+        client?.trackEvent(name, props),
       identify: (userId: string | null) => client?.identify(userId),
       flush: () => client?.flush(false),
       /** False when no AnalyticsProvider is mounted above this component. */