@theholocron/holocron-plugin-posthog 5.0.0-alpha.278 → 5.0.0-alpha.279

package/dist/index.d.mts

@@ -1,25 +1,32 @@
 import { Analytics, AuthError, PluginToken, ResolveTokenInput, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
 import { PostHogClient, PostHogClient as PostHogClient$1, PostHogClientOptions, PostHogProject, PostHogProjectsResponse, PostHogUser, createPostHogClient } from "@theholocron/posthog-client";
+/** Resolves the PostHog personal API key from `--token`, `HOLOCRON_POSTHOG_TOKEN`, `POSTHOG_PERSONAL_API_KEY` or the keyring, and throws an `AuthError` when none is set. */
 export declare const resolveToken: import("@theholocron/cli").TokenResolver;
 /** Every token this plugin takes, for `holocron doctor tokens`. */
 export declare const tokens: PluginToken[];
+/** Options for the PostHog `analytics` capability. */
 interface PostHogAnalyticsOptions {
   /** PostHog instance host — pushed as NEXT_PUBLIC_POSTHOG_HOST. Default: https://app.posthog.com */
   host?: string;
 }
+/** The `analytics` capability for PostHog: finds or creates a project and reports its API token. */
 export declare class PostHogAnalytics implements Analytics {
   private readonly client;
   private readonly opts;
+  /** The capability key, always `analytics`. */
   readonly key: "analytics";
+  /** The provider name, `posthog`. */
   readonly providerName = "posthog";
   constructor(client: () => PostHogClient$1, opts: PostHogAnalyticsOptions);
   describe(): Promise<{
     provider: string;
     envKeys: string[];
   }>;
+  /** Returns the organization slug of the user the token belongs to. */
   whoami(): Promise<{
     org: string;
   }>;
+  /** Returns the API token of the project called `name`, creating the project when it does not exist yet; `alreadyExists` says which happened. */
   ensureProject(name: string): Promise<{
     token: string;
     alreadyExists: boolean;
@@ -32,7 +39,9 @@ interface VerifyTokenOptions {
   baseUrl?: string;
   fetch?: typeof fetch;
 }
+/** Checks a PostHog personal API key by fetching the current user; the success subject is `email @ organization slug`, the failure carries the error message. */
 export declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
+/** Options for the PostHog plugin: token resolution, the instance host and test overrides. */
 export interface PostHogPluginOptions extends ResolveTokenInput, PostHogAnalyticsOptions {
   /**
    * PostHog instance host. Defaults to US cloud.
@@ -42,14 +51,21 @@ export interface PostHogPluginOptions extends ResolveTokenInput, PostHogAnalytic
   host?: string;
   /** Override base URL for tests (takes precedence over host). */
   baseUrl?: string;
+  /** Override `fetch` for tests. */
   fetch?: typeof fetch;
 }
+/** What the plugin's capabilities share: the options and a lazily built client. */
 export interface PluginContext {
+  /** The options the plugin was created with. */
   options: PostHogPluginOptions;
+  /** Builds the PostHog client on first call and reuses it; the token is resolved then, not at plugin load. */
   client: () => PostHogClient$1;
 }
+/** Creates the shared context for the given options; no token is resolved until `client()` is first called. */
 export declare function createContext(options?: PostHogPluginOptions): PluginContext;
+/** Builds the `analytics` capability from a plugin context. */
 export declare function analytics(ctx: PluginContext): Analytics;
+/** Creates the PostHog plugin: a `connection` probe and the `analytics` capability. */
 export declare function createPlugin(options?: PostHogPluginOptions): {
   name: string;
   probes: {
@@ -59,5 +75,6 @@ export declare function createPlugin(options?: PostHogPluginOptions): {
     analytics: () => Analytics;
   };
 };
+/** One-line hint shown by `holocron auth set posthog` when no token is given or the token is rejected. */
 export declare const AUTH_HINT: string;
 export { AuthError, type PostHogAnalyticsOptions, type PostHogClient, type PostHogClientOptions, type PostHogProject, type PostHogProjectsResponse, type PostHogUser, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createPostHogClient };

package/dist/index.mjs

@@ -2,6 +2,7 @@ import { AuthError, connectionProbe, createResolveToken } from "@theholocron/cli
 import { createPostHogClient, createPostHogClient as createPostHogClient$1 } from "@theholocron/posthog-client";
 import { errorMessage } from "@theholocron/misc-utils";
 // src/auth.ts
+/** Resolves the PostHog personal API key from `--token`, `HOLOCRON_POSTHOG_TOKEN`, `POSTHOG_PERSONAL_API_KEY` or the keyring, and throws an `AuthError` when none is set. */
 const resolveToken = createResolveToken({
 	envName: "HOLOCRON_POSTHOG_TOKEN",
 	vendorEnvName: "POSTHOG_PERSONAL_API_KEY",
@@ -11,10 +12,13 @@ const resolveToken = createResolveToken({
 /** Every token this plugin takes, for `holocron doctor tokens`. */
 const tokens = [resolveToken.token];
 // src/capabilities/analytics.ts
+/** The `analytics` capability for PostHog: finds or creates a project and reports its API token. */
 var PostHogAnalytics = class {
 	client;
 	opts;
+	/** The capability key, always `analytics`. */
 	key = "analytics";
+	/** The provider name, `posthog`. */
 	providerName = "posthog";
 	constructor(client, opts) {
 		this.client = client;
@@ -26,9 +30,11 @@ var PostHogAnalytics = class {
 			envKeys: ["NEXT_PUBLIC_POSTHOG_KEY", "NEXT_PUBLIC_POSTHOG_HOST"]
 		};
 	}
+	/** Returns the organization slug of the user the token belongs to. */
 	async whoami() {
 		return { org: (await this.client().users.me()).organization.slug };
 	}
+	/** Returns the API token of the project called `name`, creating the project when it does not exist yet; `alreadyExists` says which happened. */
 	async ensureProject(name) {
 		const { results } = await this.client().projects.list();
 		const found = results.find((p) => p.name === name);
@@ -47,6 +53,7 @@ var PostHogAnalytics = class {
 	}
 };
 // src/verify-token.ts
+/** Checks a PostHog personal API key by fetching the current user; the success subject is `email @ organization slug`, the failure carries the error message. */
 async function verifyToken(token, opts = {}) {
 	const client = createPostHogClient$1({
 		token,
@@ -68,6 +75,7 @@ async function verifyToken(token, opts = {}) {
 	}
 }
 // src/index.ts
+/** Creates the shared context for the given options; no token is resolved until `client()` is first called. */
 function createContext(options = {}) {
 	let client;
 	return {
@@ -80,9 +88,11 @@ function createContext(options = {}) {
 		})
 	};
 }
+/** Builds the `analytics` capability from a plugin context. */
 function analytics(ctx) {
 	return new PostHogAnalytics(ctx.client, { host: ctx.options.host });
 }
+/** Creates the PostHog plugin: a `connection` probe and the `analytics` capability. */
 function createPlugin(options = {}) {
 	const ctx = createContext(options);
 	return {
@@ -101,5 +111,6 @@ function createPlugin(options = {}) {
 		capabilities: { analytics: () => analytics(ctx) }
 	};
 }
+/** One-line hint shown by `holocron auth set posthog` when no token is given or the token is rejected. */
 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>";
 export { AUTH_HINT, AuthError, PostHogAnalytics, analytics, createContext, createPlugin, createPostHogClient, resolveToken, tokens, verifyToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/holocron-plugin-posthog",
-  "version": "5.0.0-alpha.278",
+  "version": "5.0.0-alpha.279",
   "description": "Holocron plugin for PostHog. Implements the analytics capability — project provisioning and tracking token retrieval.",
   "keywords": [
     "analytics",
@@ -44,17 +44,17 @@
     "tsx": "4.23.15",
     "typescript": "^5.9.3",
     "vitest": "^5.0.5",
-    "@theholocron/cli": "5.0.0-alpha.278",
-    "@theholocron/eslint-config": "^8.9.0-alpha.4",
-    "@theholocron/http-client": "^1.58.0-alpha.3",
     "@theholocron/misc-utils": "^1.16.1-alpha.3",
+    "@theholocron/cli": "5.0.0-alpha.279",
+    "@theholocron/tsdown-config": "^8.9.0-alpha.4",
     "@theholocron/tsconfig": "^8.9.0-alpha.4",
     "@theholocron/vitest-config": "^8.9.0-alpha.4",
-    "@theholocron/tsdown-config": "^8.9.0-alpha.4"
+    "@theholocron/http-client": "^1.58.0-alpha.3",
+    "@theholocron/eslint-config": "^8.9.0-alpha.4"
   },
   "peerDependencies": {
     "@theholocron/misc-utils": "^1.16.0",
-    "@theholocron/cli": "5.0.0-alpha.278"
+    "@theholocron/cli": "5.0.0-alpha.279"
   },
   "engines": {
     "node": ">=22"