@theholocron/holocron-plugin-posthog 5.0.0-alpha.28 → 5.0.0-alpha.280

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +1 -1
  2. package/dist/index.d.mts +33 -28
  3. package/dist/index.mjs +32 -11
  4. package/package.json +20 -18
package/README.md CHANGED
@@ -53,6 +53,6 @@ runtime — the personal key is for management only.
53
53
  | `whoami` | Calls `/api/users/@me/` to verify the token and return the org slug. |
54
54
  | `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`. |
55
55
 
56
- `holocron setup` calls `ensureProject` and pushes `NEXT_PUBLIC_POSTHOG_KEY`
56
+ `holocron repo setup` calls `ensureProject` and pushes `NEXT_PUBLIC_POSTHOG_KEY`
57
57
  (the project `api_token`) and `NEXT_PUBLIC_POSTHOG_HOST` (the resolved
58
58
  `host` value) to GitHub Secrets.
package/dist/index.d.mts CHANGED
@@ -1,26 +1,32 @@
1
+ import { Analytics, AuthError, PluginToken, ResolveTokenInput, VerifyTokenFailure, VerifyTokenResult, VerifyTokenResult as VerifyTokenResult$1, VerifyTokenSuccess } from "@theholocron/cli";
1
2
  import { PostHogClient, PostHogClient as PostHogClient$1, PostHogClientOptions, PostHogProject, PostHogProjectsResponse, PostHogUser, createPostHogClient } from "@theholocron/posthog-client";
2
- import { Analytics, AuthError, ResolveTokenInput } from "@theholocron/cli";
3
- //#region src/auth.d.ts
4
- declare const resolveToken: (input?: ResolveTokenInput) => string;
5
- //#endregion
6
- //#region src/capabilities/analytics.d.ts
3
+ /** 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. */
4
+ export declare const resolveToken: import("@theholocron/cli").TokenResolver;
5
+ /** Every token this plugin takes, for `holocron doctor tokens`. */
6
+ export declare const tokens: PluginToken[];
7
+ /** Options for the PostHog `analytics` capability. */
7
8
  interface PostHogAnalyticsOptions {
8
9
  /** PostHog instance host — pushed as NEXT_PUBLIC_POSTHOG_HOST. Default: https://app.posthog.com */
9
10
  host?: string;
10
11
  }
