@keystrokehq/posthog 0.0.1

package/dist/dashboards.mjs

@@ -0,0 +1,356 @@
+import { createPosthogManagementClient } from "./client.mjs";
+import { dashboardCollaboratorSchema, dashboardSchema, dashboardTemplateSchema, paginatedResponseSchema, projectIdInputShape, sharingConfigurationSchema } from "./schemas.mjs";
+import { t as posthogOperation } from "./factory-DYDvHOGb.mjs";
+import { z } from "zod";
+
+//#region src/dashboards.ts
+/**
+* posthog/dashboards.ts
+*
+* Dashboard + dashboard templates + collaborators + sharing.
+*
+* Docs: https://posthog.com/docs/api/dashboards
+*/
+const idInput = {
+	...projectIdInputShape,
+	id: z.number().int()
+};
+const writeShape = {
+	name: z.string().optional(),
+	description: z.string().nullable().optional(),
+	pinned: z.boolean().optional(),
+	tags: z.array(z.string()).optional(),
+	filters: z.record(z.string(), z.unknown()).optional(),
+	deleted: z.boolean().optional()
+};
+const listDashboards = posthogOperation({
+	id: "posthog_dashboards_list",
+	name: "PostHog List Dashboards",
+	description: "List dashboards in a project",
+	input: z.object({
+		...projectIdInputShape,
+		limit: z.number().int().min(1).max(500).optional(),
+		offset: z.number().int().min(0).optional(),
+		search: z.string().optional(),
+		pinned: z.boolean().optional()
+	}),
+	output: paginatedResponseSchema(dashboardSchema),
+	run: async (input, credentials) => {
+		const client = createPosthogManagementClient(credentials);
+		const projectId = client.projectId(input.projectId);
+		return client.request({
+			method: "GET",
+			path: `/api/projects/${projectId}/dashboards/`,
+			query: {
+				limit: input.limit,
+				offset: input.offset,
+				search: input.search,
+				pinned: input.pinned
+			}
+		});
+	}
+});
+const getDashboard = posthogOperation({
+	id: "posthog_dashboards_get",
+	name: "PostHog Get Dashboard",
+	description: "Retrieve a dashboard by id",
+	input: z.object(idInput),
+	output: dashboardSchema,
+	run: async (input, credentials) => {
+		const client = createPosthogManagementClient(credentials);
+		const projectId = client.projectId(input.projectId);
+		return client.request({
+			method: "GET",
+			path: `/api/projects/${projectId}/dashboards/${input.id}/`
+		});
+	}
+});
+const createDashboard = posthogOperation({
+	id: "posthog_dashboards_create",
+	name: "PostHog Create Dashboard",
+	description: "Create a new dashboard",
+	input: z.object({
+		...projectIdInputShape,
+		...writeShape,
+		name: z.string().min(1)
+	}),
+	output: dashboardSchema,
+	needsApproval: true,
+	run: async (input, credentials) => {
+		const client = createPosthogManagementClient(credentials);
+		const projectId = client.projectId(input.projectId);
+		const { projectId: _pid, ...body } = input;
+		return client.request({
+			method: "POST",
+			path: `/api/projects/${projectId}/dashboards/`,
+			body
+		});
+	}
+});
+const updateDashboard = posthogOperation({
+	id: "posthog_dashboards_update",
+	name: "PostHog Update Dashboard",
+	description: "Partial update to a dashboard",
+	input: z.object({
+		...idInput,
+		...writeShape
+	}),
+	output: dashboardSchema,
+	needsApproval: true,
+	run: async (input, credentials) => {
+		const client = createPosthogManagementClient(credentials);
+		const projectId = client.projectId(input.projectId);
+		const { projectId: _pid, id, ...body } = input;
+		return client.request({
+			method: "PATCH",
+			path: `/api/projects/${projectId}/dashboards/${id}/`,
+			body
+		});
+	}
+});
+const deleteDashboard = posthogOperation({
+	id: "posthog_dashboards_delete",
+	name: "PostHog Delete Dashboard",
+	description: "Soft-delete a dashboard",
+	input: z.object(idInput),
+	output: dashboardSchema,
+	needsApproval: true,
+	run: async (input, credentials) => {
+		const client = createPosthogManagementClient(credentials);
+		const projectId = client.projectId(input.projectId);
+		return client.request({
+			method: "PATCH",
+			path: `/api/projects/${projectId}/dashboards/${input.id}/`,
+			body: { deleted: true }
+		});
+	}
+});
+const getDashboardSharing = posthogOperation({
+	id: "posthog_dashboards_sharing_get",
+	name: "PostHog Get Dashboard Sharing",
+	description: "Fetch sharing configuration for a dashboard",
+	input: z.object(idInput),
+	output: sharingConfigurationSchema,
+	run: async (input, credentials) => {
+		const client = createPosthogManagementClient(credentials);
+		const projectId = client.projectId(input.projectId);
+		return client.request({
+			method: "GET",
+			path: `/api/projects/${projectId}/dashboards/${input.id}/sharing/`
+		});
+	}
+});
+const updateDashboardSharing = posthogOperation({
+	id: "posthog_dashboards_sharing_update",
+	name: "PostHog Update Dashboard Sharing",
+	description: "Enable or disable sharing for a dashboard",
+	input: z.object({
+		...idInput,
+		enabled: z.boolean()
+	}),
+	output: sharingConfigurationSchema,
+	needsApproval: true,
+	run: async (input, credentials) => {
+		const client = createPosthogManagementClient(credentials);
+		const projectId = client.projectId(input.projectId);
+		return client.request({
+			method: "PATCH",
+			path: `/api/projects/${projectId}/dashboards/${input.id}/sharing/`,
+			body: { enabled: input.enabled }
+		});
+	}
+});
+const listDashboardCollaborators = posthogOperation({
+	id: "posthog_dashboards_collaborators_list",
+	name: "PostHog List Dashboard Collaborators",
+	description: "List collaborators on a dashboard",
+	input: z.object(idInput),
+	output: paginatedResponseSchema(dashboardCollaboratorSchema),
+	run: async (input, credentials) => {
+		const client = createPosthogManagementClient(credentials);
+		const projectId = client.projectId(input.projectId);
+		return client.request({
+			method: "GET",
+			path: `/api/projects/${projectId}/dashboards/${input.id}/collaborators/`
+		});
+	}
+});
+const addDashboardCollaborator = posthogOperation({
+	id: "posthog_dashboards_collaborators_add",
+	name: "PostHog Add Dashboard Collaborator",
+	description: "Add a collaborator to a dashboard",
+	input: z.object({
+		...idInput,
+		user_uuid: z.string().min(1),
+		access_level: z.enum(["can_view", "can_edit"]).default("can_view")
+	}),
+	output: dashboardCollaboratorSchema,
+	needsApproval: true,
+	run: async (input, credentials) => {
+		const client = createPosthogManagementClient(credentials);
+		const projectId = client.projectId(input.projectId);
+		return client.request({
+			method: "POST",
+			path: `/api/projects/${projectId}/dashboards/${input.id}/collaborators/`,
+			body: {
+				user_uuid: input.user_uuid,
+				level: input.access_level
+			}
+		});
+	}
+});
+const removeDashboardCollaborator = posthogOperation({
+	id: "posthog_dashboards_collaborators_remove",
+	name: "PostHog Remove Dashboard Collaborator",
+	description: "Remove a collaborator from a dashboard",
+	input: z.object({
+		...idInput,
+		collaboratorId: z.number().int()
+	}),
+	output: z.object({ success: z.boolean() }),
+	needsApproval: true,
+	run: async (input, credentials) => {
+		const client = createPosthogManagementClient(credentials);
+		const projectId = client.projectId(input.projectId);
+		await client.request({
+			method: "DELETE",
+			path: `/api/projects/${projectId}/dashboards/${input.id}/collaborators/${input.collaboratorId}/`
+		});
+		return { success: true };
+	}
+});
+const listDashboardTemplates = posthogOperation({
+	id: "posthog_dashboard_templates_list",
+	name: "PostHog List Dashboard Templates",
+	description: "List dashboard templates available in a project",
+	input: z.object({
+		...projectIdInputShape,
+		limit: z.number().int().min(1).max(200).optional(),
+		offset: z.number().int().min(0).optional()
+	}),
+	output: paginatedResponseSchema(dashboardTemplateSchema),
+	run: async (input, credentials) => {
+		const client = createPosthogManagementClient(credentials);
+		const projectId = client.projectId(input.projectId);
+		return client.request({
+			method: "GET",
+			path: `/api/projects/${projectId}/dashboard_templates/`,
+			query: {
+				limit: input.limit,
+				offset: input.offset
+			}
+		});
+	}
+});
+const getDashboardTemplate = posthogOperation({
+	id: "posthog_dashboard_templates_get",
+	name: "PostHog Get Dashboard Template",
+	description: "Retrieve a dashboard template by id",
+	input: z.object({
+		...projectIdInputShape,
+		templateId: z.string().min(1)
+	}),
+	output: dashboardTemplateSchema,
+	run: async (input, credentials) => {
+		const client = createPosthogManagementClient(credentials);
+		const projectId = client.projectId(input.projectId);
+		return client.request({
+			method: "GET",
+			path: `/api/projects/${projectId}/dashboard_templates/${input.templateId}/`
+		});
+	}
+});
+const createDashboardTemplate = posthogOperation({
+	id: "posthog_dashboard_templates_create",
+	name: "PostHog Create Dashboard Template",
+	description: "Create a dashboard template from a dashboard",
+	input: z.object({
+		...projectIdInputShape,
+		template_name: z.string().min(1),
+		dashboard_description: z.string().nullable().optional(),
+		dashboard_filters: z.record(z.string(), z.unknown()).nullable().optional(),
+		tags: z.array(z.string()).optional(),
+		tiles: z.array(z.record(z.string(), z.unknown())).optional()
+	}),
+	output: dashboardTemplateSchema,
+	needsApproval: true,
+	run: async (input, credentials) => {
+		const client = createPosthogManagementClient(credentials);
+		const projectId = client.projectId(input.projectId);
+		const { projectId: _pid, ...body } = input;
+		return client.request({
+			method: "POST",
+			path: `/api/projects/${projectId}/dashboard_templates/`,
+			body
+		});
+	}
+});
+const updateDashboardTemplate = posthogOperation({
+	id: "posthog_dashboard_templates_update",
+	name: "PostHog Update Dashboard Template",
+	description: "Partial update to a dashboard template",
+	input: z.object({
+		...projectIdInputShape,
+		templateId: z.string().min(1),
+		template_name: z.string().optional(),
+		dashboard_description: z.string().nullable().optional(),
+		dashboard_filters: z.record(z.string(), z.unknown()).nullable().optional(),
+		tags: z.array(z.string()).optional(),
+		tiles: z.array(z.record(z.string(), z.unknown())).optional(),
+		deleted: z.boolean().optional()
+	}),
+	output: dashboardTemplateSchema,
+	needsApproval: true,
+	run: async (input, credentials) => {
+		const client = createPosthogManagementClient(credentials);
+		const projectId = client.projectId(input.projectId);
+		const { projectId: _pid, templateId, ...body } = input;
+		return client.request({
+			method: "PATCH",
+			path: `/api/projects/${projectId}/dashboard_templates/${templateId}/`,
+			body
+		});
+	}
+});
+const deleteDashboardTemplate = posthogOperation({
+	id: "posthog_dashboard_templates_delete",
+	name: "PostHog Delete Dashboard Template",
+	description: "Delete a dashboard template",
+	input: z.object({
+		...projectIdInputShape,
+		templateId: z.string().min(1)
+	}),
+	output: z.object({ success: z.boolean() }),
+	needsApproval: true,
+	run: async (input, credentials) => {
+		const client = createPosthogManagementClient(credentials);
+		const projectId = client.projectId(input.projectId);
+		await client.request({
+			method: "DELETE",
+			path: `/api/projects/${projectId}/dashboard_templates/${input.templateId}/`
+		});
+		return { success: true };
+	}
+});
+const getDashboardActivity = posthogOperation({
+	id: "posthog_dashboards_activity",
+	name: "PostHog Dashboard Activity",
+	description: "Fetch activity log for a dashboard",
+	input: z.object({
+		...idInput,
+		limit: z.number().int().min(1).max(200).optional()
+	}),
+	output: z.object({ results: z.array(z.record(z.string(), z.unknown())) }),
+	run: async (input, credentials) => {
+		const client = createPosthogManagementClient(credentials);
+		const projectId = client.projectId(input.projectId);
+		return client.request({
+			method: "GET",
+			path: `/api/projects/${projectId}/dashboards/${input.id}/activity/`,
+			query: { limit: input.limit }
+		});
+	}
+});
+
+//#endregion
+export { addDashboardCollaborator, createDashboard, createDashboardTemplate, deleteDashboard, deleteDashboardTemplate, getDashboard, getDashboardActivity, getDashboardSharing, getDashboardTemplate, listDashboardCollaborators, listDashboardTemplates, listDashboards, removeDashboardCollaborator, updateDashboard, updateDashboardSharing, updateDashboardTemplate };

