@keystrokehq/posthog 0.0.1

package/dist/capture.mjs

@@ -0,0 +1,241 @@
+import { createPosthogIngestClient } from "./client.mjs";
+import { captureResponseSchema, propertiesBagSchema } from "./schemas.mjs";
+import { t as posthogOperation } from "./factory-DYDvHOGb.mjs";
+import { z } from "zod";
+
+//#region src/capture.ts
+/**
+* posthog/capture.ts
+*
+* Ingest operations — single event, batch capture, identify, alias, group
+* identify, set person properties, set person properties once. All require
+* the project API key on the credential set (not the personal API key).
+*
+* Docs: https://posthog.com/docs/api/capture
+*/
+const eventNameInput = {
+	event: z.string().min(1),
+	distinctId: z.string().min(1),
+	timestamp: z.iso.datetime().optional(),
+	uuid: z.string().optional(),
+	properties: propertiesBagSchema.optional()
+};
+/**
+* Capture a single analytics event.
+* Maps Sim archive tool S1 (`posthog_capture_event`).
+*/
+const captureEvent = posthogOperation({
+	id: "posthog_capture_event",
+	name: "PostHog Capture Event",
+	description: "Capture a single analytics event via the PostHog /capture endpoint",
+	input: z.object(eventNameInput),
+	output: captureResponseSchema,
+	needsApproval: true,
+	run: async (input, credentials) => {
+		const client = createPosthogIngestClient(credentials);
+		return client.request({
+			method: "POST",
+			path: "/capture/",
+			body: {
+				api_key: client.projectApiKey(),
+				event: input.event,
+				distinct_id: input.distinctId,
+				...input.properties ? { properties: input.properties } : {},
+				...input.timestamp ? { timestamp: input.timestamp } : {},
+				...input.uuid ? { uuid: input.uuid } : {}
+			}
+		});
+	}
+});
+/**
+* Capture a batch of analytics events in one request.
+* Maps Sim archive tool S2 (`posthog_capture_batch_events`).
+*/
+const captureBatch = posthogOperation({
+	id: "posthog_capture_batch_events",
+	name: "PostHog Capture Batch",
+	description: "Capture up to 100 analytics events via the PostHog /batch endpoint",
+	input: z.object({ events: z.array(z.object({
+		event: z.string().min(1),
+		distinct_id: z.string().min(1),
+		properties: propertiesBagSchema.optional(),
+		timestamp: z.iso.datetime().optional(),
+		uuid: z.string().optional()
+	})).min(1) }),
+	output: captureResponseSchema,
+	needsApproval: true,
+	run: async (input, credentials) => {
+		const client = createPosthogIngestClient(credentials);
+		return client.request({
+			method: "POST",
+			path: "/batch/",
+			body: {
+				api_key: client.projectApiKey(),
+				batch: input.events
+			}
+		});
+	}
+});
+/**
+* Identify a person — associates distinct_id with a set of properties.
+* Maps Sim archive tool S3 (`posthog_identify_person`).
+*/
+const identifyPerson = posthogOperation({
+	id: "posthog_identify_person",
+	name: "PostHog Identify Person",
+	description: "Associate a distinct_id with person properties via a $identify event",
+	input: z.object({
+		distinctId: z.string().min(1),
+		properties: propertiesBagSchema.optional(),
+		propertiesOnce: propertiesBagSchema.optional(),
+		timestamp: z.iso.datetime().optional()
+	}),
+	output: captureResponseSchema,
+	needsApproval: true,
+	run: async (input, credentials) => {
+		const client = createPosthogIngestClient(credentials);
+		const properties = {};
+		if (input.properties) properties.$set = input.properties;
+		if (input.propertiesOnce) properties.$set_once = input.propertiesOnce;
+		return client.request({
+			method: "POST",
+			path: "/capture/",
+			body: {
+				api_key: client.projectApiKey(),
+				event: "$identify",
+				distinct_id: input.distinctId,
+				properties,
+				...input.timestamp ? { timestamp: input.timestamp } : {}
+			}
+		});
+	}
+});
+/**
+* Alias a distinct_id to an existing user.
+* Maps Sim archive tool S4 (`posthog_alias_person`).
+*/
+const aliasPerson = posthogOperation({
+	id: "posthog_alias_person",
+	name: "PostHog Alias Person",
+	description: "Merge one distinct_id into another via a $create_alias event",
+	input: z.object({
+		distinctId: z.string().min(1),
+		alias: z.string().min(1),
+		timestamp: z.iso.datetime().optional()
+	}),
+	output: captureResponseSchema,
+	needsApproval: true,
+	run: async (input, credentials) => {
+		const client = createPosthogIngestClient(credentials);
+		return client.request({
+			method: "POST",
+			path: "/capture/",
+			body: {
+				api_key: client.projectApiKey(),
+				event: "$create_alias",
+				distinct_id: input.distinctId,
+				properties: { alias: input.alias },
+				...input.timestamp ? { timestamp: input.timestamp } : {}
+			}
+		});
+	}
+});
+/**
+* Identify a group (multi-tenant properties).
+* Maps Sim archive tool S5 (`posthog_group_identify`).
+*/
+const groupIdentify = posthogOperation({
+	id: "posthog_group_identify",
+	name: "PostHog Group Identify",
+	description: "Attach properties to a group (organization, project, etc.) via $groupidentify",
+	input: z.object({
+		distinctId: z.string().min(1),
+		groupType: z.string().min(1),
+		groupKey: z.string().min(1),
+		groupProperties: propertiesBagSchema.optional(),
+		timestamp: z.iso.datetime().optional()
+	}),
+	output: captureResponseSchema,
+	needsApproval: true,
+	run: async (input, credentials) => {
+		const client = createPosthogIngestClient(credentials);
+		return client.request({
+			method: "POST",
+			path: "/capture/",
+			body: {
+				api_key: client.projectApiKey(),
+				event: "$groupidentify",
+				distinct_id: input.distinctId,
+				properties: {
+					$group_type: input.groupType,
+					$group_key: input.groupKey,
+					$group_set: input.groupProperties ?? {}
+				},
+				...input.timestamp ? { timestamp: input.timestamp } : {}
+			}
+		});
+	}
+});
+/**
+* Set person properties (overwrites prior values).
+* Maps Sim archive tool S6 (`posthog_set_person_properties`).
+*/
+const setPersonProperties = posthogOperation({
+	id: "posthog_set_person_properties",
+	name: "PostHog Set Person Properties",
+	description: "Set (overwrite) properties on a person via a $set event",
+	input: z.object({
+		distinctId: z.string().min(1),
+		properties: propertiesBagSchema,
+		timestamp: z.iso.datetime().optional()
+	}),
+	output: captureResponseSchema,
+	needsApproval: true,
+	run: async (input, credentials) => {
+		const client = createPosthogIngestClient(credentials);
+		return client.request({
+			method: "POST",
+			path: "/capture/",
+			body: {
+				api_key: client.projectApiKey(),
+				event: "$set",
+				distinct_id: input.distinctId,
+				properties: { $set: input.properties },
+				...input.timestamp ? { timestamp: input.timestamp } : {}
+			}
+		});
+	}
+});
+/**
+* Set person properties only if not already set.
+* Maps Sim archive tool S7 (`posthog_set_person_properties_once`).
+*/
+const setPersonPropertiesOnce = posthogOperation({
+	id: "posthog_set_person_properties_once",
+	name: "PostHog Set Person Properties Once",
+	description: "Set properties on a person only if not already set ($set_once)",
+	input: z.object({
+		distinctId: z.string().min(1),
+		properties: propertiesBagSchema,
+		timestamp: z.iso.datetime().optional()
+	}),
+	output: captureResponseSchema,
+	needsApproval: true,
+	run: async (input, credentials) => {
+		const client = createPosthogIngestClient(credentials);
+		return client.request({
+			method: "POST",
+			path: "/capture/",
+			body: {
+				api_key: client.projectApiKey(),
+				event: "$set",
+				distinct_id: input.distinctId,
+				properties: { $set_once: input.properties },
+				...input.timestamp ? { timestamp: input.timestamp } : {}
+			}
+		});
+	}
+});
+
+//#endregion
+export { aliasPerson, captureBatch, captureEvent, groupIdentify, identifyPerson, setPersonProperties, setPersonPropertiesOnce };

