@hogsend/engine 0.19.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.19.0",
+  "version": "0.21.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.19.0",
-    "@hogsend/email": "^0.19.0",
-    "@hogsend/db": "^0.19.0",
-    "@hogsend/plugin-posthog": "^0.19.0",
-    "@hogsend/plugin-resend": "^0.19.0"
+    "@hogsend/core": "^0.21.0",
+    "@hogsend/db": "^0.21.0",
+    "@hogsend/email": "^0.21.0",
+    "@hogsend/plugin-posthog": "^0.21.0",
+    "@hogsend/plugin-resend": "^0.21.0"
   },
   "optionalDependencies": {
-    "@hogsend/plugin-postmark": "^0.19.0"
+    "@hogsend/plugin-postmark": "^0.21.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/container.ts

@@ -518,7 +518,7 @@ export function createHogsendClient(
       : undefined;
 
   const analyticsProviders = new AnalyticsProviderRegistry([
-    ...analyticsProvidersFromEnv(env),
+    ...analyticsProvidersFromEnv(env, { db, logger }),
     ...(analyticsGroup?.providers ?? []),
     ...(analyticsGroup?.provider ? [analyticsGroup.provider] : []),
   ]);
@@ -547,11 +547,18 @@ export function createHogsendClient(
   // 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) {
+  // 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 (a personal API key scoped person:read). " +
+        "set POSTHOG_PERSONAL_API_KEY or run `hogsend connect posthog`. " +
         "Docs: https://hogsend.com/docs/guides/analytics-access",
     );
   }

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/index.ts

@@ -227,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,
@@ -235,6 +247,23 @@ export {
   type OutboundPayloads,
 } from "./lib/outbound.js";
 export { getPostHog } from "./lib/posthog.js";
+// --- PostHog OAuth scopes (front-loaded set; gap-detector source of truth) ---
+export { EXPECTED_POSTHOG_SCOPES } from "./lib/posthog-scopes.js";
+// --- Provider credentials (encrypted-at-rest OAuth token store) ---
+export {
+  type CredentialKind,
+  type DecryptedProviderCredential,
+  type DerivedCredentialPayload,
+  deleteProviderCredential,
+  getDerivedCredential,
+  getProviderCredential,
+  type OAuthCredentialPayload,
+  ProviderCredentialDecryptError,
+  type ProviderCredentialMeta,
+  saveDerivedCredential,
+  saveProviderCredential,
+  toCredentialMeta,
+} from "./lib/provider-credentials.js";
 export {
   type AuthSecondaryStorage,
   createRedisSecondaryStorage,
@@ -242,6 +271,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-providers-from-env.ts

@@ -1,25 +1,67 @@
 import type { AnalyticsProvider } from "@hogsend/core";
-import { createPostHogProvider } from "@hogsend/plugin-posthog";
+import type { Database } from "@hogsend/db";
+import {
+  createPostHogProvider,
+  type PostHogAuthTokenAccessor,
+} from "@hogsend/plugin-posthog";
 import type { env as envSchema } from "../env.js";
+import type { Logger } from "./logger.js";
+import { createTokenManager } from "./oauth-token-manager.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.
+ * person READS additionally need a privileged credential: an OAuth credential
+ * stored via `hogsend connect posthog` (preferred, token-manager-backed) or
+ * `POSTHOG_PERSONAL_API_KEY` (the public phc_ key is write-only by PostHog's
+ * design) — without either 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,
+  deps?: { db?: Database; logger?: Logger },
 ): AnalyticsProvider[] {
   const providers: AnalyticsProvider[] = [];
 
   if (env.POSTHOG_API_KEY) {
+    // Token-manager-backed accessor: the manager re-checks the DB (30s
+    // negative cache), so a credential stored at RUNTIME via
+    // `hogsend connect posthog` comes alive without a restart.
+    let authToken: PostHogAuthTokenAccessor | undefined;
+    if (deps?.db) {
+      const tokenManager = createTokenManager({
+        db: deps.db,
+        providerId: "posthog",
+        logger: deps.logger,
+      });
+      // Load-only warm-up (no refresh, never blocks construction). The
+      // person-reads nudge logs HERE, after the load settles — the container
+      // can't log it truthfully at boot because capabilities resolve async
+      // for OAuth-capable providers (a connected instance would otherwise
+      // log "DISABLED" once on every boot).
+      const personalKeySet = Boolean(env.POSTHOG_PERSONAL_API_KEY);
+      void tokenManager
+        .prime()
+        .then(() => {
+          if (!personalKeySet && tokenManager.credentialState() !== "present") {
+            deps.logger?.info(
+              'analytics provider "posthog" has person reads DISABLED — ' +
+                "timezone resolution falls back to contact properties. Set " +
+                "POSTHOG_PERSONAL_API_KEY or run `hogsend connect posthog`. " +
+                "Docs: https://hogsend.com/docs/guides/analytics-access",
+            );
+          }
+        })
+        .catch(() => {});
+      authToken = {
+        getToken: () => tokenManager.getAccessToken(),
+        isAvailable: () => tokenManager.credentialState() === "present",
+      };
+    }
     providers.push(
       createPostHogProvider({
         apiKey: env.POSTHOG_API_KEY,
@@ -28,6 +70,7 @@ export function analyticsProvidersFromEnv(
         projectId: env.POSTHOG_PROJECT_ID,
         privateHost: env.POSTHOG_PRIVATE_HOST,
         redis: getRedis(),
+        authToken,
       }),
     );
   }