@mantajs/plugin-posthog-proxy 0.2.0-beta.0

package/src/modules/posthog/commands/identify-user.ts

@@ -0,0 +1,32 @@
+import { defineCommand } from '@mantajs/core'
+import { PostHog } from 'posthog-node'
+import { postHogIdentifyInputSchema } from '../schemas'
+
+export default defineCommand({
+  name: 'posthog:identify-user',
+  description:
+    'Identify an anonymous PostHog visitor with their properties. Links all past anonymous events to the known user.',
+  input: postHogIdentifyInputSchema,
+  async workflow(input, { step }) {
+    // step.action signature: (name, { invoke, compensate }) → returns a runner function
+    // that you must call with (input, ctx) to execute. Compensate is mandatory but a no-op
+    // here: identify writes are idempotent and there's no PostHog primitive to "un-identify".
+    return step.action('posthog-identify', {
+      invoke: async () => {
+        const token = process.env.POSTHOG_TOKEN
+        if (!token) return { success: false, error: 'POSTHOG_TOKEN env var not set' }
+
+        const posthog = new PostHog(token, { host: process.env.POSTHOG_HOST ?? 'https://eu.i.posthog.com' })
+        posthog.identify({
+          distinctId: input.distinctId,
+          properties: input.properties,
+        })
+        await posthog.shutdown()
+        return { success: true }
+      },
+      compensate: async () => {
+        // No-op — identify writes are idempotent.
+      },
+    })(input)
+  },
+})

package/src/modules/posthog/commands/track-event.ts

@@ -0,0 +1,34 @@
+import { defineCommand } from '@mantajs/core'
+import { PostHog } from 'posthog-node'
+import { postHogCaptureInputSchema } from '../schemas'
+
+export default defineCommand({
+  name: 'posthog:track-event',
+  description:
+    'Track a custom analytics event in PostHog (page view, click, purchase, sign-up, etc.). Use for sending server-side events.',
+  input: postHogCaptureInputSchema,
+  async workflow(input, { step }) {
+    // step.action signature: (name, { invoke, compensate }) → returns a runner function
+    // that you must call with (input, ctx) to execute. Compensate is mandatory but a no-op
+    // here: PostHog events are immutable once sent, so there's nothing to rollback if a
+    // later step in the workflow fails.
+    return step.action('posthog-capture', {
+      invoke: async () => {
+        const token = process.env.POSTHOG_TOKEN
+        if (!token) return { success: false, error: 'POSTHOG_TOKEN env var not set' }
+
+        const posthog = new PostHog(token, { host: process.env.POSTHOG_HOST ?? 'https://eu.i.posthog.com' })
+        posthog.capture({
+          event: input.event,
+          distinctId: input.distinctId,
+          properties: input.properties,
+        })
+        await posthog.shutdown()
+        return { success: true }
+      },
+      compensate: async () => {
+        // No-op — events are immutable.
+      },
+    })(input)
+  },
+})

package/src/modules/posthog/entities/event/model.ts

@@ -0,0 +1,4 @@
+import { defineModel, fromZodSchema } from '@mantajs/core'
+import { postHogEventSchema } from '../../schemas'
+
+export default defineModel('PostHogEvent', fromZodSchema(postHogEventSchema)).external()

package/src/modules/posthog/entities/insight/model.ts

@@ -0,0 +1,4 @@
+import { defineModel, fromZodSchema } from '@mantajs/core'
+import { postHogInsightSchema } from '../../schemas'
+
+export default defineModel('PostHogInsight', fromZodSchema(postHogInsightSchema)).external()

package/src/modules/posthog/entities/person/model.ts

@@ -0,0 +1,4 @@
+import { defineModel, fromZodSchema } from '@mantajs/core'
+import { postHogPersonSchema } from '../../schemas'
+
+export default defineModel('PostHogPerson', fromZodSchema(postHogPersonSchema)).external()

package/src/modules/posthog/queries/graph.ts