package/dist/client.d.mts

@@ -0,0 +1,51 @@
+import { t as PosthogCredentials } from "./integration-CsCBBu4d.mjs";
+import { JsonRestMethod, JsonRestQueryValue } from "@keystrokehq/integration-authoring/http";
+
+//#region src/client.d.ts
+/**
+ * Derive the ingest host (for `/capture`, `/batch`, `/decide`) from the
+ * management host. For cloud regions we swap to the `*.i.posthog.com`
+ * ingest origin; for self-hosted installs we reuse the configured host.
+ */
+declare function deriveIngestHost(managementHost: string): string;
+interface PosthogRequestOptions {
+  readonly method: JsonRestMethod;
+  readonly path: string;
+  readonly body?: unknown;
+  readonly query?: Record<string, JsonRestQueryValue>;
+  readonly headers?: Record<string, string>;
+}
+interface PosthogManagementClient {
+  readonly request: <T = unknown>(options: PosthogRequestOptions) => Promise<T>;
+  /** Resolve the project id required by most `/api/projects/{id}/...` paths. */
+  readonly projectId: (override?: string | number) => string;
+  /**
+   * Walk a PostHog cursor-paginated list endpoint, yielding each page in
+   * order. Stops when `response.next` is null.
+   */
+  readonly paginate: <TItem>(initial: PosthogRequestOptions, parsePage?: (page: PaginatedResponse<TItem>) => PaginatedResponse<TItem>) => AsyncGenerator<PaginatedResponse<TItem>, void, void>;
+  /** Collect every page of a cursor-paginated list into a single array. */
+  readonly listAll: <TItem>(initial: PosthogRequestOptions) => Promise<TItem[]>;
+}
+interface PaginatedResponse<TItem> {
+  readonly next: string | null;
+  readonly previous: string | null;
+  readonly count: number;
+  readonly results: TItem[];
+}
+/**
+ * Build the management client. Uses the personal API key as a bearer
+ * token. Throws immediately if the caller attempts an ingest path to
+ * prevent accidental token mixing.
+ */
+declare function createPosthogManagementClient(credentials: PosthogCredentials, fetchImpl?: typeof fetch): PosthogManagementClient;
+interface PosthogIngestClient {
+  readonly request: <T = unknown>(options: PosthogRequestOptions) => Promise<T>;
+  /** Return the project API key, throwing a typed error if it is not set. */
+  readonly projectApiKey: () => string;
+}
+declare function createPosthogIngestClient(credentials: PosthogCredentials, fetchImpl?: typeof fetch): PosthogIngestClient;
+type PosthogDecideClient = PosthogIngestClient;
+declare function createPosthogDecideClient(credentials: PosthogCredentials, fetchImpl?: typeof fetch): PosthogDecideClient;
+//#endregion
+export { PaginatedResponse, PosthogDecideClient, PosthogIngestClient, PosthogManagementClient, PosthogRequestOptions, createPosthogDecideClient, createPosthogIngestClient, createPosthogManagementClient, deriveIngestHost };