11
- declare class PostHogAnalytics implements Analytics {
12
+ /** The `analytics` capability for PostHog: finds or creates a project and reports its API token. */
13
+ export declare class PostHogAnalytics implements Analytics {
12
14
  private readonly client;
13
15
  private readonly opts;
16
+ /** The capability key, always `analytics`. */
14
17
  readonly key: "analytics";
18
+ /** The provider name, `posthog`. */
15
19
  readonly providerName = "posthog";
16
20
  constructor(client: () => PostHogClient$1, opts: PostHogAnalyticsOptions);
17
21
  describe(): Promise<{
18
22
  provider: string;
19
23
  envKeys: string[];
20
24
  }>;
25
+ /** Returns the organization slug of the user the token belongs to. */
21
26
  whoami(): Promise<{
22
27
  org: string;
23
28
  }>;
29
+ /** Returns the API token of the project called `name`, creating the project when it does not exist yet; `alreadyExists` says which happened. */
24
30
  ensureProject(name: string): Promise<{
25
31
  token: string;
26
32
  alreadyExists: boolean;
@@ -28,26 +34,15 @@ declare class PostHogAnalytics implements Analytics {
28
34
  /** The host value to push as NEXT_PUBLIC_POSTHOG_HOST. */
29
35
  get resolvedHost(): string;
30
36
  }
31
- //#endregion
32
- //#region src/verify-token.d.ts
33
- interface VerifyTokenSuccess {
34
- ok: true;
35
- subject: string;
36
- }
37
- interface VerifyTokenFailure {
38
- ok: false;
39
- message: string;
40
- }
41
- type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
42
37
  interface VerifyTokenOptions {
43
38
  host?: string;
44
39
  baseUrl?: string;
45
40
  fetch?: typeof fetch;
46
41
  }
47
- declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
48
- //#endregion
49
- //#region src/index.d.ts
50
- interface PostHogPluginOptions extends ResolveTokenInput, PostHogAnalyticsOptions {
42
+ /** Checks a PostHog personal API key by fetching the current user; the success subject is `email @ organization slug`, the failure carries the error message. */
43
+ export declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult$1>;
44
+ /** Options for the PostHog plugin: token resolution, the instance host and test overrides. */
45
+ export interface PostHogPluginOptions extends ResolveTokenInput, PostHogAnalyticsOptions {
51
46
  /**
52
47
  * PostHog instance host. Defaults to US cloud.
53
48
  * EU cloud: "https://eu.posthog.com"
@@ -56,20 +51,30 @@ interface PostHogPluginOptions extends ResolveTokenInput, PostHogAnalyticsOption
56
51
  host?: string;
57
52
  /** Override base URL for tests (takes precedence over host). */
58
53
  baseUrl?: string;
54
+ /** Override `fetch` for tests. */
59
55
  fetch?: typeof fetch;
60
56
  }
61
- interface PluginContext {
57
+ /** What the plugin's capabilities share: the options and a lazily built client. */
58
+ export interface PluginContext {
59
+ /** The options the plugin was created with. */
62
60
  options: PostHogPluginOptions;
61
+ /** Builds the PostHog client on first call and reuses it; the token is resolved then, not at plugin load. */
63
62
  client: () => PostHogClient$1;
64
63
  }
65
- declare function createContext(options?: PostHogPluginOptions): PluginContext;
66
- declare function analytics(ctx: PluginContext): Analytics;
67
- declare function createPlugin(options?: PostHogPluginOptions): {
64
+ /** Creates the shared context for the given options; no token is resolved until `client()` is first called. */
65
+ export declare function createContext(options?: PostHogPluginOptions): PluginContext;
66
+ /** Builds the `analytics` capability from a plugin context. */
67
+ export declare function analytics(ctx: PluginContext): Analytics;
68
+ /** Creates the PostHog plugin: a `connection` probe and the `analytics` capability. */
69
+ export declare function createPlugin(options?: PostHogPluginOptions): {
68
70
  name: string;
71
+ probes: {
72
+ connection: import("@theholocron/cli").Probe;
73
+ };
69
74
  capabilities: {
70
75
  analytics: () => Analytics;
71
76
  };
72
77
  };
73
- declare const AUTH_HINT: string;
74
- //#endregion
75
- export { AUTH_HINT, AuthError, PluginContext, PostHogAnalytics, type PostHogAnalyticsOptions, type PostHogClient, type PostHogClientOptions, PostHogPluginOptions, type PostHogProject, type PostHogProjectsResponse, type PostHogUser, type ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, analytics, createContext, createPlugin, createPostHogClient, resolveToken, verifyToken };
78
+ /** One-line hint shown by `holocron auth set posthog` when no token is given or the token is rejected. */
79
+ export declare const AUTH_HINT: string;
80
+ 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 CHANGED
@@ -1,18 +1,24 @@
1
+ import { AuthError, connectionProbe, createResolveToken } from "@theholocron/cli";
1
2
  import { createPostHogClient, createPostHogClient as createPostHogClient$1 } from "@theholocron/posthog-client";
2
- import { AuthError, createResolveToken } from "@theholocron/cli";
3
- //#region src/auth.ts
3
+ import { errorMessage } from "@theholocron/misc-utils";
4
+ // src/auth.ts
5
+ /** 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. */
4
6
  const resolveToken = createResolveToken({
5
7
  envName: "HOLOCRON_POSTHOG_TOKEN",
6
8
  vendorEnvName: "POSTHOG_PERSONAL_API_KEY",
7
9
  keyringService: "posthog",
8
10
  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>"
9
11
  });
10
- //#endregion
11
- //#region src/capabilities/analytics.ts
12
+ /** Every token this plugin takes, for `holocron doctor tokens`. */
13
+ const tokens = [resolveToken.token];
14
+ // src/capabilities/analytics.ts
15
+ /** The `analytics` capability for PostHog: finds or creates a project and reports its API token. */
12
16
  var PostHogAnalytics = class {
13
17
  client;
14
18
  opts;
19
+ /** The capability key, always `analytics`. */
15
20
  key = "analytics";
21
+ /** The provider name, `posthog`. */
16
22
  providerName = "posthog";
17
23
  constructor(client, opts) {
18
24
  this.client = client;
@@ -24,9 +30,11 @@ var PostHogAnalytics = class {
24
30
  envKeys: ["NEXT_PUBLIC_POSTHOG_KEY", "NEXT_PUBLIC_POSTHOG_HOST"]
25
31
  };
26
32
  }
33
+ /** Returns the organization slug of the user the token belongs to. */
27
34
  async whoami() {
28
35
  return { org: (await this.client().users.me()).organization.slug };
29
36
  }
37
+ /** Returns the API token of the project called `name`, creating the project when it does not exist yet; `alreadyExists` says which happened. */
30
38
  async ensureProject(name) {
31
39
  const { results } = await this.client().projects.list();
32
40
  const found = results.find((p) => p.name === name);
@@ -44,8 +52,8 @@ var PostHogAnalytics = class {
44
52
  return this.opts.host ?? "https://app.posthog.com";
45
53
  }
46
54
  };
47
- //#endregion
48
- //#region src/verify-token.ts
55
+ // src/verify-token.ts
56
+ /** Checks a PostHog personal API key by fetching the current user; the success subject is `email @ organization slug`, the failure carries the error message. */
49
57
  async function verifyToken(token, opts = {}) {
50
58
  const client = createPostHogClient$1({
51
59
  token,
@@ -62,12 +70,12 @@ async function verifyToken(token, opts = {}) {
62
70
  } catch (err) {
63
71
  return {
64
72
  ok: false,
65
- message: err instanceof Error ? err.message : String(err)
73
+ message: errorMessage(err)
66
74
  };
67
75
  }
68
76
  }
69
- //#endregion
70
- //#region src/index.ts
77
+ // src/index.ts
78
+ /** Creates the shared context for the given options; no token is resolved until `client()` is first called. */
71
79
  function createContext(options = {}) {
72
80
  let client;
73
81
  return {
@@ -80,16 +88,29 @@ function createContext(options = {}) {
80
88
  })
81
89
  };
82
90
  }
91
+ /** Builds the `analytics` capability from a plugin context. */
83
92
  function analytics(ctx) {
84
93
  return new PostHogAnalytics(ctx.client, { host: ctx.options.host });
85
94
  }
95
+ /** Creates the PostHog plugin: a `connection` probe and the `analytics` capability. */
86
96
  function createPlugin(options = {}) {
87
97
  const ctx = createContext(options);
88
98
  return {
89
99
  name: "@theholocron/holocron-plugin-posthog",
100
+ probes: { connection: connectionProbe({
101
+ provider: "PostHog",
102
+ url: options.baseUrl ?? options.host ?? "https://app.posthog.com",
103
+ fetch: options.fetch,
104
+ token: () => resolveToken(options),
105
+ verify: (token) => verifyToken(token, {
106
+ host: options.host,
107
+ baseUrl: options.baseUrl,
108
+ fetch: options.fetch
109
+ })
110
+ }) },
90
111
  capabilities: { analytics: () => analytics(ctx) }
91
112
  };
92
113
  }
114
+ /** One-line hint shown by `holocron auth set posthog` when no token is given or the token is rejected. */
93
115
  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>";
94
- //#endregion
95
- export { AUTH_HINT, AuthError, PostHogAnalytics, analytics, createContext, createPlugin, createPostHogClient, resolveToken, verifyToken };
116
+ export { AUTH_HINT, AuthError, PostHogAnalytics, analytics, createContext, createPlugin, createPostHogClient, resolveToken, tokens, verifyToken };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theholocron/holocron-plugin-posthog",
3
- "version": "5.0.0-alpha.28",
3
+ "version": "5.0.0-alpha.280",
4
4
  "description": "Holocron plugin for PostHog. Implements the analytics capability — project provisioning and tracking token retrieval.",
5
5
  "keywords": [
6
6
  "analytics",
@@ -8,12 +8,12 @@
8
8
  "plugin",
9
9
  "posthog"
10
10
  ],
11
- "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-posthog#readme",
11
+ "homepage": "https://docs.theholocron.dev/holocron/plugins/posthog/",
12
12
  "bugs": "https://github.com/theholocron/holocron/issues",
13
13
  "repository": {
14
14
  "type": "git",
15
15
  "url": "git+https://github.com/theholocron/holocron.git",
16
- "directory": "packages/holocron-plugin-posthog"
16
+ "directory": "plugins/holocron-plugin-posthog"
17
17
  },
18
18
  "license": "MIT",
19
19
  "author": "Newton Koumantzelis",
@@ -30,29 +30,31 @@
30
30
  "dist"
31
31
  ],
32
32
  "dependencies": {
33
- "@theholocron/posthog-client": "^1.23.0"
33
+ "@theholocron/posthog-client": "^1.58.0-alpha.3"
34
34
  },
35
35
  "devDependencies": {
36
- "@theholocron/eslint-config": "^8.0.0",
37
- "@theholocron/http-client": "^1.23.0",
38
- "@theholocron/tsconfig": "^8.0.0",
39
- "@theholocron/tsdown-config": "^8.0.0",
40
- "@theholocron/vitest-config": "^8.0.0",
41
36
  "@types/node": "^26",
42
- "@vitest/coverage-v8": "^4.1.11",
37
+ "@vitest/coverage-v8": "^5.0.5",
43
38
  "@vitest/eslint-plugin": "^1.6.27",
44
39
  "chalk": "^6.0.0",
45
40
  "eslint": "^10.8.1",
46
41
  "eslint-plugin-n": "^18.3.0",
47
42
  "globals": "^17.11.0",
48
- "tsdown": "^0.22.14",
49
- "tsx": "4.23.12",
43
+ "tsdown": "^0.23.3",
44
+ "tsx": "4.23.15",
50
45
  "typescript": "^5.9.3",
51
- "vitest": "^4.1.11",
52
- "@theholocron/cli": "5.0.0-alpha.28"
46
+ "vitest": "^5.0.5",
47
+ "@theholocron/eslint-config": "^8.9.0-alpha.4",
48
+ "@theholocron/http-client": "^1.58.0-alpha.3",
49
+ "@theholocron/misc-utils": "^1.16.1-alpha.3",
50
+ "@theholocron/tsdown-config": "^8.9.0-alpha.4",
51
+ "@theholocron/tsconfig": "^8.9.0-alpha.4",
52
+ "@theholocron/cli": "5.0.0-alpha.280",
53
+ "@theholocron/vitest-config": "^8.9.0-alpha.4"
53
54
  },
54
55
  "peerDependencies": {
55
- "@theholocron/cli": "5.0.0-alpha.28"
56
+ "@theholocron/misc-utils": "^1.16.0",
57
+ "@theholocron/cli": "5.0.0-alpha.280"
56
58
  },
57
59
  "engines": {
58
60
  "node": ">=22"
@@ -62,10 +64,10 @@
62
64
  },
63
65
  "scripts": {
64
66
  "delivery.build": "tsdown",
65
- "sourceQuality.staticAnalysis": "holocron run sourceQuality.staticAnalysis --",
67
+ "sourceQuality.staticAnalysis": "eslint .",
66
68
  "test:watch": "vitest",
67
69
  "validate": "tsx scripts/validate.mjs",
68
- "verification.typeSafety": "holocron run verification.typeSafety --",
69
- "verification.unitTests": "holocron run verification.unitTests --"
70
+ "verification.typeSafety": "tsc --noEmit",
71
+ "verification.unitTests": "vitest run"
70
72
  }
71
73
  }