@@ -0,0 +1,24 @@
+// PostHog query graph extension — declares which entities this module owns and routes
+// Manta query graph requests to PostHog's HogQL / Insights APIs.
+//
+// The file is auto-discovered by the framework (scans modules/{name}/queries/*.ts).
+// Because its default export uses `extendQueryGraph`, the framework registers it on
+// the QueryService as a resolver for the listed entities.
+
+import { extendQueryGraph } from '@mantajs/core'
+import { executeHogQL, executeInsights } from './lib/execute'
+import { SUPPORTED_FILTERS } from './lib/schema'
+
+export default extendQueryGraph({
+  owns: ['posthogEvent', 'posthogPerson', 'posthogInsight'],
+  supportedFilters: SUPPORTED_FILTERS,
+  async resolve(query) {
+    // Case-insensitive dispatch — caller may pass 'posthogInsight', 'PostHogInsight',
+    // 'posthoginsight', etc. depending on where they discovered the entity name (AI
+    // system prompt lowercases module names, for example).
+    if (typeof query.entity === 'string' && query.entity.toLowerCase() === 'posthoginsight') {
+      return executeInsights(query)
+    }
+    return executeHogQL(query)
+  },
+})

package/src/modules/posthog/queries/lib/execute.ts

@@ -0,0 +1,111 @@
+// PostHog HogQL execution — runs SQL against the PostHog query endpoint and normalizes results.
+
+import type { GraphQueryConfig } from '@mantajs/core'
+import { MantaError } from '@mantajs/core'
+import { DEFAULT_SORT, ENTITY_TO_TABLE } from './schema'
+import { normalizeRow, translateFilters } from './translate'
+
+export interface PostHogConnection {
+  host: string
+  personalApiKey: string
+}
+
+/**
+ * Read PostHog connection info from environment variables. No plugin config — pure env.
+ * Throws MantaError if the personal API key is missing, so the caller (AI or HTTP) sees a clear message.
+ */
+export function readPostHogConnection(): PostHogConnection {
+  const host = process.env.POSTHOG_HOST ?? 'https://eu.i.posthog.com'
+  const personalApiKey = process.env.POSTHOG_API_KEY
+  if (!personalApiKey) {
+    throw new MantaError('INVALID_DATA', 'POSTHOG_API_KEY env var not set — cannot query PostHog data warehouse.')
+  }
+  return { host, personalApiKey }
+}
+
+/**
+ * Resolve a query that targets posthogEvent or posthogPerson via HogQL.
+ *
+ * Entity name normalization: the extendQueryGraph() framework does a case-insensitive
+ * match when deciding which extension owns an entity, but passes the caller's original
+ * string to the resolver. Callers can therefore use 'posthogEvent', 'PostHogEvent', or
+ * 'posthogevent' (e.g. when the AI system prompt lowercases module names). We normalize
+ * against the canonical keys of ENTITY_TO_TABLE so every downstream lookup
+ * (translateFilters, normalizeRow) gets the canonical name.
+ */
+export async function executeHogQL(query: GraphQueryConfig): Promise<Record<string, unknown>[]> {
+  const rawEntity = query.entity as string
+  const canonicalEntity = Object.keys(ENTITY_TO_TABLE).find((k) => k.toLowerCase() === rawEntity.toLowerCase())
+  if (!canonicalEntity) {
+    throw new MantaError(
+      'INVALID_DATA',
+      `Unknown PostHog entity: ${rawEntity}. Known: ${Object.keys(ENTITY_TO_TABLE).join(', ')}`,
+    )
+  }
+  const entity = canonicalEntity
+  const table = ENTITY_TO_TABLE[entity]
+
+  const { host, personalApiKey } = readPostHogConnection()
+  const whereClause = translateFilters(entity, query.filters)
+  const limit = query.pagination?.limit ?? 100
+  const offset = query.pagination?.offset ?? 0
+  // Each ClickHouse table has its own time column — events.timestamp, persons.created_at.
+  // Pick the right one from DEFAULT_SORT, or skip ORDER BY entirely if no default is known.
+  const orderByClause = DEFAULT_SORT[entity] ? `ORDER BY ${DEFAULT_SORT[entity]}` : ''
+
+  const hogql = `SELECT * FROM ${table} ${whereClause} ${orderByClause} LIMIT ${limit} OFFSET ${offset}`
+    .replace(/\s+/g, ' ')
+    .trim()
+
+  const res = await fetch(`${host}/api/projects/@current/query/`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${personalApiKey}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ query: { kind: 'HogQLQuery', query: hogql } }),
+  })
+
+  if (!res.ok) {
+    throw new MantaError('INVALID_DATA', `PostHog HogQL returned ${res.status}: ${await res.text()}`)
+  }
+
+  const data = (await res.json()) as { results?: unknown[][]; columns?: string[] }
+  if (!data.results || !data.columns) return []
+
+  return data.results.map((row) => {
+    const obj: Record<string, unknown> = {}
+    data.columns?.forEach((col, idx) => {
+      obj[col] = row[idx]
+    })
+    return normalizeRow(entity, obj)
+  })
+}
+
+/**
+ * Resolve posthogInsight via PostHog's REST endpoint (not HogQL — insights have their own API).
+ */
+export async function executeInsights(query: GraphQueryConfig): Promise<Record<string, unknown>[]> {
+  const { host, personalApiKey } = readPostHogConnection()
+  const params = new URLSearchParams()
+  params.set('limit', String(query.pagination?.limit ?? 100))
+  if (query.filters?.id) params.set('short_id', String(query.filters.id))
+
+  const res = await fetch(`${host}/api/projects/@current/insights/?${params}`, {
+    headers: { Authorization: `Bearer ${personalApiKey}` },
+  })
+  if (!res.ok) {
+    throw new MantaError('INVALID_DATA', `PostHog Insights API returned ${res.status}: ${await res.text()}`)
+  }
+
+  const data = (await res.json()) as { results?: Array<Record<string, unknown>> }
+  return (data.results ?? []).map((r) => ({
+    id: r.id,
+    name: r.name,
+    description: r.description,
+    shortId: r.short_id,
+    filters: r.filters,
+    createdAt: r.created_at,
+    updatedAt: r.updated_at,
+  }))
+}

