@hogsend/plugin-posthog 0.18.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/plugin-posthog",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -23,7 +23,7 @@
   },
   "dependencies": {
     "posthog-node": "^5.35.1",
-    "@hogsend/core": "^0.18.0"
+    "@hogsend/core": "^0.20.0"
   },
   "peerDependencies": {
     "ioredis": ">=5.0.0"

package/src/index.ts

@@ -1,11 +1,15 @@
 export { captureEvent } from "./capture.js";
-export { createPostHogClient } from "./client.js";
-export { getPersonProperties } from "./properties.js";
+export { createPostHogClient, DEFAULT_HOST } from "./client.js";
+export { derivePrivateHost, getPersonProperties } from "./properties.js";
+export { createPostHogProvider } from "./provider.js";
 export { createPostHogService } from "./service.js";
 export type {
+  AnalyticsProvider,
   CaptureOptions,
   PersonPropertiesCache,
   PersonPropertiesConfig,
+  PersonPropertiesWrite,
+  PostHogAuthTokenAccessor,
   PostHogService,
   PostHogServiceConfig,
 } from "./types.js";

package/src/properties.ts

@@ -4,6 +4,89 @@ const CACHE_PREFIX = "posthog:person:";
 const DEFAULT_TTL = 300;
 const FETCH_TIMEOUT_MS = 10_000;
 
+/**
+ * Derive the private (app) API host from a capture/ingestion host by
+ * stripping PostHog Cloud's `.i.` ingestion label:
+ *
+ *   https://eu.i.posthog.com → https://eu.posthog.com
+ *   https://us.i.posthog.com → https://us.posthog.com
+ *
+ * Self-hosted instances serve both planes on one host, so anything that
+ * doesn't match the Cloud ingestion pattern passes through unchanged.
+ */
+export function derivePrivateHost(host: string): string {
+  return host.replace(/^(https?:\/\/[a-z0-9-]+)\.i\.(posthog\.com)/i, "$1.$2");
+}
+
+/**
+ * Resolve the project id for environment-scoped private endpoints via
+ * `GET /api/projects/@current/` (the personal key's scoped project). Returns
+ * undefined on any failure — callers soft-fail.
+ */
+async function discoverProjectId(opts: {
+  privateHost: string;
+  token: string;
+}): Promise<string | undefined> {
+  try {
+    const response = await fetch(
+      new URL("/api/projects/@current/", opts.privateHost).toString(),
+      {
+        headers: {
+          Authorization: `Bearer ${opts.token}`,
+          Accept: "application/json",
+        },
+        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+      },
+    );
+    if (!response.ok) return undefined;
+    const data = (await response.json()) as { id?: number | string };
+    return data.id !== undefined ? String(data.id) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Per-(host,credential) one-shot project-id discovery, shared across calls. */
+const projectIdCache = new Map<string, Promise<string | undefined>>();
+
+function resolveProjectId(opts: {
+  privateHost: string;
+  token: string;
+  /**
+   * Cache identity, NOT the bearer token: OAuth access tokens rotate every
+   * ~10h, so keying on `token` would re-discover after every refresh. Callers
+   * pass the (stable) personal key or a fixed "oauth" marker.
+   */
+  cacheKey: string;
+  projectId?: string;
+}): Promise<string | undefined> {
+  if (opts.projectId) return Promise.resolve(opts.projectId);
+  const cacheKey = `${opts.privateHost}::${opts.cacheKey}`;
+  let pending = projectIdCache.get(cacheKey);
+  if (!pending) {
+    pending = discoverProjectId(opts).then((id) => {
+      // Don't cache a failed discovery — let the next call retry.
+      if (id === undefined) projectIdCache.delete(cacheKey);
+      return id;
+    });
+    projectIdCache.set(cacheKey, pending);
+  }
+  return pending;
+}
+
+/**
+ * Person-property READ via PostHog's private API.
+ *
+ * Requires a privileged credential (scope `person:read`) — the `phc_` project
+ * key is write-only by design (it ships in browser bundles) and can never
+ * read. An OAuth token (via `getAuthToken`) is preferred; `personalApiKey` is
+ * the fallback. With NEITHER configured this resolves `{}` immediately (reads
+ * disabled); the engine's timezone fallbacks (contact properties → client
+ * default) take over. All upstream errors also soft-fail to `{}`.
+ *
+ * The private API lives on the APP host (`eu.posthog.com`), not the
+ * ingestion host (`eu.i.posthog.com`) — derived via {@link derivePrivateHost}.
+ */
 export async function getPersonProperties(opts: {
   config: PersonPropertiesConfig;
   distinctId: string;
@@ -11,6 +94,8 @@ export async function getPersonProperties(opts: {
 }): Promise<Record<string, unknown>> {
   const { config, distinctId, cache } = opts;
 
+  if (!config.personalApiKey && !config.getAuthToken) return {};
+
   if (cache) {
     try {
       const cached = await cache.redis.get(`${CACHE_PREFIX}${distinctId}`);
@@ -22,15 +107,34 @@ export async function getPersonProperties(opts: {
     }
   }
 
-  const url = new URL("/api/persons/", config.host);
-  url.searchParams.set("distinct_id", distinctId);
+  const privateHost = config.privateHost ?? derivePrivateHost(config.host);
 
   let properties: Record<string, unknown> = {};
 
   try {
+    // OAuth preferred, personal key fallback — a revoked/failed OAuth
+    // credential degrades to the personal key for free.
+    const oauthToken = config.getAuthToken ? await config.getAuthToken() : null;
+    const token = oauthToken ?? config.personalApiKey;
+    if (!token) return {};
+
+    const projectId = await resolveProjectId({
+      privateHost,
+      token,
+      cacheKey: config.personalApiKey ?? "oauth",
+      projectId: config.projectId,
+    });
+    if (!projectId) return {};
+
+    const url = new URL(
+      `/api/environments/${encodeURIComponent(projectId)}/persons/`,
+      privateHost,
+    );
+    url.searchParams.set("distinct_id", distinctId);
+
     const response = await fetch(url.toString(), {
       headers: {
-        Authorization: `Bearer ${config.apiKey}`,
+        Authorization: `Bearer ${token}`,
         Accept: "application/json",
       },
       signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),

package/src/provider.ts

@@ -0,0 +1,95 @@
+import { type AnalyticsProvider, defineAnalyticsProvider } from "@hogsend/core";
+import { captureEvent } from "./capture.js";
+import { createPostHogClient, DEFAULT_HOST } from "./client.js";
+import { getPersonProperties } from "./properties.js";
+import type {
+  PersonPropertiesCache,
+  PersonPropertiesConfig,
+  PostHogServiceConfig,
+} from "./types.js";
+
+/**
+ * The PostHog implementation of the neutral `AnalyticsProvider` contract —
+ * the reference implementation, the way `createResendProvider` is for email.
+ *
+ * Credential split (PostHog's design, not Hogsend's):
+ * - **capture + person WRITES** use the public project key (`apiKey`) — person
+ *   writes ride the capture pipeline as `$set`/`$set_once`, so propagation
+ *   needs NO extra credential.
+ * - **person READS** need a privileged credential against the private API
+ *   host: an engine-injected OAuth accessor (`authToken`, preferred) or
+ *   `personalApiKey` (a personal API key scoped `person:read`, the fallback).
+ *   With neither, `capabilities.personReads` is false and reads soft-fail to
+ *   `{}` — the engine falls back to contact properties for timezone
+ *   resolution.
+ */
+export function createPostHogProvider(
+  config: PostHogServiceConfig,
+): AnalyticsProvider {
+  const host = config.host ?? DEFAULT_HOST;
+  const client = createPostHogClient({ apiKey: config.apiKey, host });
+  const authToken = config.authToken;
+
+  const propsConfig: PersonPropertiesConfig = {
+    personalApiKey: config.personalApiKey,
+    getAuthToken: authToken ? () => authToken.getToken() : undefined,
+    host,
+    privateHost: config.privateHost,
+    projectId: config.projectId,
+  };
+
+  const propsCache: PersonPropertiesCache | undefined = config.redis
+    ? { redis: config.redis, ttlSeconds: config.cacheTtlSeconds ?? 300 }
+    : undefined;
+
+  return defineAnalyticsProvider({
+    meta: {
+      id: "posthog",
+      name: "PostHog",
+      description:
+        "PostHog capture + person reads/writes (reads need a personal API key).",
+    },
+    capabilities: {
+      // LIVE getter: the container builds providers at BOOT, but the OAuth
+      // credential can be stored at RUNTIME via `hogsend connect posthog`.
+      // A getter means every reader (boot nudge, doctor, future Studio
+      // status) sees current truth without rebuilding the provider.
+      get personReads() {
+        return (
+          Boolean(config.personalApiKey) || (authToken?.isAvailable() ?? false)
+        );
+      },
+      personWrites: true,
+      oauth: true,
+    },
+
+    async getPersonProperties(distinctId: string) {
+      return getPersonProperties({
+        config: propsConfig,
+        distinctId,
+        cache: propsCache,
+      });
+    },
+
+    async setPersonProperties({ distinctId, set, setOnce, unset }) {
+      if (!set && !setOnce && !unset?.length) return;
+      client.capture({
+        distinctId,
+        event: "$set",
+        properties: {
+          ...(set ? { $set: set } : {}),
+          ...(setOnce ? { $set_once: setOnce } : {}),
+          ...(unset?.length ? { $unset: unset } : {}),
+        },
+      });
+    },
+
+    capture(opts) {
+      captureEvent({ client, ...opts });
+    },
+
+    async shutdown() {
+      await client.shutdown();
+    },
+  });
+}

package/src/service.ts

@@ -9,6 +9,13 @@ import type {
   PostHogServiceConfig,
 } from "./types.js";
 
+/**
+ * @deprecated Prefer {@link createPostHogProvider} (the neutral
+ * `AnalyticsProvider` contract). This PostHog-shaped service predates it and
+ * is kept so existing `createHogsendClient({ analytics })` call sites and
+ * `getPostHog()` consumers keep compiling; person reads honour the same
+ * `personalApiKey` config as the provider.
+ */
 export function createPostHogService(
   config: PostHogServiceConfig,
 ): PostHogService {
@@ -16,8 +23,10 @@ export function createPostHogService(
   const client = createPostHogClient({ apiKey: config.apiKey, host });
 
   const propsConfig: PersonPropertiesConfig = {
-    apiKey: config.apiKey,
+    personalApiKey: config.personalApiKey,
     host,
+    privateHost: config.privateHost,
+    projectId: config.projectId,
   };
 
   const propsCache: PersonPropertiesCache | undefined = config.redis

package/src/types.ts

@@ -1,20 +1,70 @@
 import type { Redis } from "ioredis";
 
+/**
+ * Engine-injected OAuth auth accessor. `getToken()` resolves a live bearer
+ * token (or null — degrade); `isAvailable()` is the synchronous best-known
+ * credential state, used for live capability reporting. The plugin stays a
+ * dumb wire: it neither refreshes nor stores anything.
+ */
+export interface PostHogAuthTokenAccessor {
+  getToken(): Promise<string | null>;
+  isAvailable(): boolean;
+}
+
 export interface PostHogServiceConfig {
+  /** Project API key (`phc_…`) — capture/flags. Public + WRITE-ONLY by design. */
   apiKey: string;
+  /** Capture/ingestion host, e.g. `https://eu.i.posthog.com`. */
   host?: string;
+  /**
+   * Personal API key (scoped `person:read`; add `person:write` for future
+   * private-API writes). Person READS are disabled without it: the `phc_`
+   * project key cannot read the private API — it ships in every browser
+   * bundle, so PostHog makes it write-only (otherwise anyone could dump your
+   * persons). See the "Analytics access" docs page.
+   */
+  personalApiKey?: string;
+  /**
+   * Private (app) API host. Defaults to the capture host with the `.i.`
+   * ingestion label stripped (`eu.i.posthog.com` → `eu.posthog.com`).
+   * Self-hosted instances usually serve both on one host — set explicitly
+   * if yours differs.
+   */
+  privateHost?: string;
+  /**
+   * PostHog project id for the environment-scoped private endpoints. When
+   * absent it is discovered once via `GET /api/projects/@current/` with the
+   * personal key, then cached for the process lifetime.
+   */
+  projectId?: string;
   redis?: Redis;
   cacheTtlSeconds?: number;
+  /** OAuth accessor — preferred over `personalApiKey` when it yields a token. */
+  authToken?: PostHogAuthTokenAccessor;
 }
 
 // The analytics-provider contract now lives in the neutral @hogsend/core
 // package. These re-exports keep every existing
 // `import ... from "@hogsend/plugin-posthog"` working unchanged.
-export type { CaptureOptions, PostHogService } from "@hogsend/core";
+export type {
+  AnalyticsProvider,
+  CaptureOptions,
+  PersonPropertiesWrite,
+  PostHogService,
+} from "@hogsend/core";
 
 export interface PersonPropertiesConfig {
-  apiKey: string;
+  /** Personal API key — fallback when OAuth yields no token. Reads are
+   *  DISABLED (soft-fail `{}`) when BOTH this and `getAuthToken` are absent. */
+  personalApiKey?: string;
+  /** Async OAuth token resolver (the accessor's getToken, pre-bound). */
+  getAuthToken?: () => Promise<string | null>;
+  /** Capture/ingestion host (private host is derived from it). */
   host: string;
+  /** Private API host override. */
+  privateHost?: string;
+  /** Project id override (skips `@current` discovery). */
+  projectId?: string;
 }
 
 export interface PersonPropertiesCache {