@pl4yzonellc/empire-analytics 0.0.2

package/README.md

@@ -0,0 +1,744 @@
+# `@pl4yzonellc/empire-analytics`
+
+A **provider-agnostic analytics SDK** for React 19 applications. It gives product
+teams one small, strongly typed API for tracking business events, custom
+properties and revenue — and keeps the analytics vendor an implementation detail.
+
+Plausible is the first provider. **Application code never imports Plausible APIs
+and never touches `window.plausible`.**
+
+- [What it does](#what-it-does)
+- [Architecture](#architecture)
+- [Installation](#installation)
+- [Basic React setup](#basic-react-setup)
+- [Non-React / global usage](#non-react--global-usage)
+- [Configuration](#configuration)
+- [Environment behavior](#environment-behavior)
+- [Built-in event catalog](#built-in-event-catalog)
+- [Application-specific events](#application-specific-events)
+- [Event properties](#event-properties)
+- [Revenue events](#revenue-events)
+- [Privacy protection](#privacy-protection)
+- [Debugging](#debugging)
+- [Explicit page views](#explicit-page-views)
+- [Multi-tenant configuration](#multi-tenant-configuration)
+- [Testing consuming applications](#testing-consuming-applications)
+- [How the Plausible adapter works](#how-the-plausible-adapter-works)
+- [Adding a future provider](#adding-a-future-provider)
+- [Package scripts](#package-scripts)
+
+---
+
+## What it does
+
+A React application that installs this package can:
+
+- initialize analytics once, near the app root
+- automatically load and configure the analytics provider
+- track **strongly typed** business events and custom properties
+- track revenue / conversion events through a first-class abstraction
+- optionally send explicit page views
+- use React hooks (`useAnalytics`, `useTrackEvent`) and an optional `<Track>` component
+- prevent sensitive data (passwords, tokens, card numbers, PII…) from being tracked
+- disable analytics per environment and turn on a debug mode
+- swap the analytics provider later without touching application code
+- run cleanly in multi-tenant apps
+- be tested without loading a real analytics vendor
+
+It deliberately does **not** do dashboard reporting, Stats-API querying, or
+anything that needs a secret API key. This package only _sends_ client-side
+analytics.
+
+## Architecture
+
+```text
+React application
+       │
+       ▼
+React bindings          src/react       <AnalyticsProvider>, useAnalytics, useTrackEvent, <Track>
+       │
+       ▼
+Analytics Core          src/core        AnalyticsClient — enabled state, config, debug, lifecycle
+       │
+       ├─ Event catalog  src/events      BaseAnalyticsEventMap + open AnalyticsEventMap registry
+       ├─ Privacy         src/privacy     key classification + property sanitization pipeline
+       │
+       ▼
+AnalyticsAdapter        src/providers   the only contract the core depends on
+       │
+       ▼
+PlausibleAdapter        src/providers/plausible   window.plausible, script injection, revenue mapping
+       │
+       ▼
+Plausible
+```
+
+Rules the codebase enforces (an ESLint rule fails the build otherwise):
+
+- the core never imports React
+- only `src/providers/plausible/**` may reference `window.plausible`
+- provider internals are not part of the default public API
+
+### Build tooling
+
+| Concern         | Choice                                                                            |
+| --------------- | --------------------------------------------------------------------------------- |
+| Library bundle  | **tsup** (esbuild) → ESM + per-entry `.d.ts`, tree-shakeable, `sideEffects:false` |
+| Tests           | **Vitest** + **React Testing Library** (jsdom)                                    |
+| Lint / format   | **ESLint 9** (flat config, type-checked) + **Prettier**                           |
+| Example app     | **Vite 6**                                                                        |
+| Package manager | **pnpm**                                                                          |
+
+The package ships **ESM only** — the target consumers are React 19 + Vite apps
+and other modern ESM projects.
+
+## Installation
+
+```bash
+pnpm add @pl4yzonellc/empire-analytics
+# react + react-dom 19 are peer dependencies
+
+# only if you set plausible.mode: 'package' (optional peer dependency):
+pnpm add @plausible-analytics/tracker
+```
+
+Published to the public npm registry (`--access public`).
+To consume it from a private/company registry instead, point your `.npmrc` at one:
+
+```ini
+@pl4yzonellc:registry=https://npm.your-company.example/
+//npm.your-company.example/:_authToken=${NPM_TOKEN}
+```
+
+## Basic React setup
+
+```tsx
+// main.tsx
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { AnalyticsProvider } from '@pl4yzonellc/empire-analytics';
+import { App } from './App';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <AnalyticsProvider
+      config={{
+        provider: 'plausible',
+        environment: import.meta.env.MODE as 'development' | 'test' | 'staging' | 'production',
+        plausible: { domain: 'example.com' },
+      }}
+    >
+      <App />
+    </AnalyticsProvider>
+  </StrictMode>,
+);
+```
+
+Inside any component:
+
+```tsx
+import { useAnalytics } from '@pl4yzonellc/empire-analytics';
+
+function ContactForm() {
+  const analytics = useAnalytics();
+
+  return (
+    <form
+      onSubmit={() => {
+        analytics.track('contact_form_submitted', { form: 'main-contact' });
+      }}
+    >
+      {/* … */}
+    </form>
+  );
+}
+```
+
+`useTrackEvent()` returns a stable, typed `track` function that is convenient in
+dependency arrays:
+
+```tsx
+import { useEffect } from 'react';
+import { useTrackEvent } from '@pl4yzonellc/empire-analytics';
+
+function PricingPage() {
+  const track = useTrackEvent();
+  useEffect(() => track('product_viewed', { productId: 'pro-plan' }), [track]);
+  return null;
+}
+```
+
+The `<AnalyticsProvider>`:
+
+- initializes analytics on mount and destroys it on unmount
+- re-initializes only when a **meaningful** config field changes (changing an
+  `onError`/`onEvent` callback identity does **not** re-initialize)
+- is **StrictMode-safe** — initialization is idempotent and a stale double-invoke
+  cannot resurrect a destroyed client
+- contains zero Plausible-specific behavior
+
+Place it once, near the root.
+
+## Non-React / global usage
+
+The same client is available without React. It is safe to import anywhere — no
+script is injected at import time.
+
+```ts
+import { analytics } from '@pl4yzonellc/empire-analytics';
+
+// during app startup, before any global usage:
+await analytics.initialize({
+  provider: 'plausible',
+  environment: 'production',
+  plausible: { domain: 'example.com' },
+});
+
+// anywhere else, e.g. a checkout service module:
+analytics.track('checkout_started', { cartValue: 125, itemCount: 3 });
+```
+
+By default `<AnalyticsProvider>` initializes **this same shared `analytics`
+instance**, so a React app that renders the provider also configures the global
+client. Pass `client={createAnalyticsClient()}` to the provider if you need an
+isolated instance instead.
+
+For fully independent clients:
+
+```ts
+import { createAnalyticsClient } from '@pl4yzonellc/empire-analytics';
+
+const analytics = createAnalyticsClient();
+```
+
+## Configuration
+
+```ts
+interface AnalyticsConfig {
+  provider: 'plausible' | 'console' | 'custom';
+  environment: 'development' | 'test' | 'staging' | 'production';
+
+  enabled?: boolean; // explicit master switch — always wins over the env default
+  debug?: boolean; // verbose logging + stricter privacy; default: true in development
+
+  tenantKey?: string; // multi-tenant metadata; NOT sent unless includeTenantKey
+  includeTenantKey?: boolean; // default false
+  tenantPropertyName?: string; // default 'tenant'
+
+  defaultProperties?: Record<string, unknown>; // merged into every event (lowest precedence)
+
+  privacy?: {
+    onSensitive?: 'strip' | 'warn' | 'throw'; // default: throw in dev, warn on staging/test, strip in prod
+    onPii?: 'allow' | 'strip' | 'warn' | 'throw'; // default: warn
+    blockKeys?: string[]; // extra always-blocked keys (substring match)
+    allowKeys?: string[]; // force-allow keys a built-in rule would block
+    maxDepth?: number; // default 4
+    maxProperties?: number; // default 64
+    maxStringLength?: number; // default 1024
+    maxArrayLength?: number; // default 64
+  };
+
+  onError?: (error: AnalyticsError) => void; // observability; never receives provider internals
+  onEvent?: (info: AnalyticsEventInfo) => void; // observability; fires for every track/pageView attempt
+
+  // provider block — the discriminated union requires the one matching `provider`
+  plausible?: {
+    domain: string; // required for provider: 'plausible'
+    mode?: 'cdn' | 'package'; // default 'cdn' (hosted script); 'package' = @plausible-analytics/tracker
+    scriptUrl?: string; // 'cdn' mode: self-hosted / first-party proxy
+    endpoint?: string; // custom events API
+    injectScript?: boolean; // 'cdn' mode: default true; false if the host page already includes the snippet
+    autoPageViews?: boolean; // default true; false = manual page views only
+    hashRouting?: boolean;
+    outboundLinks?: boolean;
+    fileDownloads?: boolean;
+    taggedEvents?: boolean;
+    revenue?: boolean; // default true
+    trackLocalhost?: boolean;
+  };
+  console?: { prefix?: string; sink?: Pick<Console, 'log' | 'info' | 'group' | 'groupEnd'> };
+  adapter?: (context: { logger: Logger }) => AnalyticsAdapter; // for provider: 'custom'
+}
+```
+
+Configuration can come from **anywhere** — a runtime config service, a JSON file
+served per tenant, or Vite env vars. Nothing in this package assumes
+`import.meta.env`.
+
+```jsonc
+// e.g. GET /config → consumed by your app and passed to <AnalyticsProvider>
+{
+  "analytics": {
+    "enabled": true,
+    "provider": "plausible",
+    "domain": "client-a.example.com",
+  },
+}
+```
+
+Invalid configuration (unknown environment/provider, missing `plausible.domain`,
+missing custom `adapter`) throws `AnalyticsConfigError` from `initialize()`.
+
+## Environment behavior
+
+| `environment` | default when `enabled` is omitted          |
+| ------------- | ------------------------------------------ |
+| `development` | **disabled**                               |
+| `test`        | **disabled**                               |
+| `staging`     | **disabled** (opt in with `enabled: true`) |
+| `production`  | **enabled**                                |
+
+An explicit `enabled` **always** overrides the default — `enabled: true` in
+`development`, `enabled: false` in `production`, both honored.
+
+`debug` defaults to `true` in `development` only, and can be set explicitly in any
+environment.
+
+While disabled the client is inert: no provider is created, **no script is
+injected**, `track()` / `pageView()` are no-ops (reported through `onEvent` with
+`delivered: false`), and `isEnabled()` returns `false`.
+
+Consent flows can toggle at runtime:
+
+```ts
+analytics.setEnabled(true); // lazily starts the provider if it was disabled at init
+```
+
+## Built-in event catalog
+
+Reuse these standardized names instead of inventing near-duplicates. Each has a
+typed property model (`?` = optional).
+
+<details>
+<summary><strong>Common</strong></summary>
+
+| Event                   | Properties                   |
+| ----------------------- | ---------------------------- |
+| `cta_clicked`           | `id?`, `label?`, `location?` |
+| `outbound_link_clicked` | `url`, `location?`           |
+| `download_clicked`      | `file`, `location?`          |
+| `search_performed`      | `query?`, `resultsCount?`    |
+
+</details>
+
+<details>
+<summary><strong>Lead generation</strong></summary>
+
+| Event                    | Properties                     |
+| ------------------------ | ------------------------------ |
+| `contact_form_started`   | `form`                         |
+| `contact_form_submitted` | `form`                         |
+| `phone_clicked`          | `location?`                    |
+| `email_clicked`          | `location?`                    |
+| `appointment_started`    | `service?`                     |
+| `appointment_completed`  | `service?`, `durationMinutes?` |
+
+</details>
+
+<details>
+<summary><strong>Authentication</strong></summary>
+
+| Event              | Properties           |
+| ------------------ | -------------------- |
+| `login_started`    | `method?`            |
+| `login_completed`  | `method?`            |
+| `login_failed`     | `method?`, `reason?` |
+| `signup_started`   | `method?`            |
+| `signup_completed` | `method?`, `plan?`   |
+
+</details>
+
+<details>
+<summary><strong>Ecommerce</strong></summary>
+
+| Event                | Properties                                               |
+| -------------------- | -------------------------------------------------------- |
+| `product_viewed`     | `productId`, `name?`, `price?`, `currency?`, `category?` |
+| `add_to_cart`        | `productId`, `quantity?`, `price?`, `currency?`          |
+| `remove_from_cart`   | `productId`, `quantity?`                                 |
+| `checkout_started`   | `cartValue?`, `itemCount?`, `currency?`                  |
+| `checkout_completed` | `cartValue?`, `itemCount?`, `currency?`                  |
+| `purchase_completed` | `revenue`, `currency`, `orderId?`, `itemCount?`          |
+
+</details>
+
+<details>
+<summary><strong>Engagement</strong></summary>
+
+| Event                 | Properties                          |
+| --------------------- | ----------------------------------- |
+| `video_started`       | `id?`, `title?`                     |
+| `video_completed`     | `id?`, `title?`, `durationSeconds?` |
+| `document_downloaded` | `file`, `category?`                 |
+| `social_link_clicked` | `network`, `location?`              |
+
+</details>
+
+Runtime helpers: `ANALYTICS_EVENT_CATALOG` (grouped), `ALL_ANALYTICS_EVENTS`
+(flat), `isKnownAnalyticsEvent(name)`.
+
+## Application-specific events
+
+The catalog is not a ceiling. Extend the open `AnalyticsEventMap` registry with
+**TypeScript module augmentation** — one file, no generics:
+
+```ts
+// src/analytics-events.ts  (import it once, e.g. from main.tsx)
+import '@pl4yzonellc/empire-analytics';
+
+declare module '@pl4yzonellc/empire-analytics' {
+  interface AnalyticsEventMap {
+    quote_requested: { service: string; budgetRange?: string };
+    newsletter_subscribed: { source: string };
+  }
+}
+```
+
+From then on, everywhere (`analytics.track`, `useTrackEvent`, `<Track>`):
+
+```ts
+analytics.track('quote_requested', { service: 'roofing' }); // ✅ typed
+analytics.track('quote_requestd', { service: 'roofing' }); // ❌ compile error (typo)
+analytics.track('quote_requested', {}); // ❌ compile error (missing `service`)
+```
+
+- standard events stay standardized
+- app events are strongly typed
+- arbitrary typo-prone strings are rejected by the compiler
+
+`AnalyticsEventMap` already `extends BaseAnalyticsEventMap`, so the whole catalog
+is always available.
+
+## Event properties
+
+- events with a required property force the `properties` argument; events with
+  only optional properties make it optional
+- `defaultProperties` from config are merged in with the **lowest** precedence
+- values are sanitized before they reach the adapter (see
+  [Privacy protection](#privacy-protection))
+
+## Revenue events
+
+Revenue is a first-class SDK concept. Applications never learn Plausible's payload
+shape.
+
+```ts
+analytics.track('purchase_completed', {
+  revenue: 49.99,
+  currency: 'USD',
+  orderId: 'abc123',
+});
+```
+
+The Plausible adapter translates `{ revenue, currency }` into
+`{ revenue: { amount, currency } }` and forwards the remaining fields as props.
+`{ revenue: { amount, currency } }` is also accepted. Configure the matching goal
+as a revenue goal in the Plausible dashboard; keep `plausible.revenue` enabled
+(the default).
+
+Raw financial / payment-card fields (`cardNumber`, `cvv`, …) are stripped by the
+privacy layer and never forwarded.
+
+## Privacy protection
+
+A two-tier key classifier runs on every property bag (including nested objects and
+arrays). Matching is on a normalized key — `credit_card`, `credit-card`,
+`creditCard` all match.
+
+**Always blocked (`sensitive`)** — credentials, tokens, card data, government ids:
+`password`, `passcode`, `token`, `accessToken`, `refreshToken`, `authorization`,
+`jwt`, `apiKey`, `clientSecret`, `creditCard`, `cardNumber`, `cvv`, `ssn`,
+`socialSecurityNumber`, `iban`, `routingNumber`, `sessionId`, … (see
+`DEFAULT_SENSITIVE_KEYS`).
+
+**Configurable (`pii`)** — direct identifiers: `email`, `phone`, `phoneNumber`,
+`firstName`, `lastName`, `fullName`, `address`, `streetAddress`, `dateOfBirth`,
+`ipAddress`, … (see `DEFAULT_PII_KEYS`).
+
+| Policy        | `development` / `debug` | `test` / `staging` | `production`                                                  |
+| ------------- | ----------------------- | ------------------ | ------------------------------------------------------------- |
+| `onSensitive` | `throw` (default)       | `warn` (default)   | `strip` (default; `throw`/`warn` are **downgraded to strip**) |
+| `onPii`       | `warn` (default)        | `warn` (default)   | `warn` (default; `throw` downgraded)                          |
+
+**Production never crashes** because analytics saw a bad property — `throw` is
+clamped. In development a blocked `sensitive` key raises `AnalyticsPrivacyError`
+(carrying the **key path only**, never the value) so mistakes surface early.
+
+The sanitization pipeline also:
+
+- removes functions, symbols, `undefined`, `null`, `NaN`/`Infinity`
+- converts `Date` → ISO string, `bigint` → string
+- breaks circular references instead of throwing
+- caps depth, property count, string length and array length
+- truncates over-long strings
+
+Tune it per app:
+
+```ts
+privacy: {
+  onPii: 'strip',                 // silently drop identifiers in every environment
+  allowKeys: ['country'],         // ...but keep a coarse `country`
+  blockKeys: ['internalMemberId'] // project-specific always-blocked key
+}
+```
+
+Blocked **values** are never logged, stored, or attached to any error.
+
+## Debugging
+
+```ts
+{
+  debug: true;
+}
+```
+
+Turns on a small internal logger (the library has no scattered `console.*`
+calls). Typical output:
+
+```text
+[Analytics] Event {
+  type: 'event',
+  name: 'checkout_started',
+  provider: 'plausible',
+  enabled: true,
+  environment: 'development',
+  properties: { cartValue: 125, itemCount: 3 },   // sanitized
+  blockedKeys: []                                  // key paths removed by privacy (names only)
+}
+```
+
+When disabled you also get a reason:
+
+```text
+[Analytics] Event skipped {
+  name: 'checkout_started',
+  reason: 'analytics disabled by default for the "development" environment'
+}
+```
+
+With `debug` off the logger is completely silent; errors still reach `onError`.
+
+The `console` provider (`provider: 'console'`) prints every event to the console
+instead of sending it — handy for local development without a Plausible account.
+
+## Explicit page views
+
+Plausible tracks SPA navigation itself, so **you do not need `useEffect` route
+tracking** and this package is **not coupled to any router**.
+
+Use `pageView()` only for special cases (virtual pages, multi-step wizards,
+modals treated as pages):
+
+```ts
+analytics.pageView('/checkout/step-2');
+```
+
+Sensitive query parameters (`?token=…`, `?password=…`) are stripped from the path
+before it is sent.
+
+If your app uses hash routing, set `plausible.hashRouting: true`. To take full
+manual control, set `plausible.autoPageViews: false` (loads the `manual` script
+variant) and call `pageView()` yourself.
+
+## Multi-tenant configuration
+
+`tenantKey` is treated as **application metadata**, not analytics data. It is not
+sent unless you opt in:
+
+```ts
+{
+  tenantKey: 'client-a',
+  includeTenantKey: true,        // now every event carries…
+  tenantPropertyName: 'tenant',  // …{ tenant: 'client-a' }
+}
+```
+
+Because configuration is just an object, a host app can build it from its own
+per-tenant runtime config service (domain, enabled flag, provider) and hand it to
+`<AnalyticsProvider>` or `analytics.initialize()`. Vite env vars are one possible
+source, never the only one.
+
+## Testing consuming applications
+
+Import from the dedicated `/testing` entry point (kept out of the production
+bundle). Tests never load Plausible and never send a real event.
+
+```ts
+import {
+  createMockAnalyticsClient,
+  createTestAnalyticsClient,
+  MemoryAdapter,
+} from '@pl4yzonellc/empire-analytics/testing';
+```
+
+### `createMockAnalyticsClient()` — a zero-dependency fake
+
+```ts
+import { AnalyticsProvider } from '@pl4yzonellc/empire-analytics';
+import { createMockAnalyticsClient } from '@pl4yzonellc/empire-analytics/testing';
+
+const analytics = createMockAnalyticsClient({ spy: (fn) => vi.fn(fn) });
+
+render(
+  <AnalyticsProvider config={config} client={analytics}>
+    <App />
+  </AnalyticsProvider>,
+);
+
+await userEvent.click(screen.getByRole('button', { name: 'Buy' }));
+
+expect(analytics.track).toHaveBeenCalledWith('checkout_started', expect.anything());
+// or, without a spy library:
+expect(analytics.events).toContainEqual({
+  name: 'checkout_started',
+  properties: { cartValue: 125 },
+});
+```
+
+Pass `spy: (fn) => vi.fn(fn)` (or `jest.fn`) to make the methods assertable with
+`toHaveBeenCalledWith`. Without it, inspect `analytics.events` / `analytics.pageViews`.
+`analytics.reset()` clears recorded calls.
+
+### `createTestAnalyticsClient()` — the real pipeline, in memory
+
+Runs the actual core (privacy sanitization, tenant handling, enabled logic) into a
+`MemoryAdapter`:
+
+```ts
+const { client, adapter } = createTestAnalyticsClient({ defaultProperties: { app: 'web' } });
+
+client.track('checkout_started', { cartValue: 125, password: 'nope' });
+
+expect(adapter.lastEvent).toEqual({
+  name: 'checkout_started',
+  properties: { app: 'web', cartValue: 125 }, // password stripped by the real privacy layer
+});
+```
+
+### `MemoryAdapter`
+
+Use directly with `provider: 'custom'` to assert exactly what the SDK forwards to
+a provider.
+
+## How the Plausible adapter works
+
+`PlausibleAdapter` (in `src/providers/plausible/`) is the only code that knows
+about Plausible. It has two runtimes, chosen by `plausible.mode`.
+
+### `mode: 'cdn'` (default)
+
+- **Script loading** — composes the CDN URL from the enabled script variants
+  (`script.revenue.manual.js`, …), injects a single deferred `<script data-domain>`
+  tag, and installs the `window.plausible` queue stub so early calls are buffered.
+  Injection is **idempotent**: a second adapter, a repeat `initialize()`, or a
+  hand-added snippet in `index.html` never produces a duplicate tag. Set
+  `injectScript: false` if your host page already includes the script;
+  `scriptUrl` points at a self-hosted instance or first-party proxy.
+- **Page views** — `pageView(path)` sends `plausible('pageview', { u })`.
+- **Cleanup** — `destroy()` removes the injected script and the queue stub it created.
+
+### `mode: 'package'` — [`@plausible-analytics/tracker`](https://www.npmjs.com/package/@plausible-analytics/tracker)
+
+- An **optional peer dependency**. The consuming app runs `pnpm add @plausible-analytics/tracker`;
+  the adapter reaches it through a lazy `import()`, so apps that don't opt in never
+  download it and it is not in the SDK's bundle.
+- **No remote `<script>`** — avoids the heavily blocklisted `plausible.io/js/script.js`
+  filename, pins the tracker version, and needs no `script-src` CSP entry. `initialize()`
+  calls the package's `init()` with `bindToWindow: false` (so `window.plausible` is
+  never created), mapping the SDK options onto `autoCapturePageviews`,
+  `hashBasedRouting`, `outboundLinks`, `fileDownloads`, `captureOnLocalhost`.
+- **Page views** — `pageView(path)` calls `track('pageview', { url })`.
+- **Cleanup** — the package exposes no teardown; `destroy()` drops the adapter's
+  reference so no further events are sent.
+- A missing package produces a generic `AnalyticsError` (`provider_unavailable`)
+  routed to `onError` — never an unhandled module-resolution crash.
+- `scriptUrl`, `injectScript` and `taggedEvents` do not apply in this mode.
+
+### Both modes
+
+- **Events** — `track(name, props)` maps the SDK property bag to Plausible's
+  `{ props, revenue }` shape (see [Revenue events](#revenue-events)).
+- **Resilience** — a missing `window`, a missing/throwing tracker (ad blocker,
+  privacy extension), or a failed load never throws. Failures are logged in `debug`
+  mode and routed to `onError`; generic `AnalyticsError` codes
+  (`script_load_failed`, `provider_unavailable`, `initialization_failed`, …) never
+  leak provider internals.
+- **SSR** — every browser-global access is guarded, so importing and constructing
+  the adapter is safe where `window`/`document` are absent.
+
+## Adding a future provider
+
+The core depends only on `AnalyticsAdapter`:
+
+```ts
+interface AnalyticsAdapter {
+  readonly name: string;
+  initialize(): Promise<void> | void;
+  track(eventName: string, properties?: Record<string, unknown>): void;
+  pageView(path?: string): void;
+  destroy(): void;
+}
+```
+
+### Option A — a custom adapter today (no library change)
+
+```ts
+import type { AnalyticsAdapter } from '@pl4yzonellc/empire-analytics';
+
+class PostHogAdapter implements AnalyticsAdapter {
+  readonly name = 'posthog';
+  initialize() {
+    /* load posthog-js */
+  }
+  track(name: string, props?: Record<string, unknown>) {
+    /* posthog.capture(name, props) */
+  }
+  pageView(path?: string) {
+    /* posthog.capture('$pageview', { $current_url: path }) */
+  }
+  destroy() {
+    /* posthog.reset() */
+  }
+}
+
+<AnalyticsProvider
+  config={{
+    provider: 'custom',
+    environment: 'production',
+    adapter: (ctx) => new PostHogAdapter(/* ctx.logger */),
+  }}
+/>;
+```
+
+### Option B — a first-class provider in the library
+
+1. add `src/providers/<name>/<Name>Adapter.ts` implementing `AnalyticsAdapter`
+2. add a `<Name>ProviderConfig` type and a `<name>` block to the config union in
+   `src/core/types.ts`
+3. add a `case '<name>'` to `createAdapter()` in `src/providers/factory.ts`
+4. resolve its defaults in `src/core/config.ts`
+
+Application-facing APIs (`track`, `pageView`, the event catalog, hooks) do not
+change.
+
+## Package scripts
+
+| Script               | Purpose                           |
+| -------------------- | --------------------------------- |
+| `pnpm build`         | Bundle to `dist/` (ESM + `.d.ts`) |
+| `pnpm test`          | Run the test suite once           |
+| `pnpm test:watch`    | Vitest watch mode                 |
+| `pnpm test:coverage` | Coverage report                   |
+| `pnpm typecheck`     | `tsc --noEmit`                    |
+| `pnpm lint`          | ESLint                            |
+| `pnpm format`        | Prettier write                    |
+| `pnpm format:check`  | Prettier check (CI)               |
+
+`pnpm install && pnpm build && pnpm test && pnpm typecheck && pnpm lint` all pass.
+
+A runnable demo lives in [`example/`](./example) — it uses the `console` provider
+so no Plausible credentials are needed.
+
+## License
+
+MIT