package/src/modules/posthog/queries/lib/schema.ts

@@ -0,0 +1,45 @@
+// PostHog entity ↔ HogQL mapping — which ClickHouse tables + columns back each Manta entity.
+
+/** Manta entity name → HogQL table name. */
+export const ENTITY_TO_TABLE: Record<string, string> = {
+  posthogEvent: 'events',
+  posthogPerson: 'persons',
+}
+
+/** Manta field name → HogQL column path (supports dotted access for properties). */
+export const FIELD_MAP: Record<string, Record<string, string>> = {
+  posthogEvent: {
+    id: 'uuid',
+    event: 'event',
+    distinctId: 'distinct_id',
+    timestamp: 'timestamp',
+    properties: 'properties',
+    url: 'properties.$current_url',
+    personId: 'person_id',
+  },
+  posthogPerson: {
+    id: 'id',
+    distinctId: 'distinct_id',
+    email: 'properties.email',
+    name: 'properties.name',
+    createdAt: 'created_at',
+    properties: 'properties',
+  },
+}
+
+/** Filters supported per entity — anything else throws at query time. */
+export const SUPPORTED_FILTERS: Record<string, string[]> = {
+  posthogEvent: ['event', 'distinctId', 'personId', 'timestamp', 'after', 'before'],
+  posthogPerson: ['email', 'distinctId', 'id'],
+  posthogInsight: ['id', 'shortId'],
+}
+
+/**
+ * Default ORDER BY clause per entity. Each ClickHouse table has its own time column —
+ * `events.timestamp`, `persons.created_at` — and using the wrong one yields a 400
+ * "Unable to resolve field" error. Keyed by canonical Manta entity name.
+ */
+export const DEFAULT_SORT: Record<string, string> = {
+  posthogEvent: 'timestamp DESC',
+  posthogPerson: 'created_at DESC',
+}

package/src/modules/posthog/queries/lib/translate.ts