package/dist/client.mjs

@@ -0,0 +1,200 @@
+import { PosthogClientError, classifyHttpFailure } from "./errors.mjs";
+import { createJsonRestClient, isJsonRestError } from "@keystrokehq/integration-authoring/http";
+
+//#region src/client.ts
+/**
+* posthog/client.ts
+*
+* Three narrowly-scoped client helpers. Each sees only the tokens and
+* hosts it needs. Cross-token leakage is impossible at the module
+* boundary because capture/decide and management endpoints live behind
+* different factories that receive different credential projections.
+*
+* - `createPosthogManagementClient(credentials)` — bearer = personal API
+*   key; base = `POSTHOG_HOST`; covers `/api/**`.
+* - `createPosthogIngestClient(credentials)` — no bearer; base = derived
+*   ingest host; covers `/capture/` and `/batch/`; enforces project key.
+* - `createPosthogDecideClient(credentials)` — no bearer; base = derived
+*   ingest host; covers `/decide/`; enforces project key.
+*
+* Pagination helpers are exposed for cursor-style list endpoints that
+* return `{ next, previous, count, results }`.
+*/
+const US_CLOUD = "https://us.posthog.com";
+const EU_CLOUD = "https://eu.posthog.com";
+const US_INGEST = "https://us.i.posthog.com";
+const EU_INGEST = "https://eu.i.posthog.com";
+/**
+* Derive the ingest host (for `/capture`, `/batch`, `/decide`) from the
+* management host. For cloud regions we swap to the `*.i.posthog.com`
+* ingest origin; for self-hosted installs we reuse the configured host.
+*/
+function deriveIngestHost(managementHost) {
+	const normalized = stripTrailingSlash(managementHost);
+	if (normalized === US_CLOUD) return US_INGEST;
+	if (normalized === EU_CLOUD) return EU_INGEST;
+	return normalized;
+}
+function stripTrailingSlash(value) {
+	return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+function resolveHost(credentials) {
+	return stripTrailingSlash(credentials.POSTHOG_HOST);
+}
+/**
+* Wrap a raw `JsonRestClient` so every non-2xx failure is re-thrown as
+* a structured `PosthogClientError`. We preserve the original error's
+* status/headers/body while normalizing the shape for callers.
+*/
+function wrapRequest(raw, errorPrefix) {
+	const request = async (options) => {
+		try {
+			return await raw.request(options);
+		} catch (err) {
+			if (isJsonRestError(err)) throw classifyHttpFailure({
+				status: err.status,
+				statusText: err.statusText,
+				body: err.body,
+				headers: err.headers,
+				errorPrefix
+			});
+			throw err;
+		}
+	};
+	return { request };
+}
+/**
+* Build the management client. Uses the personal API key as a bearer
+* token. Throws immediately if the caller attempts an ingest path to
+* prevent accidental token mixing.
+*/
+function createPosthogManagementClient(credentials, fetchImpl) {
+	const wrapped = wrapRequest(createJsonRestClient({
+		baseUrl: resolveHost(credentials),
+		errorPrefix: "PostHog management API error",
+		authHeaders: () => ({ Authorization: `Bearer ${credentials.POSTHOG_PERSONAL_API_KEY}` }),
+		...fetchImpl ? { fetchImpl } : {}
+	}), "PostHog management API error");
+	const guarded = async (options) => {
+		if (isIngestPath(options.path)) throw new PosthogClientError({
+			kind: "bad_credential_shape",
+			message: `PostHog management client cannot call ingest path: ${options.path}`,
+			status: null,
+			providerCode: "WRONG_CLIENT",
+			detail: `Use createPosthogIngestClient or createPosthogDecideClient for ${options.path}`,
+			requestId: null,
+			retryable: false
+		});
+		return wrapped.request(options);
+	};
+	const projectId = (override) => {
+		if (override !== void 0 && override !== null && String(override).length > 0) return String(override);
+		const stored = credentials.POSTHOG_PROJECT_ID;
+		if (!stored) throw new PosthogClientError({
+			kind: "bad_credential_shape",
+			message: "PostHog project id is required. Provide POSTHOG_PROJECT_ID on the credential or pass it explicitly.",
+			status: null,
+			providerCode: "MISSING_PROJECT_ID",
+			detail: "POSTHOG_PROJECT_ID was not set on the credential and no explicit id was provided.",
+			requestId: null,
+			retryable: false
+		});
+		return stored;
+	};
+	async function* paginate(initial, parsePage) {
+		let next = null;
+		let current = initial;
+		while (current) {
+			const page = await guarded(current);
+			const parsed = parsePage ? parsePage(page) : page;
+			yield parsed;
+			next = parsed.next;
+			if (!next) current = null;
+			else {
+				const url = new URL(next);
+				current = {
+					method: "GET",
+					path: `${url.pathname}${url.search}`
+				};
+			}
+		}
+	}
+	const listAll = async (initial) => {
+		const all = [];
+		for await (const page of paginate(initial)) all.push(...page.results);
+		return all;
+	};
+	return {
+		request: guarded,
+		projectId,
+		paginate,
+		listAll
+	};
+}
+function createPosthogIngestClient(credentials, fetchImpl) {
+	return buildIngestLikeClient({
+		credentials,
+		fetchImpl,
+		errorPrefix: "PostHog ingest API error",
+		allowPath: isCapturePath,
+		wrongPathMessage: (path) => `PostHog ingest client cannot call non-capture path: ${path}`
+	});
+}
+function createPosthogDecideClient(credentials, fetchImpl) {
+	return buildIngestLikeClient({
+		credentials,
+		fetchImpl,
+		errorPrefix: "PostHog decide API error",
+		allowPath: isDecidePath,
+		wrongPathMessage: (path) => `PostHog decide client cannot call non-decide path: ${path}`
+	});
+}
+function buildIngestLikeClient(params) {
+	const wrapped = wrapRequest(createJsonRestClient({
+		baseUrl: deriveIngestHost(params.credentials.POSTHOG_HOST),
+		errorPrefix: params.errorPrefix,
+		authHeaders: () => ({}),
+		...params.fetchImpl ? { fetchImpl: params.fetchImpl } : {}
+	}), params.errorPrefix);
+	const guarded = async (options) => {
+		if (!params.allowPath(options.path)) throw new PosthogClientError({
+			kind: "bad_credential_shape",
+			message: params.wrongPathMessage(options.path),
+			status: null,
+			providerCode: "WRONG_CLIENT",
+			detail: params.wrongPathMessage(options.path),
+			requestId: null,
+			retryable: false
+		});
+		return wrapped.request(options);
+	};
+	const projectApiKey = () => {
+		const key = params.credentials.POSTHOG_PROJECT_API_KEY;
+		if (!key) throw new PosthogClientError({
+			kind: "bad_credential_shape",
+			message: "PostHog project API key is required for capture/decide calls. Set POSTHOG_PROJECT_API_KEY on the credential set.",
+			status: null,
+			providerCode: "MISSING_PROJECT_API_KEY",
+			detail: "POSTHOG_PROJECT_API_KEY was not set on the credential set.",
+			requestId: null,
+			retryable: false
+		});
+		return key;
+	};
+	return {
+		request: guarded,
+		projectApiKey
+	};
+}
+function isIngestPath(path) {
+	return isCapturePath(path) || isDecidePath(path);
+}
+function isCapturePath(path) {
+	return path.startsWith("/capture") || path.startsWith("/batch");
+}
+function isDecidePath(path) {
+	return path.startsWith("/decide");
+}
+
+//#endregion
+export { createPosthogDecideClient, createPosthogIngestClient, createPosthogManagementClient, deriveIngestHost };