package/dist/decide.d.mts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import * as _keystrokehq_core_credential_set0 from "@keystrokehq/core/credential-set";
+import * as _keystrokehq_core0 from "@keystrokehq/core";
+
+//#region src/decide.d.ts
+/** Evaluate feature flags for a distinct_id (server-side). Maps Sim tool S8. */
+declare const decideFeatureFlags: _keystrokehq_core0.Operation<z.ZodObject<{
+  distinctId: z.ZodString;
+  personProperties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  groups: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  groupProperties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+  version: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+  config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  featureFlags: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodString, z.ZodNumber]>>>;
+  featureFlagPayloads: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  errorsWhileComputingFlags: z.ZodOptional<z.ZodBoolean>;
+  toolbarParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  sessionRecording: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+}, z.core.$strip>, readonly [_keystrokehq_core0.CredentialSet<"posthog", z.ZodObject<{
+  POSTHOG_PERSONAL_API_KEY: z.ZodString;
+  POSTHOG_PROJECT_API_KEY: z.ZodOptional<z.ZodString>;
+  POSTHOG_HOST: z.ZodDefault<z.ZodURL>;
+  POSTHOG_PROJECT_ID: z.ZodOptional<z.ZodString>;
+  POSTHOG_SCOPES: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, readonly _keystrokehq_core_credential_set0.CredentialConnection<z.ZodObject<{
+  POSTHOG_PERSONAL_API_KEY: z.ZodString;
+  POSTHOG_PROJECT_API_KEY: z.ZodOptional<z.ZodString>;
+  POSTHOG_HOST: z.ZodDefault<z.ZodURL>;
+  POSTHOG_PROJECT_ID: z.ZodOptional<z.ZodString>;
+  POSTHOG_SCOPES: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>>[] | undefined>], undefined>;
+/**
+ * Fetch the local-evaluation feature-flag payload for running a local SDK.
+ * Maps Sim tool S9 and Composio slug `manage_project_feature_flags_for_local_evaluation`.
+ */
+declare const decideFeatureFlagsLocal: _keystrokehq_core0.Operation<z.ZodObject<{
+  projectId: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+  sendCohorts: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>, z.ZodObject<{
+  flags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    key: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    filters: z.ZodOptional<z.ZodObject<{
+      groups: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+      multivariate: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+      payloads: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+    deleted: z.ZodOptional<z.ZodBoolean>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    created_at: z.ZodOptional<z.ZodString>;
+    created_by: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    ensure_experience_continuity: z.ZodOptional<z.ZodBoolean>;
+    rollout_percentage: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    version: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strip>>>;
+  group_type_mapping: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  cohorts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, readonly [_keystrokehq_core0.CredentialSet<"posthog", z.ZodObject<{
+  POSTHOG_PERSONAL_API_KEY: z.ZodString;
+  POSTHOG_PROJECT_API_KEY: z.ZodOptional<z.ZodString>;
+  POSTHOG_HOST: z.ZodDefault<z.ZodURL>;
+  POSTHOG_PROJECT_ID: z.ZodOptional<z.ZodString>;
+  POSTHOG_SCOPES: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, readonly _keystrokehq_core_credential_set0.CredentialConnection<z.ZodObject<{
+  POSTHOG_PERSONAL_API_KEY: z.ZodString;
+  POSTHOG_PROJECT_API_KEY: z.ZodOptional<z.ZodString>;
+  POSTHOG_HOST: z.ZodDefault<z.ZodURL>;
+  POSTHOG_PROJECT_ID: z.ZodOptional<z.ZodString>;
+  POSTHOG_SCOPES: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>>[] | undefined>], undefined>;
+//#endregion
+export { decideFeatureFlags, decideFeatureFlagsLocal };

package/dist/decide.mjs

@@ -0,0 +1,75 @@
+import { createPosthogDecideClient, createPosthogManagementClient } from "./client.mjs";
+import { decideResponseSchema, localEvaluationResponseSchema, propertiesBagSchema } from "./schemas.mjs";
+import { t as posthogOperation } from "./factory-DYDvHOGb.mjs";
+import { z } from "zod";
+
+//#region src/decide.ts
+/**
+* posthog/decide.ts
+*
+* Server-side feature-flag evaluation.
+*
+* - `decideFeatureFlags` — hot-path evaluation via `/decide/`
+*   (Sim tool S8). Uses the project API key and returns resolved flag
+*   values plus payloads.
+* - `decideFeatureFlagsLocal` — local-evaluation payload for running a
+*   local SDK (Sim tool S9). Uses the personal API key against
+*   `/api/feature_flag/local_evaluation/`.
+*
+* Docs: https://posthog.com/docs/api/decide
+*/
+/** Evaluate feature flags for a distinct_id (server-side). Maps Sim tool S8. */
+const decideFeatureFlags = posthogOperation({
+	id: "posthog_decide_feature_flags",
+	name: "PostHog Decide Feature Flags",
+	description: "Evaluate all feature flags for a distinct_id via the /decide endpoint",
+	input: z.object({
+		distinctId: z.string().min(1),
+		personProperties: propertiesBagSchema.optional(),
+		groups: z.record(z.string(), z.string()).optional(),
+		groupProperties: z.record(z.string(), propertiesBagSchema).optional(),
+		version: z.number().int().min(1).default(3)
+	}),
+	output: decideResponseSchema,
+	run: async (input, credentials) => {
+		const client = createPosthogDecideClient(credentials);
+		return client.request({
+			method: "POST",
+			path: "/decide/",
+			query: { v: input.version },
+			body: {
+				api_key: client.projectApiKey(),
+				distinct_id: input.distinctId,
+				...input.personProperties ? { person_properties: input.personProperties } : {},
+				...input.groups ? { groups: input.groups } : {},
+				...input.groupProperties ? { group_properties: input.groupProperties } : {}
+			}
+		});
+	}
+});
+/**
+* Fetch the local-evaluation feature-flag payload for running a local SDK.
+* Maps Sim tool S9 and Composio slug `manage_project_feature_flags_for_local_evaluation`.
+*/
+const decideFeatureFlagsLocal = posthogOperation({
+	id: "posthog_decide_feature_flags_local",
+	name: "PostHog Local Evaluation Payload",
+	description: "Fetch the local-evaluation payload for all feature flags in a project",
+	input: z.object({
+		projectId: z.union([z.string(), z.number().int()]).optional(),
+		sendCohorts: z.boolean().default(true)
+	}),
+	output: localEvaluationResponseSchema,
+	run: async (input, credentials) => {
+		const client = createPosthogManagementClient(credentials);
+		const projectId = client.projectId(input.projectId);
+		return client.request({
+			method: "GET",
+			path: `/api/projects/${projectId}/feature_flags/local_evaluation/`,
+			query: { send_cohorts: input.sendCohorts }
+		});
+	}
+});
+
+//#endregion
+export { decideFeatureFlags, decideFeatureFlagsLocal };

package/dist/errors.d.mts

@@ -0,0 +1,58 @@
+//#region src/errors.d.ts
+/**
+ * posthog/errors.ts
+ *
+ * Typed error surface for the PostHog client.
+ *
+ * `PosthogClientError` is a discriminated union on `kind` that wraps
+ * every failure the client can emit. It preserves the HTTP status,
+ * provider-reported error code, request id, and retryability so
+ * callers can make structured decisions rather than string-parsing.
+ */
+type PosthogErrorKind = 'http' | 'rate_limit' | 'auth' | 'validation' | 'bad_credential_shape' | 'region_mismatch';
+interface PosthogClientErrorInit {
+  readonly kind: PosthogErrorKind;
+  readonly message: string;
+  readonly status: number | null;
+  readonly providerCode: string | null;
+  readonly detail: string;
+  readonly requestId: string | null;
+  readonly retryable: boolean;
+  readonly retryAfterMs?: number | null;
+  readonly body?: string;
+}
+/**
+ * Typed error thrown by `createPosthogManagementClient`,
+ * `createPosthogIngestClient`, and `createPosthogDecideClient`.
+ *
+ * Use `isPosthogClientError` to type-narrow and read the `kind` field.
+ */
+declare class PosthogClientError extends Error {
+  readonly name = "PosthogClientError";
+  readonly kind: PosthogErrorKind;
+  readonly status: number | null;
+  readonly providerCode: string | null;
+  readonly detail: string;
+  readonly requestId: string | null;
+  readonly retryable: boolean;
+  readonly retryAfterMs: number | null;
+  readonly body: string;
+  constructor(init: PosthogClientErrorInit);
+}
+/**
+ * Structural type guard. Tolerates cross-realm errors by checking `name`.
+ */
+declare function isPosthogClientError(error: unknown): error is PosthogClientError;
+/**
+ * Classify an HTTP status plus response body into a `PosthogClientError`.
+ * Exposed so the client can convert `JsonRestError` failures uniformly.
+ */
+declare function classifyHttpFailure(params: {
+  status: number;
+  statusText: string;
+  body: string;
+  headers: Headers;
+  errorPrefix: string;
+}): PosthogClientError;
+//#endregion
+export { PosthogClientError, PosthogClientErrorInit, PosthogErrorKind, classifyHttpFailure, isPosthogClientError };

package/dist/errors.mjs

@@ -0,0 +1,120 @@
+//#region src/errors.ts
+/**
+* Typed error thrown by `createPosthogManagementClient`,
+* `createPosthogIngestClient`, and `createPosthogDecideClient`.
+*
+* Use `isPosthogClientError` to type-narrow and read the `kind` field.
+*/
+var PosthogClientError = class extends Error {
+	name = "PosthogClientError";
+	kind;
+	status;
+	providerCode;
+	detail;
+	requestId;
+	retryable;
+	retryAfterMs;
+	body;
+	constructor(init) {
+		super(init.message);
+		this.kind = init.kind;
+		this.status = init.status;
+		this.providerCode = init.providerCode;
+		this.detail = init.detail;
+		this.requestId = init.requestId;
+		this.retryable = init.retryable;
+		this.retryAfterMs = init.retryAfterMs ?? null;
+		this.body = init.body ?? "";
+	}
+};
+/**
+* Structural type guard. Tolerates cross-realm errors by checking `name`.
+*/
+function isPosthogClientError(error) {
+	if (!error || typeof error !== "object") return false;
+	const candidate = error;
+	return candidate.name === "PosthogClientError" && typeof candidate.kind === "string";
+}
+/**
+* Classify an HTTP status plus response body into a `PosthogClientError`.
+* Exposed so the client can convert `JsonRestError` failures uniformly.
+*/
+function classifyHttpFailure(params) {
+	const { status, statusText, body, headers, errorPrefix } = params;
+	const requestId = headers.get("x-request-id") ?? headers.get("X-Request-Id") ?? null;
+	const retryAfterMs = parseRetryAfter(headers.get("retry-after"));
+	const { providerCode, detail } = parsePosthogErrorBody(body);
+	if (status === 429) return new PosthogClientError({
+		kind: "rate_limit",
+		message: `${errorPrefix}: 429 ${statusText}${detail ? ` — ${detail}` : ""}`,
+		status,
+		providerCode,
+		detail: detail ?? statusText,
+		requestId,
+		retryable: true,
+		retryAfterMs,
+		body
+	});
+	if (status === 401 || status === 403) return new PosthogClientError({
+		kind: "auth",
+		message: `${errorPrefix}: ${status} ${statusText}${detail ? ` — ${detail}` : ""}`,
+		status,
+		providerCode,
+		detail: detail ?? statusText,
+		requestId,
+		retryable: false,
+		body
+	});
+	if (status === 400 || status === 422) return new PosthogClientError({
+		kind: "validation",
+		message: `${errorPrefix}: ${status} ${statusText}${detail ? ` — ${detail}` : ""}`,
+		status,
+		providerCode,
+		detail: detail ?? statusText,
+		requestId,
+		retryable: false,
+		body
+	});
+	return new PosthogClientError({
+		kind: "http",
+		message: `${errorPrefix}: ${status} ${statusText}${detail ? ` — ${detail}` : ""}`,
+		status,
+		providerCode,
+		detail: detail ?? statusText,
+		requestId,
+		retryable: status >= 500,
+		body
+	});
+}
+function parseRetryAfter(value) {
+	if (!value) return null;
+	const seconds = Number.parseInt(value, 10);
+	if (Number.isFinite(seconds)) return seconds * 1e3;
+	const asDate = Date.parse(value);
+	if (Number.isFinite(asDate)) {
+		const delta = asDate - Date.now();
+		return delta > 0 ? delta : 0;
+	}
+	return null;
+}
+function parsePosthogErrorBody(body) {
+	if (!body) return {
+		providerCode: null,
+		detail: null
+	};
+	try {
+		const parsed = JSON.parse(body);
+		return {
+			providerCode: (typeof parsed.code === "string" ? parsed.code : null) ?? (typeof parsed.type === "string" ? parsed.type : null),
+			detail: (typeof parsed.detail === "string" ? parsed.detail : null) ?? (typeof parsed.error === "string" ? parsed.error : null) ?? (typeof parsed.message === "string" ? parsed.message : null)
+		};
+	} catch {
+		return {
+			providerCode: null,
+			detail: body.length < 500 ? body : null
+		};
+	}
+}
+
+//#endregion
+export { PosthogClientError, classifyHttpFailure, isPosthogClientError };