@voltro/plugin-posthog 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import { AnalyticsEvent } from '@voltro/runtime';
+import { AnalyticsSinkImpl } from '@voltro/runtime';
+import { AnalyticsSinkSpec } from '@voltro/runtime';
+
+export { AnalyticsEvent }
+
+export { AnalyticsSinkImpl }
+
+export { AnalyticsSinkSpec }
+
+export declare const posthogAnalytics: (options: PostHogAnalyticsOptions) => AnalyticsSinkSpec;
+
+export declare interface PostHogAnalyticsOptions {
+    /** PostHog project API key (sometimes called `project_id` token). */
+    readonly apiKey: string;
+    /** API host. Default 'https://app.posthog.com'. Use 'https://eu.posthog.com'
+     *  for the EU cloud or your self-hosted URL. */
+    readonly host?: string;
+    /** Opt into client-side batching (PostHog `/batch/`). Omit for immediate
+     *  per-event `/capture/` delivery. See the batching note in the file
+     *  header for the delivery-semantics trade-off. */
+    readonly batch?: PostHogBatchOptions;
+}
+
+export declare interface PostHogBatchOptions {
+    /** Flush once the buffer reaches this many events. Default 20. */
+    readonly maxSize?: number;
+    /** Flush a non-empty buffer this many ms after the first event lands
+     *  (so low-volume trickles don't sit until shutdown). Default 5000. */
+    readonly flushIntervalMs?: number;
+}
+
+export declare interface PostHogClient {
+    /** POST one event to `/capture/`. */
+    readonly capture: (event: AnalyticsEvent) => Promise<void>;
+    /** POST many events to `/batch/` in one request. */
+    readonly captureBatch: (events: ReadonlyArray<AnalyticsEvent>) => Promise<void>;
+}
+
+export { }

package/dist/index.js

@@ -0,0 +1,104 @@
+import { Effect as e } from "effect";
+import { createLogger as t } from "@voltro/logger";
+import { AnalyticsCapabilityNotSupported as n, AnalyticsError as r } from "@voltro/runtime";
+//#region src/index.ts
+var i = "posthog", a = "https://app.posthog.com", o = 20, s = 5e3, c = t({ scope: "@voltro/plugin-posthog" }), l = (e) => ({
+	event: e.name,
+	distinct_id: e.subjectId ?? "anonymous",
+	timestamp: (e.occurredAt ?? /* @__PURE__ */ new Date()).toISOString(),
+	properties: e.tenantId !== void 0 && e.tenantId !== null ? {
+		...e.properties,
+		$tenant_id: e.tenantId
+	} : e.properties
+}), u = (e) => {
+	let t = e.host ?? a, n = async (e, n) => {
+		let r = await fetch(`${t}${e}`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify(n)
+		});
+		if (!r.ok) {
+			let t = await r.text().catch(() => "");
+			throw Error(`posthog ${e} returned HTTP ${r.status}: ${t}`);
+		}
+	};
+	return {
+		capture: (t) => n("/capture/", {
+			api_key: e.apiKey,
+			...l(t)
+		}),
+		captureBatch: (t) => n("/batch/", {
+			api_key: e.apiKey,
+			batch: t.map(l)
+		})
+	};
+}, d = (e, t) => {
+	let n = [], r, i = () => {
+		r !== void 0 && (clearTimeout(r), r = void 0);
+	}, a = async () => {
+		if (i(), n.length === 0) return;
+		let t = n;
+		n = [];
+		try {
+			await e.captureBatch(t);
+		} catch (e) {
+			c.warn("posthog batch flush failed — dropped events", { dropped: t.length }, e);
+		}
+	};
+	return {
+		add: (e) => {
+			if (n.push(e), n.length >= t.maxSize) {
+				a();
+				return;
+			}
+			r === void 0 && (r = setTimeout(() => {
+				a();
+			}, t.flushIntervalMs), r.unref?.());
+		},
+		flush: a
+	};
+}, f = (t) => {
+	let c = u(t), l = t.host ?? a, f = (t) => e.mapError((e) => new r({
+		provider: i,
+		operation: t,
+		cause: e instanceof Error ? `${e.name}: ${e.message}` : String(e)
+	})), p = (t) => e.fail(new n({
+		provider: i,
+		capability: t
+	})), m = t.batch ? {
+		maxSize: t.batch.maxSize ?? o,
+		flushIntervalMs: t.batch.flushIntervalMs ?? s
+	} : void 0, h = m ? d(c, m) : void 0, g = (t) => h ? e.sync(() => h.add(t)) : e.tryPromise({
+		try: () => c.capture(t),
+		catch: (e) => e
+	}).pipe(f("track")), _ = {
+		info: {
+			provider: i,
+			capabilities: {
+				track: !0,
+				aggregate: !1,
+				timeseries: !1,
+				topN: !1,
+				mirror: !1
+			},
+			detail: {
+				host: l,
+				...m ? { batch: {
+					maxSize: m.maxSize,
+					flushIntervalMs: m.flushIntervalMs
+				} } : {}
+			}
+		},
+		track: g,
+		aggregate: () => p("aggregate"),
+		timeseries: () => p("timeseries"),
+		topN: () => p("topN")
+	};
+	return {
+		kind: "posthog",
+		build: () => _,
+		...h ? { dispose: () => e.promise(() => h.flush()) } : {}
+	};
+};
+//#endregion
+export { f as posthogAnalytics };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@voltro/plugin-posthog",
+  "version": "0.1.0",
+  "description": "PostHog AnalyticsSink — track-only. Forwards events to PostHog's /capture endpoint. Aggregate/timeseries/topN return AnalyticsCapabilityNotSupported because PostHog's analytics live in their UI/SQL, not in a generic API. Compose with another sink for the reads.",
+  "keywords": [
+    "voltro",
+    "typescript",
+    "framework"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://voltro.dev",
+  "bugs": {
+    "email": "support@voltro.dev"
+  },
+  "author": {
+    "name": "Voltro UG",
+    "url": "https://voltro.dev"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@voltro/logger": "0.1.0",
+    "@voltro/runtime": "0.1.0"
+  },
+  "peerDependencies": {
+    "effect": "^3.21.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}