@hogsend/engine 0.18.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -40,14 +40,14 @@
     "svix": "^1.95.1",
     "winston": "^3.19.0",
     "zod": "^4.4.3",
-    "@hogsend/core": "^0.18.0",
-    "@hogsend/db": "^0.18.0",
-    "@hogsend/email": "^0.18.0",
-    "@hogsend/plugin-posthog": "^0.18.0",
-    "@hogsend/plugin-resend": "^0.18.0"
+    "@hogsend/core": "^0.20.0",
+    "@hogsend/db": "^0.20.0",
+    "@hogsend/email": "^0.20.0",
+    "@hogsend/plugin-posthog": "^0.20.0",
+    "@hogsend/plugin-resend": "^0.20.0"
   },
   "optionalDependencies": {
-    "@hogsend/plugin-postmark": "^0.18.0"
+    "@hogsend/plugin-postmark": "^0.20.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/container.ts

@@ -1,5 +1,10 @@
 import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
-import type { EmailProvider, PostHogService, TimeZone } from "@hogsend/core";
+import type {
+  AnalyticsProvider,
+  EmailProvider,
+  PostHogService,
+  TimeZone,
+} from "@hogsend/core";
 import type { BucketRegistry, JourneyRegistry } from "@hogsend/core/registry";
 import type { SendWindow } from "@hogsend/core/schedule";
 import {
@@ -25,6 +30,12 @@ import { env } from "./env.js";
 import { setClientScheduleDefaults } from "./journeys/client-defaults-singleton.js";
 import type { DefinedJourney } from "./journeys/define-journey.js";
 import { buildJourneyRegistry } from "./journeys/registry.js";
+import {
+  isAnalyticsProvider,
+  wrapLegacyAnalyticsService,
+} from "./lib/analytics-adapter.js";
+import { AnalyticsProviderRegistry } from "./lib/analytics-provider-registry.js";
+import { analyticsProvidersFromEnv } from "./lib/analytics-providers-from-env.js";
 import { setAnalytics } from "./lib/analytics-singleton.js";
 import { type Auth, createAuth } from "./lib/auth.js";
 import {
@@ -41,7 +52,6 @@ import type {
 import { hatchet } from "./lib/hatchet.js";
 import { createLogger, type Logger } from "./lib/logger.js";
 import { createTrackedMailer } from "./lib/mailer.js";
-import { getPostHog } from "./lib/posthog.js";
 import { createRedisSecondaryStorage, getRedis } from "./lib/redis.js";
 import { sendResetPasswordEmail } from "./lib/reset-email.js";
 import { seedPostHogDestination } from "./lib/seed-posthog-destination.js";
@@ -92,7 +102,18 @@ export interface HogsendClient {
    * templates without going through a send. Empty when no templates are wired.
    */
   templates: TemplateRegistry;
-  analytics?: PostHogService;
+  /**
+   * The container-held registry of analytics providers, keyed by `meta.id` —
+   * the analytics sibling of {@link emailProviders}. Built from env presets
+   * (`analyticsProvidersFromEnv`) merged consumer-last.
+   */
+  analyticsProviders: AnalyticsProviderRegistry;
+  /**
+   * The single resolved ACTIVE analytics provider (identity PULL + person
+   * writes + capture). Undefined when nothing is configured — every consumer
+   * treats that as a silent no-op.
+   */
+  analytics?: AnalyticsProvider;
   registry: JourneyRegistry;
   /**
    * The bucket registry (id map + event/property inverted indexes for candidate
@@ -171,25 +192,43 @@ export interface HogsendClientOptions {
     templates?: TemplateRegistry;
   };
   /**
-   * The PostHog-style analytics service. As of the destinations spine its role
+   * The analytics provider(s) — provider-neutral since the
+   * `AnalyticsProvider` contract (the analytics sibling of `EmailProvider`;
+   * PostHog is the reference implementation, not the architecture). Its role
    * is deliberately NARROW — it is NOT the outbound-catalog firing path (the
-   * email/contact/journey/bucket lifecycle now fans out durably via
-   * DESTINATIONS on the webhook spine, keyed by `webhook_endpoints.kind`). It
-   * remains for exactly two things:
+   * email/contact/journey/bucket lifecycle fans out durably via DESTINATIONS
+   * on the webhook spine). The ACTIVE provider serves:
    *
    * 1. The identity PULL — `getPersonProperties` for per-user timezone
    *    resolution at journey enrollment (`define-journey` / `lib/timezone.ts`).
-   *    This read role is UNCHANGED and load-bearing.
-   * 2. The opt-in `bucket.syncToPostHog` person-property mirror — `$set`/`$unset`
-   *    of a boolean cohort property on bucket transitions (`bucket-posthog-sync`).
-   *    Off by default; PostHog `$set`/`$unset` identity semantics have no
-   *    vendor-neutral envelope, so this stays a PostHog-direct write.
+   *    On PostHog this needs `POSTHOG_PERSONAL_API_KEY` (the phc_ project key
+   *    is write-only by design); reads soft-fail to contact-property
+   *    fallbacks without it.
+   * 2. Person WRITES — `setPersonProperties` (the opt-in `bucket.syncToPostHog`
+   *    mirror, and trait propagation). Rides the capture pipeline; no extra
+   *    credential.
+   *
+   * Accepted shapes (mirrors `email`):
+   * - a group: `{ provider?, providers?, defaultProvider? }` — register one or
+   *   many `AnalyticsProvider`s; env presets (`analyticsProvidersFromEnv` —
+   *   PostHog when `POSTHOG_API_KEY` is set) merge consumer-LAST;
+   *   `defaultProvider` / env `ANALYTICS_PROVIDER` picks the active id
+   *   (default `"posthog"`).
+   * - a bare `AnalyticsProvider` — registered and made active.
+   * - @deprecated a legacy `PostHogService` — wrapped via
+   *   `wrapLegacyAnalyticsService` and made active.
    *
    * Lives at the top level (not under `email`) because the engine itself uses
-   * it for the PULL. Defaults to {@link getPostHog} (a no-op when
-   * `POSTHOG_API_KEY` is unset).
+   * it for the PULL.
    */
-  analytics?: PostHogService;
+  analytics?:
+    | PostHogService
+    | AnalyticsProvider
+    | {
+        provider?: AnalyticsProvider;
+        providers?: AnalyticsProvider[];
+        defaultProvider?: string;
+      };
   /**
    * Code-defined outbound DESTINATIONS (Phase 3). Each is a
    * `defineDestination()` delivery-time transform keyed by its `meta.id`, which
@@ -462,16 +501,76 @@ export function createHogsendClient(
       },
     });
 
-  const analytics = opts.analytics ?? getPostHog();
+  // Resolve the analytics provider(s) — mirrors the email-provider shape:
+  // env presets first, consumer registrations LAST (last-writer-wins), then
+  // ONE active provider picked by id. The deprecated bare-PostHogService and
+  // bare-AnalyticsProvider forms register-and-activate directly.
+  const analyticsOpt = opts.analytics;
+  const analyticsGroup =
+    analyticsOpt &&
+    !isAnalyticsProvider(analyticsOpt as AnalyticsProvider) &&
+    typeof (analyticsOpt as PostHogService).captureEvent !== "function"
+      ? (analyticsOpt as {
+          provider?: AnalyticsProvider;
+          providers?: AnalyticsProvider[];
+          defaultProvider?: string;
+        })
+      : undefined;
+
+  const analyticsProviders = new AnalyticsProviderRegistry([
+    ...analyticsProvidersFromEnv(env, { db, logger }),
+    ...(analyticsGroup?.providers ?? []),
+    ...(analyticsGroup?.provider ? [analyticsGroup.provider] : []),
+  ]);
+
+  let analytics: AnalyticsProvider | undefined;
+  if (analyticsOpt && !analyticsGroup) {
+    // Bare provider or legacy service: register and activate it directly.
+    analytics = isAnalyticsProvider(analyticsOpt as AnalyticsProvider)
+      ? (analyticsOpt as AnalyticsProvider)
+      : wrapLegacyAnalyticsService(analyticsOpt as PostHogService);
+    analyticsProviders.register(analytics);
+  } else {
+    const activeId = analyticsGroup?.defaultProvider ?? env.ANALYTICS_PROVIDER;
+    analytics = analyticsProviders.get(activeId);
+    if (analyticsGroup?.defaultProvider && !analytics) {
+      throw new Error(
+        `analytics.defaultProvider "${analyticsGroup.defaultProvider}" is not a registered analytics provider (registered: ${analyticsProviders
+          .getAll()
+          .map((p) => p.meta.id)
+          .join(", ")})`,
+      );
+    }
+  }
+
+  // Person reads need a privileged credential on most platforms (PostHog: a
+  // personal API key — the phc_ project key is write-only by design). Surface
+  // the degraded mode once at boot instead of letting tz resolution silently
+  // fall back for months.
+  // OAuth-capable providers resolve their credential ASYNC (the env factory
+  // logs the truthful nudge after the load settles) — a sync check here would
+  // log a false "DISABLED" on every boot of a connected instance.
+  if (
+    analytics &&
+    !analytics.capabilities.oauth &&
+    !analytics.capabilities.personReads
+  ) {
+    logger.info(
+      `analytics provider "${analytics.meta.id}" has person reads DISABLED — ` +
+        "timezone resolution falls back to contact properties. For PostHog, " +
+        "set POSTHOG_PERSONAL_API_KEY or run `hogsend connect posthog`. " +
+        "Docs: https://hogsend.com/docs/guides/analytics-access",
+    );
+  }
 
   // Expose the resolved analytics instance to the module-level task-execution
   // sites that have no client reference. Its role is NARROW (see the
   // `analytics?` option doc): the identity PULL (`getPersonProperties` for tz
-  // resolution in the journey durable task) plus the opt-in
-  // `bucket.syncToPostHog` person-property mirror — NOT the outbound catalog
-  // firing path (that is the destinations spine). `createHogsendClient` runs in
-  // both the API and worker, so this is installed before any worker task runs.
-  // May be undefined (no POSTHOG_API_KEY) — the reads stay no-ops.
+  // resolution in the journey durable task) plus person writes (the opt-in
+  // `bucket.syncToPostHog` mirror) — NOT the outbound catalog firing path
+  // (that is the destinations spine). `createHogsendClient` runs in both the
+  // API and worker, so this is installed before any worker task runs. May be
+  // undefined (no provider configured) — the reads stay no-ops.
   setAnalytics(analytics);
 
   // Build + install the outbound DESTINATION registry (Phase 3) the
@@ -527,6 +626,7 @@ export function createHogsendClient(
     emailProvider: provider,
     domainStatus,
     templates,
+    analyticsProviders,
     analytics,
     registry,
     bucketRegistry,

package/src/destinations/presets/posthog.ts

@@ -1,3 +1,4 @@
+import type { OutboundPayloads } from "../../lib/outbound.js";
 import { WEBHOOK_EVENT_TYPES } from "../../lib/webhook-signing.js";
 import { defineDestination } from "../define-destination.js";
 
@@ -16,6 +17,60 @@ interface PostHogConfig {
    * be remapped this way; absent or unmapped keys pass through unchanged.
    */
   eventNames?: Record<string, string>;
+  /**
+   * Person-property propagation (the contact → analytics-person rail). When
+   * true, `contact.created` / `contact.updated` events become `$set` captures
+   * of the contact's `properties` under the contact's canonical key — the
+   * SAME distinct id the identify loop uses — so PostHog person profiles
+   * accumulate contact truth (plan, role, lifecycle stage…) and cohorts can
+   * segment on it. `contact.unsubscribed` (scope `all`) sets
+   * `hogsend_unsubscribed: true`.
+   *
+   * Privacy posture: ONLY `contact.properties` syncs — never email or any
+   * other identifier. Anything but a boolean `true` (config is a loose jsonb
+   * bag) leaves `contact.*` events SKIPPED entirely — they carry no
+   * `userId`/`to`, so the generic capture branch could never address them
+   * correctly anyway.
+   */
+  syncPersons?: boolean;
+  /**
+   * The person property a scope-`all` unsubscribe sets (default
+   * `hogsend_unsubscribed`) — overridable like the bucket mirror's
+   * `postHogPropertyKey`, so operators can match their own naming scheme.
+   */
+  unsubscribedPropertyKey?: string;
+}
+
+/**
+ * The one place the PostHog capture request is built — all three transform
+ * branches (person `$set`, `email.action`, generic catalog capture) share it,
+ * so a change to the capture wire shape happens once.
+ */
+function captureRequest(opts: {
+  host: string;
+  apiKey: string;
+  event: string;
+  distinctId: string | undefined;
+  timestamp: string;
+  properties: Record<string, unknown>;
+}): {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body: string;
+} {
+  return {
+    url: `${opts.host}/capture/`,
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      api_key: opts.apiKey,
+      event: opts.event,
+      distinct_id: opts.distinctId,
+      timestamp: opts.timestamp,
+      properties: { ...opts.properties, $lib: "hogsend" },
+    }),
+  };
 }
 
 /**
@@ -47,6 +102,62 @@ export const posthogDestination = defineDestination({
       );
     }
     const host = config.host ?? "https://us.i.posthog.com";
+
+    // Person-property propagation: `contact.*` events carry a contact payload
+    // (id/externalId/email/properties), NOT the userId/to identity chain the
+    // generic capture branch keys on — so they are handled here exclusively
+    // and SKIPPED (null) when `config.syncPersons` is off.
+    if (envelope.type.startsWith("contact.")) {
+      // Strict `=== true`: config is a loose jsonb bag, and a stray string
+      // value ("false") must not enable the sync.
+      if (config.syncPersons !== true) return null;
+
+      const setCapture = (distinctId: string, set: Record<string, unknown>) =>
+        captureRequest({
+          host,
+          apiKey: config.apiKey as string,
+          event: "$set",
+          distinctId,
+          timestamp: envelope.timestamp,
+          properties: { $set: set },
+        });
+
+      if (
+        envelope.type === "contact.created" ||
+        envelope.type === "contact.updated"
+      ) {
+        const contact =
+          envelope.data as unknown as OutboundPayloads["contact.updated"];
+        const props = contact.properties ?? {};
+        // Nothing to propagate — a successful no-op, not a delivery failure.
+        if (Object.keys(props).length === 0) return null;
+        // The contact's canonical key (externalId ?? id) — the same distinct
+        // id the identify loop and hs_t stitch use, so the $set lands on the
+        // person the contact's web sessions and email events already share.
+        // Known limitation: the serialized payload omits anonymousId, so an
+        // anonymous-keyed contact syncs under its row id rather than its
+        // anonymous key — fixed properly when contact.* payloads grow a
+        // first-class `contactKey` field.
+        return setCapture(contact.externalId ?? contact.id, props);
+      }
+
+      if (envelope.type === "contact.unsubscribed") {
+        const data =
+          envelope.data as unknown as OutboundPayloads["contact.unsubscribed"];
+        // Category-scoped opt-outs are too granular for a person flag, and a
+        // payload without externalId can't be addressed safely (the canonical
+        // key of an email-only contact is its row id, which this payload
+        // doesn't carry — guessing by email would mint a wrong person).
+        if (data.scope !== "all" || !data.externalId) return null;
+        const flag = config.unsubscribedPropertyKey ?? "hogsend_unsubscribed";
+        return setCapture(data.externalId, { [flag]: true });
+      }
+
+      // contact.deleted: PostHog person deletion is a private-API operation,
+      // not a capture — out of scope for this rail.
+      return null;
+    }
+
     const data = envelope.data as {
       userId?: string | null;
       to?: string | null;
@@ -69,38 +180,29 @@ export const posthogDestination = defineDestination({
         userId: string | null;
         at: string;
       };
-      return {
-        url: `${host}/capture/`,
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          api_key: config.apiKey,
-          event: action.event,
-          distinct_id: distinctId,
-          timestamp: envelope.timestamp,
-          properties: {
-            ...(action.properties ?? {}),
-            emailSendId: action.emailSendId,
-            templateKey: action.templateKey,
-            linkId: action.linkId,
-            $lib: "hogsend",
-          },
-        }),
-      };
+      return captureRequest({
+        host,
+        apiKey: config.apiKey,
+        event: action.event,
+        distinctId,
+        timestamp: envelope.timestamp,
+        properties: {
+          ...(action.properties ?? {}),
+          emailSendId: action.emailSendId,
+          templateKey: action.templateKey,
+          linkId: action.linkId,
+        },
+      });
     }
     // Optional event-name remap (identity by default).
     const eventName = config.eventNames?.[envelope.type] ?? envelope.type;
-    return {
-      url: `${host}/capture/`,
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        api_key: config.apiKey,
-        event: eventName,
-        distinct_id: distinctId,
-        timestamp: envelope.timestamp,
-        properties: { ...envelope.data, $lib: "hogsend" },
-      }),
-    };
+    return captureRequest({
+      host,
+      apiKey: config.apiKey,
+      event: eventName,
+      distinctId,
+      timestamp: envelope.timestamp,
+      properties: envelope.data as Record<string, unknown>,
+    });
   },
 });

package/src/env.ts

@@ -134,6 +134,21 @@ export const env = createEnv({
     CLIENT_MIGRATIONS_FOLDER: z.string().min(1).optional(),
     POSTHOG_API_KEY: z.string().min(1).optional(),
     POSTHOG_HOST: z.string().url().optional(),
+    // Personal API key (scoped `person:read`, optionally `person:write`) for
+    // person-property READS on the private API. The phc_ project key cannot
+    // read — it is public + write-only by PostHog's design. Without this,
+    // person reads soft-fail and timezone resolution falls back to contact
+    // properties. See the "Analytics access" docs page.
+    POSTHOG_PERSONAL_API_KEY: z.string().min(1).optional(),
+    // PostHog project id for environment-scoped private endpoints. Discovered
+    // automatically via GET /api/projects/@current/ when unset.
+    POSTHOG_PROJECT_ID: z.string().min(1).optional(),
+    // Private (app) API host override. Defaults to POSTHOG_HOST with the
+    // `.i.` ingestion label stripped (eu.i.posthog.com → eu.posthog.com).
+    POSTHOG_PRIVATE_HOST: z.string().url().optional(),
+    // Selects the ACTIVE analytics provider id out of the registry (env
+    // presets + consumer-registered providers). Mirrors EMAIL_PROVIDER.
+    ANALYTICS_PROVIDER: z.string().min(1).default("posthog"),
     POSTHOG_WEBHOOK_SECRET: z.string().min(1).optional(),
     // When true AND POSTHOG_API_KEY is set, the engine idempotently auto-seeds
     // ONE kind="posthog" webhook endpoint subscribed to the email funnel so the

package/src/index.ts

@@ -37,7 +37,11 @@ export * from "@hogsend/core";
 // omitted here: the engine's public `SendEmailOptions` is the high-level
 // journey-facing send options from `./lib/email.js`; the provider-contract
 // `SendEmailOptions` remains available via `@hogsend/core`.)
-export { defineEmailProvider, WebhookHandshakeSignal } from "@hogsend/core";
+export {
+  defineAnalyticsProvider,
+  defineEmailProvider,
+  WebhookHandshakeSignal,
+} from "@hogsend/core";
 export {
   BucketRegistry,
   JourneyRegistry,
@@ -136,6 +140,9 @@ export {
   getJourneyRegistrySingleton,
   setJourneyRegistry,
 } from "./journeys/registry-singleton.js";
+// --- Analytics provider registry (the analytics sibling) ---
+export { AnalyticsProviderRegistry } from "./lib/analytics-provider-registry.js";
+export { analyticsProvidersFromEnv } from "./lib/analytics-providers-from-env.js";
 // --- Auth ---
 export {
   type Auth,
@@ -220,6 +227,18 @@ export {
 // --- Logging ---
 export { createLogger, type Logger } from "./lib/logger.js";
 export { createTrackedMailer } from "./lib/mailer.js";
+// --- OAuth token manager (provider access-token cache + refresh) ---
+export {
+  ABSENT_RECHECK_MS,
+  type CredentialState,
+  type CredentialStore,
+  createTokenManager,
+  EXPIRY_SKEW_MS,
+  FAILURE_BACKOFF_MS,
+  HOGSEND_POSTHOG_CLIENT_ID,
+  oauthCredentialPayloadSchema,
+  type TokenManager,
+} from "./lib/oauth-token-manager.js";
 // --- Outbound webhooks: emit spine (Section 1.4) ---
 export {
   emitOutbound,
@@ -228,6 +247,18 @@ export {
   type OutboundPayloads,
 } from "./lib/outbound.js";
 export { getPostHog } from "./lib/posthog.js";
+// --- Provider credentials (encrypted-at-rest OAuth token store) ---
+export {
+  type CredentialKind,
+  type DecryptedProviderCredential,
+  deleteProviderCredential,
+  getProviderCredential,
+  type OAuthCredentialPayload,
+  ProviderCredentialDecryptError,
+  type ProviderCredentialMeta,
+  saveProviderCredential,
+  toCredentialMeta,
+} from "./lib/provider-credentials.js";
 export {
   type AuthSecondaryStorage,
   createRedisSecondaryStorage,
@@ -235,6 +266,8 @@ export {
 } from "./lib/redis.js";
 // --- Self-service password reset (engine-owned, self-contained email) ---
 export { sendResetPasswordEmail } from "./lib/reset-email.js";
+// --- PostHog destination seed (idempotent; ENABLE_POSTHOG_DESTINATION) ---
+export { seedPostHogDestination } from "./lib/seed-posthog-destination.js";
 export {
   type ConfirmSemanticClickInput,
   type ConfirmSemanticClickResult,

package/src/lib/analytics-adapter.ts

@@ -0,0 +1,68 @@
+import type { AnalyticsProvider, PostHogService } from "@hogsend/core";
+
+/**
+ * Wrap a legacy `PostHogService` (the deprecated PostHog-shaped interface
+ * accepted by `createHogsendClient({ analytics })` since before the neutral
+ * `AnalyticsProvider` contract existed) so it satisfies the contract the
+ * engine now speaks internally. Capabilities are assumed-on: a hand-built
+ * service predates capability reporting, and every method is best-effort
+ * anyway.
+ *
+ * Mapping notes:
+ * - `setPersonProperties.set` → `identify(distinctId, set)` (the legacy $set
+ *   path). `setOnce` ALSO maps to `identify` — legacy services have no
+ *   set-once wire, so overwrite semantics apply; `unset` maps to the legacy
+ *   raw `$set` capture with `$unset`, mirroring what the bucket sync used to
+ *   emit directly.
+ */
+export function wrapLegacyAnalyticsService(
+  service: PostHogService,
+): AnalyticsProvider {
+  return {
+    meta: {
+      id: "custom",
+      name: "Custom analytics service (legacy PostHogService shape)",
+    },
+    capabilities: { personReads: true, personWrites: true },
+
+    getPersonProperties(distinctId) {
+      return service.getPersonProperties(distinctId);
+    },
+
+    async setPersonProperties({ distinctId, set, setOnce, unset }) {
+      const merged = { ...(setOnce ?? {}), ...(set ?? {}) };
+      if (Object.keys(merged).length > 0) {
+        service.identify(distinctId, merged);
+      }
+      if (unset?.length) {
+        service.captureEvent({
+          distinctId,
+          event: "$set",
+          properties: { $unset: unset },
+        });
+      }
+    },
+
+    capture(opts) {
+      service.captureEvent(opts);
+    },
+
+    async shutdown() {
+      await service.shutdown();
+    },
+  };
+}
+
+/**
+ * Runtime discrimination for the `analytics` option union: a neutral
+ * `AnalyticsProvider` carries `meta` + `capture`; the legacy `PostHogService`
+ * carries `captureEvent` and no `meta`.
+ */
+export function isAnalyticsProvider(
+  value: AnalyticsProvider | PostHogService,
+): value is AnalyticsProvider {
+  return (
+    typeof (value as AnalyticsProvider).capture === "function" &&
+    typeof (value as AnalyticsProvider).meta === "object"
+  );
+}

package/src/lib/analytics-provider-registry.ts

@@ -0,0 +1,35 @@
+import type { AnalyticsProvider } from "@hogsend/core";
+
+/**
+ * Container-held registry of analytics providers, keyed by `provider.meta.id`
+ * — the analytics sibling of `EmailProviderRegistry`. The container picks ONE
+ * `active` provider out of it (env `ANALYTICS_PROVIDER` /
+ * `analytics.defaultProvider`, default `"posthog"`) for the identity PULL,
+ * person writes, and capture.
+ *
+ * Keyed with last-writer-wins, so a consumer-supplied provider of the same id
+ * overrides an env preset of that id.
+ */
+export class AnalyticsProviderRegistry {
+  private byId = new Map<string, AnalyticsProvider>();
+
+  constructor(providers: AnalyticsProvider[] = []) {
+    for (const provider of providers) this.register(provider);
+  }
+
+  register(provider: AnalyticsProvider): void {
+    this.byId.set(provider.meta.id, provider);
+  }
+
+  get(id: string): AnalyticsProvider | undefined {
+    return this.byId.get(id);
+  }
+
+  getAll(): AnalyticsProvider[] {
+    return [...this.byId.values()];
+  }
+
+  count(): number {
+    return this.byId.size;
+  }
+}