@@ -0,0 +1,73 @@
+// Manta query graph → HogQL SQL translator.
+
+import { FIELD_MAP } from './schema'
+
+/**
+ * Escape a raw value for safe inclusion in a HogQL string.
+ * Numbers and booleans are passed through, strings are single-quoted with ' → ''.
+ */
+export function escapeValue(v: unknown): string {
+  if (v === null || v === undefined) return 'NULL'
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v)
+  return `'${String(v).replace(/'/g, "''")}'`
+}
+
+/**
+ * Translate a Manta filter map into a HogQL `WHERE` clause.
+ * Only equality, IN (array value), and the special `after`/`before` timestamp filters are supported.
+ */
+export function translateFilters(entity: string, filters: Record<string, unknown> | undefined): string {
+  if (!filters || Object.keys(filters).length === 0) return ''
+  const fieldMap = FIELD_MAP[entity] ?? {}
+  const clauses: string[] = []
+
+  for (const [key, value] of Object.entries(filters)) {
+    if (key === 'after') {
+      clauses.push(`timestamp > ${escapeValue(value)}`)
+      continue
+    }
+    if (key === 'before') {
+      clauses.push(`timestamp < ${escapeValue(value)}`)
+      continue
+    }
+    const column = fieldMap[key] ?? key
+    if (Array.isArray(value)) {
+      const list = value.map(escapeValue).join(', ')
+      clauses.push(`${column} IN (${list})`)
+    } else {
+      clauses.push(`${column} = ${escapeValue(value)}`)
+    }
+  }
+
+  return clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : ''
+}
+
+/**
+ * Normalize a raw HogQL result row (keyed by ClickHouse column names) into the Manta entity shape.
+ */
+export function normalizeRow(entity: string, row: Record<string, unknown>): Record<string, unknown> {
+  if (entity === 'posthogEvent') {
+    const props = (row.properties as Record<string, unknown> | null) ?? {}
+    return {
+      id: row.uuid ?? row.id,
+      event: row.event,
+      distinctId: row.distinct_id,
+      timestamp: row.timestamp,
+      properties: props,
+      url: props.$current_url ?? null,
+      personId: row.person_id ?? null,
+    }
+  }
+  if (entity === 'posthogPerson') {
+    const props = (row.properties as Record<string, unknown> | null) ?? {}
+    return {
+      id: row.id,
+      distinctId: row.distinct_id,
+      email: (props.email as string | undefined) ?? null,
+      name: (props.name as string | undefined) ?? null,
+      createdAt: row.created_at,
+      properties: props,
+    }
+  }
+  return row
+}

package/src/modules/posthog/schemas.ts

@@ -0,0 +1,48 @@
+// Generated by ts-to-zod
+import { z } from 'zod'
+
+export const postHogCaptureInputSchema = z.object({
+  distinctId: z.string(),
+  event: z.string(),
+  properties: z.record(z.string(), z.unknown()).optional(),
+  timestamp: z.date().optional(),
+  uuid: z.string().optional(),
+})
+
+export const postHogIdentifyInputSchema = z.object({
+  distinctId: z.string(),
+  properties: z.record(z.string(), z.unknown()).optional(),
+})
+
+const _assertCaptureMatchesSdkSchema = z.any()
+
+const _assertIdentifyMatchesSdkSchema = z.any()
+
+export const postHogEventSchema = z.object({
+  uuid: z.string(),
+  event: z.string(),
+  distinctId: z.string(),
+  timestamp: z.string(),
+  properties: z.record(z.string(), z.unknown()),
+  personId: z.string().nullable(),
+  url: z.string().nullable(),
+})
+
+export const postHogPersonSchema = z.object({
+  id: z.string(),
+  distinctId: z.string(),
+  email: z.string().nullable(),
+  name: z.string().nullable(),
+  createdAt: z.string(),
+  properties: z.record(z.string(), z.unknown()),
+})
+
+export const postHogInsightSchema = z.object({
+  id: z.number(),
+  shortId: z.string().nullable(),
+  name: z.string(),
+  description: z.string().nullable(),
+  filters: z.record(z.string(), z.unknown()),
+  createdAt: z.string(),
+  updatedAt: z.string().nullable(),
+})