@pl4yzonellc/empire-analytics 0.0.2

package/dist/types-Bzaq1v4t.d.ts

@@ -0,0 +1,507 @@
+/**
+ * Error model.
+ *
+ * Every error the library surfaces is an {@link AnalyticsError} carrying a stable
+ * machine-readable `code`. Provider implementation details are never leaked through
+ * the `message`; the originating error (if any) is attached as `cause` for opt-in
+ * inspection by `config.onError`.
+ */
+type AnalyticsErrorCode = 'config_invalid' | 'initialization_failed' | 'provider_unavailable' | 'script_load_failed' | 'track_failed' | 'pageview_failed' | 'destroy_failed' | 'privacy_violation' | 'unknown';
+interface AnalyticsErrorOptions {
+    code?: AnalyticsErrorCode;
+    cause?: unknown;
+}
+declare class AnalyticsError extends Error {
+    readonly code: AnalyticsErrorCode;
+    readonly cause?: unknown;
+    constructor(message: string, options?: AnalyticsErrorOptions);
+}
+/** Thrown synchronously from `initialize()` when the supplied config is invalid. */
+declare class AnalyticsConfigError extends AnalyticsError {
+    constructor(message: string, options?: Omit<AnalyticsErrorOptions, 'code'>);
+}
+/**
+ * Normalize an unknown thrown value into an {@link AnalyticsError} with a generic,
+ * provider-neutral message. Existing `AnalyticsError`s pass through unchanged.
+ */
+declare function toAnalyticsError(value: unknown, code: AnalyticsErrorCode): AnalyticsError;
+
+/** How the sanitizer reacts to a prohibited key. */
+type PrivacyViolationMode = 'strip' | 'warn' | 'throw';
+/** How the sanitizer reacts to a personally-identifiable key. */
+type PiiMode = 'allow' | 'strip' | 'warn' | 'throw';
+/**
+ * Application-facing privacy configuration. Everything is optional; sensible,
+ * environment-aware defaults are applied by `resolveConfig`.
+ */
+interface PrivacyConfig {
+    /**
+     * Handling for always-blocked sensitive keys (passwords, tokens, card data…).
+     * Default: `throw` when `debug` is on, `warn` on staging/test, `strip` in production.
+     * `throw` is always downgraded to `strip` in the `production` environment so
+     * analytics can never crash a production app.
+     */
+    onSensitive?: PrivacyViolationMode;
+    /**
+     * Handling for direct personal identifiers (email, phone, name, address…).
+     * Default: `warn`. `throw` is downgraded to `warn` in `production`.
+     */
+    onPii?: PiiMode;
+    /** Extra keys to always block (normalized substring match). */
+    blockKeys?: readonly string[];
+    /** Keys to force-allow even when a built-in rule matches (normalized exact match). */
+    allowKeys?: readonly string[];
+    /** Maximum object nesting depth to traverse. Default `4`. */
+    maxDepth?: number;
+    /** Maximum number of properties kept (across the whole tree). Default `64`. */
+    maxProperties?: number;
+    /** Strings longer than this are truncated. Default `1024`. */
+    maxStringLength?: number;
+    /** Arrays longer than this are truncated. Default `64`. */
+    maxArrayLength?: number;
+}
+/** Fully-resolved policy consumed by the sanitizer. */
+interface ResolvedPrivacyPolicy {
+    onSensitive: PrivacyViolationMode;
+    onPii: PiiMode;
+    blockKeys: readonly string[];
+    allowKeys: readonly string[];
+    maxDepth: number;
+    maxProperties: number;
+    maxStringLength: number;
+    maxArrayLength: number;
+}
+interface SanitizeResult {
+    /** Safe, adapter-ready property bag. */
+    value: Record<string, unknown>;
+    /** Key paths that were removed because they matched a privacy rule. */
+    blocked: string[];
+}
+
+interface Logger {
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+    /** Returns a logger with an extra scope segment appended to the prefix. */
+    child(scope: string): Logger;
+}
+
+/**
+ * Provider contract.
+ *
+ * The core client depends on *this interface only*. Everything Plausible-specific
+ * lives behind `PlausibleAdapter`.
+ *
+ * Refinements over the naive `initialize(config: unknown)` shape:
+ *   - provider config is injected through the constructor / factory and is
+ *     strongly typed per provider, so `unknown` never travels through the core
+ *   - `initialize()` may be sync or async; the core always awaits it
+ *   - adapters expose a stable `name` for diagnostics
+ *   - `track()` receives an already privacy-sanitized property bag
+ */
+interface AnalyticsAdapter {
+    /** Stable identifier, e.g. `'plausible'`. */
+    readonly name: string;
+    /** Prepare the provider (load scripts, wire globals). Awaited by the core. */
+    initialize(): Promise<void> | void;
+    /** Send a business event. `properties` is already sanitized. */
+    track(eventName: string, properties?: Record<string, unknown>): void;
+    /** Send an explicit page view. `path` is already sanitized when provided. */
+    pageView(path?: string): void;
+    /** Release resources: remove injected scripts, drop listeners, null out globals. */
+    destroy(): void;
+}
+/** Everything an adapter is handed at construction time. */
+interface AnalyticsAdapterContext {
+    logger: Logger;
+}
+/**
+ * Factory for a custom adapter, supplied via `{ provider: 'custom', adapter }`.
+ * This is the extension point for future first-class providers
+ * (`GoogleAnalyticsAdapter`, `PostHogAdapter`, …) without touching app code.
+ */
+type AnalyticsAdapterFactory = (context: AnalyticsAdapterContext) => AnalyticsAdapter;
+
+/**
+ * Optional Plausible script variants. The library composes the CDN filename
+ * (`script.manual.revenue.tagged-events.js`) from these flags.
+ * @see https://plausible.io/docs/script-extensions
+ */
+type PlausibleScriptExtension = 'manual' | 'hash' | 'outbound-links' | 'file-downloads' | 'tagged-events' | 'revenue' | 'pageview-props' | 'compat' | 'local';
+/**
+ * How the Plausible tracker runs in the browser:
+ *  - `'cdn'` — inject the hosted `<script data-domain>` from plausible.io (default)
+ *  - `'package'` — load the official `@plausible-analytics/tracker` npm module via a
+ *    lazy dynamic import (no remote `<script>`, pinned version, friendlier to CSP and
+ *    ad-blockers). The consuming app must install it: `pnpm add @plausible-analytics/tracker`.
+ */
+type PlausibleRuntimeMode = 'cdn' | 'package';
+/**
+ * Provider-specific configuration block. This is the *only* place Plausible
+ * terminology is allowed to surface in the public API.
+ */
+interface PlausibleProviderConfig {
+    /** The site domain registered in Plausible, e.g. `"example.com"`. Required. */
+    domain: string;
+    /**
+     * Runtime for the tracker. Default `'cdn'`.
+     * `'package'` uses `@plausible-analytics/tracker` (an **optional peer dependency**,
+     * loaded via dynamic `import()`); `scriptUrl`, `injectScript` and `taggedEvents`
+     * are ignored in that mode.
+     */
+    mode?: PlausibleRuntimeMode;
+    /**
+     * Full URL of the tracking script (`mode: 'cdn'` only). Overrides the composed
+     * CDN URL entirely. Use this for a self-hosted Plausible instance or a first-party proxy.
+     */
+    scriptUrl?: string;
+    /** Custom events API endpoint (`data-api`). Use with a first-party proxy. */
+    endpoint?: string;
+    /**
+     * Inject the browser script automatically. Default `true`.
+     * Set to `false` if the host page already includes the Plausible snippet.
+     */
+    injectScript?: boolean;
+    /**
+     * Let Plausible auto-track SPA navigations. Default `true`.
+     * When `false`, the `manual` script variant is used and page views only happen
+     * via explicit `analytics.pageView()` calls.
+     */
+    autoPageViews?: boolean;
+    /** Use the `hash` script variant for hash-based routing. Default `false`. */
+    hashRouting?: boolean;
+    /** Load the `outbound-links` script variant. Default `false`. */
+    outboundLinks?: boolean;
+    /** Load the `file-downloads` script variant. Default `false`. */
+    fileDownloads?: boolean;
+    /** Load the `tagged-events` script variant. Default `false`. */
+    taggedEvents?: boolean;
+    /**
+     * Enable revenue tracking (`revenue` script variant). Default `true` — the SDK's
+     * revenue abstraction depends on it. Individual goals must still be marked as
+     * revenue goals in the Plausible dashboard.
+     */
+    revenue?: boolean;
+    /** Load the `local` script variant so events fire on `localhost`. Default `false`. */
+    trackLocalhost?: boolean;
+}
+interface ResolvedPlausibleConfig {
+    domain: string;
+    mode: PlausibleRuntimeMode;
+    scriptUrl?: string;
+    endpoint?: string;
+    injectScript: boolean;
+    autoPageViews: boolean;
+    hashRouting: boolean;
+    outboundLinks: boolean;
+    fileDownloads: boolean;
+    taggedEvents: boolean;
+    revenue: boolean;
+    trackLocalhost: boolean;
+}
+
+interface ConsoleProviderConfig {
+    /** Where to write. Defaults to the global `console`. */
+    sink?: Pick<Console, 'log' | 'info' | 'group' | 'groupEnd'>;
+    /** Prefix for every line. Default `"[Analytics:console]"`. */
+    prefix?: string;
+}
+interface ResolvedConsoleConfig {
+    sink: Pick<Console, 'log' | 'info' | 'group' | 'groupEnd'>;
+    prefix: string;
+}
+
+/**
+ * Typed event system
+ * ==================
+ *
+ * The library deliberately does *not* recommend `track(event: string)`. Instead it
+ * ships a shared catalog (`BaseAnalyticsEventMap`) and lets each application extend
+ * an open registry interface (`AnalyticsEventMap`) via TypeScript module augmentation:
+ *
+ * ```ts
+ * // app/src/analytics-events.ts
+ * declare module '@pl4yzonellc/empire-analytics' {
+ *   interface AnalyticsEventMap {
+ *     quote_requested: { service: string; budgetRange?: string };
+ *   }
+ * }
+ * ```
+ *
+ * After that, `analytics.track('quote_requested', { service: 'roofing' })` is fully
+ * typed everywhere (hooks, `<Track>`, the global client) with zero generic plumbing,
+ * while unknown strings are rejected by the compiler.
+ */
+/** Common UI interactions shared by most applications. */
+interface CommonEventMap {
+    cta_clicked: {
+        id?: string;
+        label?: string;
+        location?: string;
+    };
+    outbound_link_clicked: {
+        url: string;
+        location?: string;
+    };
+    download_clicked: {
+        file: string;
+        location?: string;
+    };
+    /** `query` is free text — never put PII in it. */
+    search_performed: {
+        query?: string;
+        resultsCount?: number;
+    };
+}
+/** Lead-generation / contact funnels. */
+interface LeadGenerationEventMap {
+    contact_form_started: {
+        form: string;
+    };
+    contact_form_submitted: {
+        form: string;
+    };
+    phone_clicked: {
+        location?: string;
+    };
+    email_clicked: {
+        location?: string;
+    };
+    appointment_started: {
+        service?: string;
+    };
+    appointment_completed: {
+        service?: string;
+        durationMinutes?: number;
+    };
+}
+/** Authentication lifecycle. */
+interface AuthenticationEventMap {
+    login_started: {
+        method?: string;
+    };
+    login_completed: {
+        method?: string;
+    };
+    login_failed: {
+        method?: string;
+        reason?: string;
+    };
+    signup_started: {
+        method?: string;
+    };
+    signup_completed: {
+        method?: string;
+        plan?: string;
+    };
+}
+/** Ecommerce funnel. `purchase_completed` carries first-class revenue fields. */
+interface EcommerceEventMap {
+    product_viewed: {
+        productId: string;
+        name?: string;
+        price?: number;
+        currency?: string;
+        category?: string;
+    };
+    add_to_cart: {
+        productId: string;
+        quantity?: number;
+        price?: number;
+        currency?: string;
+    };
+    remove_from_cart: {
+        productId: string;
+        quantity?: number;
+    };
+    checkout_started: {
+        cartValue?: number;
+        itemCount?: number;
+        currency?: string;
+    };
+    checkout_completed: {
+        cartValue?: number;
+        itemCount?: number;
+        currency?: string;
+    };
+    purchase_completed: {
+        revenue: number;
+        currency: string;
+        orderId?: string;
+        itemCount?: number;
+    };
+}
+/** Content engagement. */
+interface EngagementEventMap {
+    video_started: {
+        id?: string;
+        title?: string;
+    };
+    video_completed: {
+        id?: string;
+        title?: string;
+        durationSeconds?: number;
+    };
+    document_downloaded: {
+        file: string;
+        category?: string;
+    };
+    social_link_clicked: {
+        network: string;
+        location?: string;
+    };
+}
+/**
+ * The standardized, framework-agnostic event catalog. Applications should reuse
+ * these names rather than inventing near-duplicates.
+ */
+interface BaseAnalyticsEventMap extends CommonEventMap, LeadGenerationEventMap, AuthenticationEventMap, EcommerceEventMap, EngagementEventMap {
+}
+/**
+ * Open registry. Augment this interface from application code to add strongly
+ * typed application-specific events. It extends {@link BaseAnalyticsEventMap} so
+ * the standard catalog is always available.
+ */
+interface AnalyticsEventMap extends BaseAnalyticsEventMap {
+}
+/** Every known event name (standard catalog + application augmentations). */
+type AnalyticsEventName = Extract<keyof AnalyticsEventMap, string>;
+/** The typed property model for a given event. */
+type AnalyticsEventProperties<K extends AnalyticsEventName> = AnalyticsEventMap[K];
+type HasRequiredKeys<T> = {
+    [K in keyof T]-?: undefined extends T[K] ? never : K;
+}[keyof T] extends never ? false : true;
+/**
+ * The `track()` argument tuple for an event. Events with at least one required
+ * property force a `properties` argument; events with only optional properties
+ * (or none) make it optional.
+ */
+type TrackArgs<K extends AnalyticsEventName> = HasRequiredKeys<AnalyticsEventProperties<K>> extends true ? [properties: AnalyticsEventProperties<K>] : [properties?: AnalyticsEventProperties<K>];
+
+type AnalyticsEnvironment = 'development' | 'test' | 'staging' | 'production';
+type AnalyticsProviderName = 'plausible' | 'console' | 'custom';
+type AnalyticsErrorHandler = (error: AnalyticsError) => void;
+/** Observability payload passed to `config.onEvent` for every attempted send. */
+interface AnalyticsEventInfo {
+    type: 'event' | 'pageview';
+    name: string;
+    provider: AnalyticsProviderName;
+    environment: AnalyticsEnvironment;
+    enabled: boolean;
+    /** `false` when analytics is disabled or the provider was unavailable. */
+    delivered: boolean;
+    /** Human-readable explanation when `delivered` is `false`. */
+    reason?: string;
+    /** Sanitized properties actually forwarded (never contains blocked keys). */
+    properties?: Record<string, unknown>;
+    /** Key paths removed by the privacy layer. */
+    blockedKeys?: string[];
+}
+interface AnalyticsConfigBase {
+    /**
+     * Current environment. Drives the enabled/disabled default:
+     * `development` → off, `test` → off, `staging` → off (opt-in), `production` → on.
+     */
+    environment: AnalyticsEnvironment;
+    /**
+     * Explicit master switch. When set it always wins over the environment default —
+     * e.g. `enabled: true` in `development`, or `enabled: false` in `production`.
+     */
+    enabled?: boolean;
+    /** Verbose logging + stricter privacy handling. Default: `true` in `development`. */
+    debug?: boolean;
+    /**
+     * Multi-tenant metadata. Treated as configuration only — it is **not** sent as a
+     * property unless `includeTenantKey` is `true`.
+     */
+    tenantKey?: string;
+    /** Send `tenantKey` as a property on every event. Default `false`. */
+    includeTenantKey?: boolean;
+    /** Property name used when `includeTenantKey` is `true`. Default `"tenant"`. */
+    tenantPropertyName?: string;
+    /** Properties merged into every event (lowest precedence). */
+    defaultProperties?: Record<string, unknown>;
+    /** Privacy / sanitization overrides. */
+    privacy?: PrivacyConfig;
+    /** Observability hook for internal errors. Never receives provider internals. */
+    onError?: AnalyticsErrorHandler;
+    /** Observability hook fired for every `track`/`pageView` attempt. */
+    onEvent?: (info: AnalyticsEventInfo) => void;
+}
+interface PlausibleAnalyticsConfig extends AnalyticsConfigBase {
+    provider: 'plausible';
+    plausible: PlausibleProviderConfig;
+}
+interface ConsoleAnalyticsConfig extends AnalyticsConfigBase {
+    provider: 'console';
+    console?: ConsoleProviderConfig;
+}
+interface CustomAnalyticsConfig extends AnalyticsConfigBase {
+    provider: 'custom';
+    /** Factory for a bespoke adapter — the forward-compatibility hook for new providers. */
+    adapter: AnalyticsAdapterFactory;
+}
+/**
+ * Strongly typed, provider-agnostic configuration. A discriminated union on
+ * `provider` so the compiler requires the matching provider block.
+ */
+type AnalyticsConfig = PlausibleAnalyticsConfig | ConsoleAnalyticsConfig | CustomAnalyticsConfig;
+/** Config after defaults, validation and environment resolution have been applied. */
+interface ResolvedAnalyticsConfig {
+    provider: AnalyticsProviderName;
+    environment: AnalyticsEnvironment;
+    enabled: boolean;
+    disabledReason?: string;
+    debug: boolean;
+    tenantKey?: string;
+    includeTenantKey: boolean;
+    tenantPropertyName: string;
+    defaultProperties: Record<string, unknown>;
+    privacy: ResolvedPrivacyPolicy;
+    onError?: AnalyticsErrorHandler;
+    onEvent?: (info: AnalyticsEventInfo) => void;
+    plausible?: ResolvedPlausibleConfig;
+    console?: ResolvedConsoleConfig;
+    adapter?: AnalyticsAdapterFactory;
+}
+/** Small, safe snapshot of client state (no internal config leaks). */
+interface AnalyticsClientState {
+    initialized: boolean;
+    enabled: boolean;
+    environment: AnalyticsEnvironment | null;
+    provider: AnalyticsProviderName | null;
+    debug: boolean;
+}
+/**
+ * The framework-independent analytics client. The core never imports React.
+ */
+interface AnalyticsClient {
+    /**
+     * Configure and start the client. Idempotent: calling again with an equivalent
+     * config is a no-op; calling with a different config reconfigures in place.
+     */
+    initialize(config: AnalyticsConfig): Promise<void>;
+    /** Send a strongly typed business event (revenue fields included where relevant). */
+    track<K extends AnalyticsEventName>(event: K, ...args: TrackArgs<K>): void;
+    /**
+     * Send an explicit page view. Normal SPA navigation is handled by the provider
+     * itself — use this only for special cases (virtual pages, wizards, modals).
+     */
+    pageView(path?: string): void;
+    /** `true` when analytics is currently sending events. */
+    isEnabled(): boolean;
+    /** `true` once `initialize()` has been called (and not since `destroy()`d). */
+    isInitialized(): boolean;
+    /**
+     * Toggle sending at runtime (e.g. after a consent decision). Enabling a client
+     * that was initialized while disabled will lazily create + start the provider.
+     */
+    setEnabled(enabled: boolean): void;
+    /** Safe state snapshot for debugging / dev tooling. */
+    getState(): AnalyticsClientState;
+    /** Tear down the provider and reset to the pre-`initialize()` state. */
+    destroy(): void;
+}
+
+export { type AnalyticsClient as A, type BaseAnalyticsEventMap as B, type CommonEventMap as C, type PrivacyConfig as D, type EcommerceEventMap as E, type PrivacyViolationMode as F, type ResolvedAnalyticsConfig as G, toAnalyticsError as H, type Logger as L, type PiiMode as P, type ResolvedPrivacyPolicy as R, type SanitizeResult as S, type TrackArgs as T, AnalyticsError as a, type AnalyticsEnvironment as b, type AnalyticsConfig as c, type AnalyticsEventName as d, type AnalyticsAdapter as e, type AnalyticsAdapterContext as f, type AnalyticsAdapterFactory as g, type AnalyticsClientState as h, type AnalyticsConfigBase as i, AnalyticsConfigError as j, type AnalyticsErrorCode as k, type AnalyticsErrorHandler as l, type AnalyticsEventInfo as m, type AnalyticsEventMap as n, type AnalyticsEventProperties as o, type AnalyticsProviderName as p, type AuthenticationEventMap as q, type ConsoleAnalyticsConfig as r, type ConsoleProviderConfig as s, type CustomAnalyticsConfig as t, type EngagementEventMap as u, type LeadGenerationEventMap as v, type PlausibleAnalyticsConfig as w, type PlausibleProviderConfig as x, type PlausibleRuntimeMode as y, type PlausibleScriptExtension as z };

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@pl4yzonellc/empire-analytics",
+  "version": "0.0.2",
+  "description": "Provider-agnostic analytics SDK for React 19 applications. First provider: Plausible.",
+  "license": "MIT",
+  "author": "pl4yzonellc",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@plausible-analytics/tracker": "^0.4.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@plausible-analytics/tracker": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.18.0",
+    "@plausible-analytics/tracker": "^0.4.6",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
+    "@testing-library/user-event": "^14.5.2",
+    "@types/node": "^22.10.5",
+    "@types/react": "^19.0.7",
+    "@types/react-dom": "^19.0.3",
+    "@vitest/coverage-v8": "^3.0.5",
+    "eslint": "^9.18.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-react": "^7.37.4",
+    "eslint-plugin-react-hooks": "^5.1.0",
+    "jsdom": "^25.0.1",
+    "prettier": "^3.4.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.20.0",
+    "vitest": "^3.0.5"
+  },
+  "keywords": [
+    "analytics",
+    "plausible",
+    "react",
+    "sdk",
+    "provider-agnostic",
+    "typescript",
+    "privacy"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rimraf dist coverage",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md,yml,yaml}\"",
+    "format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,json,md,yml,yaml}\""
+  }
+}