@hogsend/plugin-posthog 0.19.0 → 0.21.0

package/package.json

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

package/src/index.ts

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

package/src/properties.ts

@@ -25,14 +25,14 @@ export function derivePrivateHost(host: string): string {
  */
 async function discoverProjectId(opts: {
   privateHost: string;
-  personalApiKey: string;
+  token: string;
 }): Promise<string | undefined> {
   try {
     const response = await fetch(
       new URL("/api/projects/@current/", opts.privateHost).toString(),
       {
         headers: {
-          Authorization: `Bearer ${opts.personalApiKey}`,
+          Authorization: `Bearer ${opts.token}`,
           Accept: "application/json",
         },
         signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
@@ -46,16 +46,22 @@ async function discoverProjectId(opts: {
   }
 }
 
-/** Per-(host,key) one-shot project-id discovery, shared across calls. */
+/** Per-(host,credential) one-shot project-id discovery, shared across calls. */
 const projectIdCache = new Map<string, Promise<string | undefined>>();
 
 function resolveProjectId(opts: {
   privateHost: string;
-  personalApiKey: 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.personalApiKey}`;
+  const cacheKey = `${opts.privateHost}::${opts.cacheKey}`;
   let pending = projectIdCache.get(cacheKey);
   if (!pending) {
     pending = discoverProjectId(opts).then((id) => {
@@ -71,11 +77,12 @@ function resolveProjectId(opts: {
 /**
  * Person-property READ via PostHog's private API.
  *
- * Requires a PERSONAL API key (scope `person:read`) — the `phc_` project key
- * is write-only by design (it ships in browser bundles) and can never read.
- * Without `personalApiKey` this resolves `{}` immediately (reads disabled);
- * the engine's timezone fallbacks (contact properties → client default) take
- * over. All upstream errors also soft-fail to `{}`.
+ * 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}.
@@ -87,7 +94,7 @@ export async function getPersonProperties(opts: {
 }): Promise<Record<string, unknown>> {
   const { config, distinctId, cache } = opts;
 
-  if (!config.personalApiKey) return {};
+  if (!config.personalApiKey && !config.getAuthToken) return {};
 
   if (cache) {
     try {
@@ -105,9 +112,16 @@ export async function getPersonProperties(opts: {
   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,
-      personalApiKey: config.personalApiKey,
+      token,
+      cacheKey: config.personalApiKey ?? "oauth",
       projectId: config.projectId,
     });
     if (!projectId) return {};
@@ -120,7 +134,7 @@ export async function getPersonProperties(opts: {
 
     const response = await fetch(url.toString(), {
       headers: {
-        Authorization: `Bearer ${config.personalApiKey}`,
+        Authorization: `Bearer ${token}`,
         Accept: "application/json",
       },
       signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),

package/src/provider.ts

@@ -16,19 +16,23 @@ import type {
  * - **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 `personalApiKey` (a personal API key scoped
- *   `person:read`) against the private API host. Without it,
- *   `capabilities.personReads` is false and reads soft-fail to `{}` — the
- *   engine falls back to contact properties for timezone resolution.
+ * - **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,
@@ -46,8 +50,17 @@ export function createPostHogProvider(
         "PostHog capture + person reads/writes (reads need a personal API key).",
     },
     capabilities: {
-      personReads: Boolean(config.personalApiKey),
+      // 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) {

package/src/types.ts

@@ -1,5 +1,16 @@
 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;
@@ -28,6 +39,8 @@ export interface PostHogServiceConfig {
   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
@@ -41,8 +54,11 @@ export type {
 } from "@hogsend/core";
 
 export interface PersonPropertiesConfig {
-  /** Personal API key — reads are DISABLED (soft-fail `{}`) without it. */
+  /** 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. */