@theholocron/holocron-plugin-posthog 3.25.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Newton Koumantzelis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+<!-- editorconfig-checker-disable-file -->
+
+# `@theholocron/holocron-plugin-posthog`
+
+PostHog plugin for [Holocron](../cli). Implements the `analytics`
+capability against the [PostHog API](https://posthog.com/docs/api) —
+project provisioning and tracking token retrieval.
+
+## Install
+
+<!-- prettier-ignore -->
+```bash
+pnpm add -D @theholocron/holocron-plugin-posthog
+
+```
+
+## Auth
+
+Token resolution order:
+
+1. `--token <KEY>` flag on the holocron invocation
+2. `HOLOCRON_POSTHOG_TOKEN` env var
+3. `POSTHOG_PERSONAL_API_KEY` env var
+
+The token must be a **personal API key** (`phx_*`), found at
+**app.posthog.com → Settings → User → Personal API keys**. This is
+distinct from the project API key (`phc_*`) that the app embeds at
+runtime — the personal key is for management only.
+
+## Config
+
+<!-- prettier-ignore -->
+```jsonc
+{
+  "providers": {
+    "analytics": ["posthog", { "host": "https://eu.posthog.com" }],
+  },
+}
+
+```
+
+- `host` (optional) — PostHog instance base URL. Defaults to the US
+  cloud (`https://app.posthog.com`). Set to `https://eu.posthog.com`
+  for EU cloud or your own URL for self-hosted instances.
+
+## What's implemented
+
+| Method          | What it does                                                                                                                                                                   |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `describe`      | Returns `{ provider: "posthog", envKeys: ["NEXT_PUBLIC_POSTHOG_KEY", "NEXT_PUBLIC_POSTHOG_HOST"] }` — the env vars the app reads at runtime.                                   |
+| `whoami`        | Calls `/api/users/@me/` to verify the token and return the org slug.                                                                                                           |
+| `ensureProject` | Lists projects and returns the existing one if found by name; creates it via `POST /api/projects/` otherwise. Returns the project's `api_token` (`phc_*`) and `alreadyExists`. |
+
+`holocron setup` calls `ensureProject` and pushes `NEXT_PUBLIC_POSTHOG_KEY`
+(the project `api_token`) and `NEXT_PUBLIC_POSTHOG_HOST` (the resolved
+`host` value) to GitHub Secrets.

package/dist/index.d.mts

@@ -0,0 +1,110 @@
+import { Analytics, AuthError, ResolveTokenInput } from "@theholocron/cli";
+//#region src/auth.d.ts
+declare const resolveToken: (input?: ResolveTokenInput) => string;
+//#endregion
+//#region src/rest.d.ts
+interface PostHogClientOptions {
+  token: string;
+  /** PostHog instance host. Default: https://app.posthog.com */
+  host?: string;
+  /** Override base URL for tests (takes precedence over host). */
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+interface PostHogProject {
+  id: number;
+  name: string;
+  api_token: string;
+}
+interface PostHogUser {
+  email: string;
+  organization: {
+    slug: string;
+    name: string;
+  };
+}
+interface PostHogClient {
+  users: {
+    me(): Promise<PostHogUser>;
+  };
+  projects: {
+    list(): Promise<{
+      results: PostHogProject[];
+    }>;
+    create(input: {
+      name: string;
+    }): Promise<PostHogProject>;
+  };
+}
+declare function createPostHogClient({ token, host, baseUrl, fetch: fetchImpl }: PostHogClientOptions): PostHogClient;
+//#endregion
+//#region src/capabilities/analytics.d.ts
+interface PostHogAnalyticsOptions {
+  /** PostHog instance host — pushed as NEXT_PUBLIC_POSTHOG_HOST. Default: https://app.posthog.com */
+  host?: string;
+}
+declare class PostHogAnalytics implements Analytics {
+  private readonly client;
+  private readonly opts;
+  readonly key: "analytics";
+  readonly providerName = "posthog";
+  constructor(client: PostHogClient, opts: PostHogAnalyticsOptions);
+  describe(): Promise<{
+    provider: string;
+    envKeys: string[];
+  }>;
+  whoami(): Promise<{
+    org: string;
+  }>;
+  ensureProject(name: string): Promise<{
+    token: string;
+    alreadyExists: boolean;
+  }>;
+  /** The host value to push as NEXT_PUBLIC_POSTHOG_HOST. */
+  get resolvedHost(): string;
+}
+//#endregion
+//#region src/verify-token.d.ts
+interface VerifyTokenSuccess {
+  ok: true;
+  subject: string;
+}
+interface VerifyTokenFailure {
+  ok: false;
+  message: string;
+}
+type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
+interface VerifyTokenOptions {
+  host?: string;
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
+//#endregion
+//#region src/index.d.ts
+interface PostHogPluginOptions extends ResolveTokenInput, PostHogAnalyticsOptions {
+  /**
+   * PostHog instance host. Defaults to US cloud.
+   * EU cloud: "https://eu.posthog.com"
+   * Self-hosted: your own base URL.
+   */
+  host?: string;
+  /** Override base URL for tests (takes precedence over host). */
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+interface PluginContext {
+  options: PostHogPluginOptions;
+  client: PostHogClient;
+}
+declare function createContext(options?: PostHogPluginOptions): PluginContext;
+declare function analytics(ctx: PluginContext): Analytics;
+declare function createPlugin(options?: PostHogPluginOptions): {
+  name: string;
+  capabilities: {
+    analytics: () => Analytics;
+  };
+};
+declare const AUTH_HINT: string;
+//#endregion
+export { AUTH_HINT, AuthError, PluginContext, PostHogAnalytics, type PostHogAnalyticsOptions, type PostHogClient, type PostHogClientOptions, PostHogPluginOptions, type PostHogProject, type PostHogUser, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, analytics, createContext, createPlugin, createPostHogClient, resolveToken, verifyToken };

package/dist/index.mjs

@@ -0,0 +1,113 @@
+import { AuthError, createResolveToken, createRestClient } from "@theholocron/cli";
+//#region src/auth.ts
+const resolveToken = createResolveToken({
+	envName: "HOLOCRON_POSTHOG_TOKEN",
+	vendorEnvName: "POSTHOG_PERSONAL_API_KEY",
+	keyringService: "posthog",
+	errorMessage: "no PostHog personal API key found. Pass --token <KEY>, set HOLOCRON_POSTHOG_TOKEN / POSTHOG_PERSONAL_API_KEY, or run: holocron auth set posthog <phx_KEY>"
+});
+//#endregion
+//#region src/capabilities/analytics.ts
+var PostHogAnalytics = class {
+	client;
+	opts;
+	key = "analytics";
+	providerName = "posthog";
+	constructor(client, opts) {
+		this.client = client;
+		this.opts = opts;
+	}
+	async describe() {
+		return {
+			provider: "posthog",
+			envKeys: ["NEXT_PUBLIC_POSTHOG_KEY", "NEXT_PUBLIC_POSTHOG_HOST"]
+		};
+	}
+	async whoami() {
+		return { org: (await this.client.users.me()).organization.slug };
+	}
+	async ensureProject(name) {
+		const { results } = await this.client.projects.list();
+		const found = results.find((p) => p.name === name);
+		if (found) return {
+			token: found.api_token,
+			alreadyExists: true
+		};
+		return {
+			token: (await this.client.projects.create({ name })).api_token,
+			alreadyExists: false
+		};
+	}
+	/** The host value to push as NEXT_PUBLIC_POSTHOG_HOST. */
+	get resolvedHost() {
+		return this.opts.host ?? "https://app.posthog.com";
+	}
+};
+//#endregion
+//#region src/rest.ts
+function createPostHogClient({ token, host, baseUrl, fetch: fetchImpl }) {
+	const client = createRestClient({
+		baseUrl: baseUrl ?? host ?? "https://app.posthog.com",
+		token,
+		vendor: "PostHog",
+		fetch: fetchImpl
+	});
+	return {
+		users: { me: () => client.request("/api/users/@me/") },
+		projects: {
+			list: () => client.request("/api/projects/"),
+			create: (input) => client.request("/api/projects/", {
+				method: "POST",
+				body: input
+			})
+		}
+	};
+}
+//#endregion
+//#region src/verify-token.ts
+async function verifyToken(token, opts = {}) {
+	const client = createPostHogClient({
+		token,
+		host: opts.host,
+		baseUrl: opts.baseUrl,
+		fetch: opts.fetch
+	});
+	try {
+		const user = await client.users.me();
+		return {
+			ok: true,
+			subject: `${user.email} @ ${user.organization.slug}`
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+//#endregion
+//#region src/index.ts
+function createContext(options = {}) {
+	return {
+		options,
+		client: createPostHogClient({
+			token: resolveToken(options),
+			host: options.host,
+			baseUrl: options.baseUrl,
+			fetch: options.fetch
+		})
+	};
+}
+function analytics(ctx) {
+	return new PostHogAnalytics(ctx.client, { host: ctx.options.host });
+}
+function createPlugin(options = {}) {
+	const ctx = createContext(options);
+	return {
+		name: "@theholocron/holocron-plugin-posthog",
+		capabilities: { analytics: () => analytics(ctx) }
+	};
+}
+const AUTH_HINT = "create a personal API key at https://app.posthog.com/settings/user/api-keys (not the project API key — that is the client-side phc_* tracking token), then run: holocron auth set posthog <phx_KEY>";
+//#endregion
+export { AUTH_HINT, AuthError, PostHogAnalytics, analytics, createContext, createPlugin, createPostHogClient, resolveToken, verifyToken };

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@theholocron/holocron-plugin-posthog",
+  "version": "3.25.1",
+  "description": "Holocron plugin for PostHog. Implements the analytics capability — project provisioning and tracking token retrieval.",
+  "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-posthog#readme",
+  "bugs": "https://github.com/theholocron/holocron/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theholocron/holocron.git",
+    "directory": "packages/holocron-plugin-posthog"
+  },
+  "license": "MIT",
+  "author": "Newton Koumantzelis",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "peerDependencies": {
+    "@theholocron/cli": "3.26.0"
+  },
+  "devDependencies": {
+    "@theholocron/eslint-config": "^7.19.1",
+    "@theholocron/tsconfig": "^7.19.1",
+    "@theholocron/tsdown-config": "^7.19.1",
+    "@theholocron/vitest-config": "^7.19.1",
+    "@types/node": "^26",
+    "@vitest/coverage-v8": "^4.1.10",
+    "@vitest/eslint-plugin": "^1.6.27",
+    "chalk": "^6.0.0",
+    "eslint": "^10.8.1",
+    "eslint-plugin-n": "^18.3.0",
+    "globals": "^17.9.0",
+    "tsdown": "^0.22.14",
+    "tsx": "4.22.4",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10",
+    "@theholocron/cli": "3.26.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "types": "./dist/index.d.mts",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "validate": "tsx scripts/validate.mjs"
+  }
+}