@hogsend/engine 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.18.0",
+  "version": "0.19.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.19.0",
+    "@hogsend/email": "^0.19.0",
+    "@hogsend/db": "^0.19.0",
+    "@hogsend/plugin-posthog": "^0.19.0",
+    "@hogsend/plugin-resend": "^0.19.0"
   },
   "optionalDependencies": {
-    "@hogsend/plugin-postmark": "^0.18.0"
+    "@hogsend/plugin-postmark": "^0.19.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,69 @@ 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),
+    ...(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.
+  if (analytics && !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 (a personal API key scoped person:read). " +
+        "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 +619,7 @@ export function createHogsendClient(
     emailProvider: provider,
     domainStatus,
     templates,
+    analyticsProviders,
     analytics,
     registry,
     bucketRegistry,

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,

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;
+  }
+}

package/src/lib/analytics-providers-from-env.ts

@@ -0,0 +1,36 @@
+import type { AnalyticsProvider } from "@hogsend/core";
+import { createPostHogProvider } from "@hogsend/plugin-posthog";
+import type { env as envSchema } from "../env.js";
+import { getRedis } from "./redis.js";
+
+/**
+ * Env-driven analytics-provider presets — the analytics sibling of
+ * `emailProvidersFromEnv`. PostHog is built when `POSTHOG_API_KEY` is set;
+ * person READS additionally need `POSTHOG_PERSONAL_API_KEY` (the public phc_
+ * key is write-only by PostHog's design) — without it the provider still
+ * captures and writes person properties, and reads soft-fail to the engine's
+ * contact-property fallback.
+ *
+ * Consumer-supplied providers (`analytics.providers` / `analytics.provider`)
+ * merge AFTER these in the registry, so a consumer build of the same id wins.
+ */
+export function analyticsProvidersFromEnv(
+  env: typeof envSchema,
+): AnalyticsProvider[] {
+  const providers: AnalyticsProvider[] = [];
+
+  if (env.POSTHOG_API_KEY) {
+    providers.push(
+      createPostHogProvider({
+        apiKey: env.POSTHOG_API_KEY,
+        host: env.POSTHOG_HOST,
+        personalApiKey: env.POSTHOG_PERSONAL_API_KEY,
+        projectId: env.POSTHOG_PROJECT_ID,
+        privateHost: env.POSTHOG_PRIVATE_HOST,
+        redis: getRedis(),
+      }),
+    );
+  }
+
+  return providers;
+}

package/src/lib/analytics-singleton.ts

@@ -1,4 +1,4 @@
-import type { PostHogService } from "@hogsend/core";
+import type { AnalyticsProvider } from "@hogsend/core";
 import { createOptionalSingleton } from "./singleton.js";
 
 /**
@@ -24,7 +24,7 @@ import { createOptionalSingleton } from "./singleton.js";
  * container resolves `analytics` to `undefined` and installs it here, so every
  * read remains a no-op exactly as before — hence the optional singleton variant.
  */
-const singleton = createOptionalSingleton<PostHogService>();
+const singleton = createOptionalSingleton<AnalyticsProvider>();
 
 export const setAnalytics = singleton.set;
 export const getAnalytics = singleton.get;

package/src/lib/bucket-posthog-sync.ts

@@ -42,16 +42,18 @@ export function syncBucketToPostHog(opts: {
 
   try {
     if (kind === "entered") {
-      // $set { key: true } — mirrors plugin-posthog identify() ($set path).
-      posthog.identify(userId, { [propertyKey]: true });
+      // set { key: true } — the provider's person-write wire ($set on PostHog).
+      void posthog.setPersonProperties({
+        distinctId: userId,
+        set: { [propertyKey]: true },
+      });
     } else {
-      // $unset [key] — RECOMMENDED on leave (Section 12). The property is absent
+      // unset [key] — RECOMMENDED on leave (Section 12). The property is absent
       // unless the user is currently a member, so both `key = true` and
       // `key is set` cohorts behave correctly.
-      posthog.captureEvent({
+      void posthog.setPersonProperties({
         distinctId: userId,
-        event: "$set",
-        properties: { $unset: [propertyKey] },
+        unset: [propertyKey],
       });
     }
   } catch (err) {

package/src/lib/posthog.ts

@@ -4,12 +4,28 @@ import { getRedis } from "./redis.js";
 
 let _posthog: PostHogService | undefined;
 
+/**
+ * Lazy PostHog service singleton for STANDALONE consumer imports (journeys
+ * calling `getPostHog()` for capture/identify/flags). Reads process.env
+ * directly so it works without a container reference.
+ *
+ * Person READS additionally require `POSTHOG_PERSONAL_API_KEY` (the phc_
+ * project key is write-only by PostHog's design); without it
+ * `getPersonProperties` soft-fails to `{}`.
+ *
+ * The engine's own analytics path now flows through the neutral
+ * `AnalyticsProvider` registry (see `analyticsProvidersFromEnv` /
+ * `createHogsendClient`'s `analytics` option) — this stays for consumer code.
+ */
 export function getPostHog(): PostHogService | undefined {
   if (!process.env.POSTHOG_API_KEY) return undefined;
   if (!_posthog) {
     _posthog = createPostHogService({
       apiKey: process.env.POSTHOG_API_KEY,
       host: process.env.POSTHOG_HOST,
+      personalApiKey: process.env.POSTHOG_PERSONAL_API_KEY,
+      projectId: process.env.POSTHOG_PROJECT_ID,
+      privateHost: process.env.POSTHOG_PRIVATE_HOST,
       redis: getRedis(),
     });
   }

package/src/worker.ts

@@ -108,8 +108,9 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
       _worker?.stop(),
       // Shut down the injected analytics instance (same object the worker's
       // tasks use), not the module singleton. Undefined when no analytics is
-      // configured — the optional chain makes that a no-op.
-      container.analytics?.shutdown(),
+      // configured, and `shutdown` is optional on the provider contract —
+      // both optional chains make that a no-op.
+      container.analytics?.shutdown?.(),
       getRedisIfConnected()?.quit(),
     ]);
   }