@posthog/convex 0.0.1 → 0.1.0

package/src/client/index.ts

@@ -0,0 +1,363 @@
+import type { Scheduler } from 'convex/server'
+import type { ComponentApi } from '../component/_generated/component.js'
+
+/** Context with a scheduler — available in mutations and actions. */
+type SchedulerCtx = { scheduler: Scheduler }
+
+/** Context with runAction — available in actions only. */
+type ActionCtx = { runAction: (reference: any, args: any) => Promise<any> }
+
+type FeatureFlagOptions = {
+  groups?: Record<string, string>
+  personProperties?: Record<string, string>
+  groupProperties?: Record<string, Record<string, string>>
+  sendFeatureFlagEvents?: boolean
+  disableGeoip?: boolean
+}
+
+export type FeatureFlagResult = {
+  key: string
+  enabled: boolean
+  variant: string | null
+  payload: unknown
+}
+
+export type PostHogEvent = {
+  event: string
+  distinctId: string
+  properties?: Record<string, unknown>
+}
+
+export type BeforeSendFn = (event: PostHogEvent) => PostHogEvent | null
+
+export type IdentifyFn = (ctx: any) => Promise<{ distinctId: string } | null>
+
+export function normalizeError(error: unknown): {
+  message: string
+  stack?: string
+  name?: string
+} {
+  if (error instanceof Error) {
+    return { message: error.message, stack: error.stack, name: error.name }
+  }
+  if (typeof error === 'string') {
+    return { message: error }
+  }
+  if (
+    typeof error === 'object' &&
+    error !== null &&
+    'message' in error &&
+    typeof (error as { message: unknown }).message === 'string'
+  ) {
+    const obj = error as {
+      message: string
+      stack?: unknown
+      name?: unknown
+    }
+    return {
+      message: obj.message,
+      stack: typeof obj.stack === 'string' ? obj.stack : undefined,
+      name: typeof obj.name === 'string' ? obj.name : undefined,
+    }
+  }
+  return { message: String(error) }
+}
+
+export class PostHog {
+  private apiKey: string
+  private host: string
+  private beforeSend?: BeforeSendFn | BeforeSendFn[]
+  private identifyFn?: IdentifyFn
+
+  constructor(
+    public component: ComponentApi,
+    options?: {
+      apiKey?: string
+      host?: string
+      beforeSend?: BeforeSendFn | BeforeSendFn[]
+      identify?: IdentifyFn
+    }
+  ) {
+    this.apiKey = options?.apiKey ?? process.env.POSTHOG_API_KEY ?? ''
+    this.host = options?.host ?? process.env.POSTHOG_HOST ?? 'https://us.i.posthog.com'
+    this.beforeSend = options?.beforeSend
+    this.identifyFn = options?.identify
+  }
+
+  private async resolveDistinctId(ctx: unknown, argsDistinctId?: string): Promise<string> {
+    if (this.identifyFn) {
+      const result = await this.identifyFn(ctx)
+      if (result) return result.distinctId
+    }
+    if (argsDistinctId) return argsDistinctId
+    throw new Error(
+      'PostHog: Could not resolve distinctId. Either configure an identify callback ' +
+        'in the PostHog constructor or pass distinctId explicitly.'
+    )
+  }
+
+  private runBeforeSend(event: PostHogEvent): PostHogEvent | null {
+    if (!this.beforeSend) return event
+    const fns = Array.isArray(this.beforeSend) ? this.beforeSend : [this.beforeSend]
+    let result: PostHogEvent | null = event
+    for (const fn of fns) {
+      result = fn(result)
+      if (!result) return null
+    }
+    return result
+  }
+
+  // --- Fire-and-forget methods (work in mutations and actions) ---
+
+  async capture(
+    ctx: SchedulerCtx,
+    args: {
+      distinctId?: string
+      event: string
+      properties?: Record<string, unknown>
+      groups?: Record<string, string | number>
+      sendFeatureFlags?: boolean
+      timestamp?: Date
+      uuid?: string
+      disableGeoip?: boolean
+    }
+  ) {
+    const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
+    const result = this.runBeforeSend({
+      event: args.event,
+      distinctId,
+      properties: args.properties,
+    })
+    if (!result) return
+
+    await ctx.scheduler.runAfter(0, this.component.lib.capture, {
+      apiKey: this.apiKey,
+      host: this.host,
+      distinctId: result.distinctId,
+      event: result.event,
+      properties: result.properties,
+      groups: args.groups,
+      sendFeatureFlags: args.sendFeatureFlags,
+      timestamp: args.timestamp?.getTime(),
+      uuid: args.uuid,
+      disableGeoip: args.disableGeoip,
+    })
+  }
+
+  async identify(
+    ctx: SchedulerCtx,
+    args: {
+      distinctId?: string
+      properties?: Record<string, unknown> & {
+        $set?: Record<string, unknown>
+        $set_once?: Record<string, unknown>
+        $anon_distinct_id?: string
+      }
+      disableGeoip?: boolean
+    }
+  ) {
+    const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
+    const result = this.runBeforeSend({
+      event: '$identify',
+      distinctId,
+      properties: args.properties,
+    })
+    if (!result) return
+
+    await ctx.scheduler.runAfter(0, this.component.lib.identify, {
+      apiKey: this.apiKey,
+      host: this.host,
+      distinctId: result.distinctId,
+      properties: result.properties,
+      disableGeoip: args.disableGeoip,
+    })
+  }
+
+  async groupIdentify(
+    ctx: SchedulerCtx,
+    args: {
+      groupType: string
+      groupKey: string
+      properties?: Record<string, unknown>
+      distinctId?: string
+      disableGeoip?: boolean
+    }
+  ) {
+    const result = this.runBeforeSend({
+      event: '$groupidentify',
+      distinctId: args.distinctId ?? '',
+      properties: args.properties,
+    })
+    if (!result) return
+
+    await ctx.scheduler.runAfter(0, this.component.lib.groupIdentify, {
+      apiKey: this.apiKey,
+      host: this.host,
+      groupType: args.groupType,
+      groupKey: args.groupKey,
+      properties: result.properties,
+      distinctId: args.distinctId,
+      disableGeoip: args.disableGeoip,
+    })
+  }
+
+  async alias(
+    ctx: SchedulerCtx,
+    args: {
+      distinctId?: string
+      alias: string
+      disableGeoip?: boolean
+    }
+  ) {
+    const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
+    const result = this.runBeforeSend({
+      event: '$create_alias',
+      distinctId,
+    })
+    if (!result) return
+
+    await ctx.scheduler.runAfter(0, this.component.lib.alias, {
+      apiKey: this.apiKey,
+      host: this.host,
+      distinctId: result.distinctId,
+      alias: args.alias,
+      disableGeoip: args.disableGeoip,
+    })
+  }
+
+  async captureException(
+    ctx: SchedulerCtx,
+    args: {
+      error: unknown
+      distinctId?: string
+      additionalProperties?: Record<string, unknown>
+    }
+  ) {
+    const { message, stack, name } = normalizeError(args.error)
+
+    let distinctId: string | undefined
+    try {
+      distinctId = await this.resolveDistinctId(ctx, args.distinctId)
+    } catch {
+      // captureException works without a distinctId
+    }
+
+    const result = this.runBeforeSend({
+      event: '$exception',
+      distinctId: distinctId ?? '',
+      properties: args.additionalProperties,
+    })
+    if (!result) return
+
+    await ctx.scheduler.runAfter(0, this.component.lib.captureException, {
+      apiKey: this.apiKey,
+      host: this.host,
+      distinctId: result.distinctId || undefined,
+      errorMessage: message,
+      errorStack: stack,
+      errorName: name,
+      additionalProperties: result.properties,
+    })
+  }
+
+  // --- Feature flag methods (require action context) ---
+
+  async getFeatureFlag(
+    ctx: ActionCtx,
+    args: { key: string; distinctId?: string } & FeatureFlagOptions
+  ): Promise<boolean | string | null> {
+    const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
+    return await ctx.runAction(this.component.lib.getFeatureFlag, {
+      apiKey: this.apiKey,
+      host: this.host,
+      ...args,
+      distinctId,
+    })
+  }
+
+  async isFeatureEnabled(
+    ctx: ActionCtx,
+    args: { key: string; distinctId?: string } & FeatureFlagOptions
+  ): Promise<boolean | null> {
+    const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
+    return await ctx.runAction(this.component.lib.isFeatureEnabled, {
+      apiKey: this.apiKey,
+      host: this.host,
+      ...args,
+      distinctId,
+    })
+  }
+
+  async getFeatureFlagPayload(
+    ctx: ActionCtx,
+    args: {
+      key: string
+      distinctId?: string
+      matchValue?: boolean | string
+    } & FeatureFlagOptions
+  ): Promise<unknown> {
+    const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
+    return await ctx.runAction(this.component.lib.getFeatureFlagPayload, {
+      apiKey: this.apiKey,
+      host: this.host,
+      ...args,
+      distinctId,
+    })
+  }
+
+  async getFeatureFlagResult(
+    ctx: ActionCtx,
+    args: { key: string; distinctId?: string } & FeatureFlagOptions
+  ): Promise<FeatureFlagResult | null> {
+    const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
+    return await ctx.runAction(this.component.lib.getFeatureFlagResult, {
+      apiKey: this.apiKey,
+      host: this.host,
+      ...args,
+      distinctId,
+    })
+  }
+
+  async getAllFlags(
+    ctx: ActionCtx,
+    args: {
+      distinctId?: string
+      groups?: Record<string, string>
+      personProperties?: Record<string, string>
+      groupProperties?: Record<string, Record<string, string>>
+      disableGeoip?: boolean
+      flagKeys?: string[]
+    }
+  ): Promise<Record<string, boolean | string>> {
+    const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
+    return await ctx.runAction(this.component.lib.getAllFlags, {
+      apiKey: this.apiKey,
+      host: this.host,
+      ...args,
+      distinctId,
+    })
+  }
+
+  async getAllFlagsAndPayloads(
+    ctx: ActionCtx,
+    args: {
+      distinctId?: string
+      groups?: Record<string, string>
+      personProperties?: Record<string, string>
+      groupProperties?: Record<string, Record<string, string>>
+      disableGeoip?: boolean
+      flagKeys?: string[]
+    }
+  ): Promise<{
+    featureFlags: Record<string, boolean | string>
+    featureFlagPayloads: Record<string, unknown>
+  }> {
+    const distinctId = await this.resolveDistinctId(ctx, args.distinctId)
+    return await ctx.runAction(this.component.lib.getAllFlagsAndPayloads, {
+      apiKey: this.apiKey,
+      host: this.host,
+      ...args,
+      distinctId,
+    })
+  }
+}

package/src/client/setup.test.ts

@@ -0,0 +1,20 @@
+/// <reference types="vite/client" />
+import { test } from '@jest/globals'
+import { convexTest } from 'convex-test'
+export const modules = import.meta.glob('./**/*.*s')
+
+import { defineSchema, type GenericSchema, type SchemaDefinition } from 'convex/server'
+import { type ComponentApi } from '../component/_generated/component.js'
+import { componentsGeneric } from 'convex/server'
+import { register } from '../test.js'
+
+export function initConvexTest<Schema extends SchemaDefinition<GenericSchema, boolean>>(schema?: Schema) {
+  const t = convexTest(schema ?? defineSchema({}), modules)
+  register(t)
+  return t
+}
+export const components = componentsGeneric() as unknown as {
+  posthog: ComponentApi
+}
+
+test('setup', () => {})

package/src/component/_generated/api.ts

@@ -0,0 +1,50 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as lib from "../lib.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  lib: typeof lib;
+}> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+> = anyApi as any;
+
+export const components = componentsGeneric() as unknown as {};

package/src/component/_generated/component.ts

@@ -0,0 +1,203 @@
+/* eslint-disable */
+/**
+ * Generated `ComponentApi` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type { FunctionReference } from "convex/server";
+
+/**
+ * A utility for referencing a Convex component's exposed API.
+ *
+ * Useful when expecting a parameter like `components.myComponent`.
+ * Usage:
+ * ```ts
+ * async function myFunction(ctx: QueryCtx, component: ComponentApi) {
+ *   return ctx.runQuery(component.someFile.someQuery, { ...args });
+ * }
+ * ```
+ */
+export type ComponentApi<Name extends string | undefined = string | undefined> =
+  {
+    lib: {
+      alias: FunctionReference<
+        "action",
+        "internal",
+        {
+          alias: string;
+          apiKey: string;
+          disableGeoip?: boolean;
+          distinctId: string;
+          host: string;
+        },
+        any,
+        Name
+      >;
+      capture: FunctionReference<
+        "action",
+        "internal",
+        {
+          apiKey: string;
+          disableGeoip?: boolean;
+          distinctId: string;
+          event: string;
+          groups?: any;
+          host: string;
+          properties?: any;
+          sendFeatureFlags?: boolean;
+          timestamp?: number;
+          uuid?: string;
+        },
+        any,
+        Name
+      >;
+      captureException: FunctionReference<
+        "action",
+        "internal",
+        {
+          additionalProperties?: any;
+          apiKey: string;
+          distinctId?: string;
+          errorMessage: string;
+          errorName?: string;
+          errorStack?: string;
+          host: string;
+        },
+        any,
+        Name
+      >;
+      getAllFlags: FunctionReference<
+        "action",
+        "internal",
+        {
+          apiKey: string;
+          disableGeoip?: boolean;
+          distinctId: string;
+          flagKeys?: Array<string>;
+          groupProperties?: any;
+          groups?: any;
+          host: string;
+          personProperties?: any;
+        },
+        any,
+        Name
+      >;
+      getAllFlagsAndPayloads: FunctionReference<
+        "action",
+        "internal",
+        {
+          apiKey: string;
+          disableGeoip?: boolean;
+          distinctId: string;
+          flagKeys?: Array<string>;
+          groupProperties?: any;
+          groups?: any;
+          host: string;
+          personProperties?: any;
+        },
+        any,
+        Name
+      >;
+      getFeatureFlag: FunctionReference<
+        "action",
+        "internal",
+        {
+          apiKey: string;
+          disableGeoip?: boolean;
+          distinctId: string;
+          groupProperties?: any;
+          groups?: any;
+          host: string;
+          key: string;
+          personProperties?: any;
+          sendFeatureFlagEvents?: boolean;
+        },
+        any,
+        Name
+      >;
+      getFeatureFlagPayload: FunctionReference<
+        "action",
+        "internal",
+        {
+          apiKey: string;
+          disableGeoip?: boolean;
+          distinctId: string;
+          groupProperties?: any;
+          groups?: any;
+          host: string;
+          key: string;
+          matchValue?: string | boolean;
+          personProperties?: any;
+          sendFeatureFlagEvents?: boolean;
+        },
+        any,
+        Name
+      >;
+      getFeatureFlagResult: FunctionReference<
+        "action",
+        "internal",
+        {
+          apiKey: string;
+          disableGeoip?: boolean;
+          distinctId: string;
+          groupProperties?: any;
+          groups?: any;
+          host: string;
+          key: string;
+          personProperties?: any;
+          sendFeatureFlagEvents?: boolean;
+        },
+        any,
+        Name
+      >;
+      groupIdentify: FunctionReference<
+        "action",
+        "internal",
+        {
+          apiKey: string;
+          disableGeoip?: boolean;
+          distinctId?: string;
+          groupKey: string;
+          groupType: string;
+          host: string;
+          properties?: any;
+        },
+        any,
+        Name
+      >;
+      identify: FunctionReference<
+        "action",
+        "internal",
+        {
+          apiKey: string;
+          disableGeoip?: boolean;
+          distinctId: string;
+          host: string;
+          properties?: any;
+        },
+        any,
+        Name
+      >;
+      isFeatureEnabled: FunctionReference<
+        "action",
+        "internal",
+        {
+          apiKey: string;
+          disableGeoip?: boolean;
+          distinctId: string;
+          groupProperties?: any;
+          groups?: any;
+          host: string;
+          key: string;
+          personProperties?: any;
+          sendFeatureFlagEvents?: boolean;
+        },
+        any,
+        Name
+      >;
+    };
+  };

package/src/component/_generated/dataModel.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;