@posthog/convex 0.0.1 → 0.1.0

package/src/component/_generated/server.ts

@@ -0,0 +1,156 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  ActionBuilder,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+} from "convex/server";
+import {
+  actionGeneric,
+  httpActionGeneric,
+  queryGeneric,
+  mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+} from "convex/server";
+import type { DataModel } from "./dataModel.js";
+
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const query: QueryBuilder<DataModel, "public"> = queryGeneric;
+
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery: QueryBuilder<DataModel, "internal"> =
+  internalQueryGeneric;
+
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const mutation: MutationBuilder<DataModel, "public"> = mutationGeneric;
+
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation: MutationBuilder<DataModel, "internal"> =
+  internalMutationGeneric;
+
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export const action: ActionBuilder<DataModel, "public"> = actionGeneric;
+
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction: ActionBuilder<DataModel, "internal"> =
+  internalActionGeneric;
+
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export const httpAction: HttpActionBuilder = httpActionGeneric;
+
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * If you're using code generation, use the `QueryCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type QueryCtx = GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ *
+ * If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type MutationCtx = GenericMutationCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
+export type ActionCtx = GenericActionCtx<DataModel>;
+
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;

package/src/component/convex.config.ts

@@ -0,0 +1,3 @@
+import { defineComponent } from 'convex/server'
+
+export default defineComponent('posthog')

package/src/component/lib.ts

@@ -0,0 +1,259 @@
+import type { FeatureFlagValue, JsonType } from '@posthog/core'
+import { PostHog } from 'posthog-node/edge'
+import { action } from './_generated/server.js'
+import { v } from 'convex/values'
+
+function createClient(apiKey: string, host: string) {
+  return new PostHog(apiKey, { host, flushAt: 1, flushInterval: 0 })
+}
+
+export const capture = action({
+  args: {
+    apiKey: v.string(),
+    host: v.string(),
+    distinctId: v.string(),
+    event: v.string(),
+    properties: v.optional(v.any()),
+    groups: v.optional(v.any()),
+    sendFeatureFlags: v.optional(v.boolean()),
+    timestamp: v.optional(v.number()),
+    uuid: v.optional(v.string()),
+    disableGeoip: v.optional(v.boolean()),
+  },
+  handler: async (_ctx, args) => {
+    const client = createClient(args.apiKey, args.host)
+    client.capture({
+      distinctId: args.distinctId,
+      event: args.event,
+      properties: args.properties,
+      groups: args.groups,
+      sendFeatureFlags: args.sendFeatureFlags,
+      timestamp: args.timestamp ? new Date(args.timestamp) : undefined,
+      uuid: args.uuid,
+      disableGeoip: args.disableGeoip,
+    })
+    await client.shutdown()
+  },
+})
+
+export const identify = action({
+  args: {
+    apiKey: v.string(),
+    host: v.string(),
+    distinctId: v.string(),
+    properties: v.optional(v.any()),
+    disableGeoip: v.optional(v.boolean()),
+  },
+  handler: async (_ctx, args) => {
+    const client = createClient(args.apiKey, args.host)
+    client.identify({
+      distinctId: args.distinctId,
+      properties: args.properties,
+      disableGeoip: args.disableGeoip,
+    })
+    await client.shutdown()
+  },
+})
+
+export const groupIdentify = action({
+  args: {
+    apiKey: v.string(),
+    host: v.string(),
+    groupType: v.string(),
+    groupKey: v.string(),
+    properties: v.optional(v.any()),
+    distinctId: v.optional(v.string()),
+    disableGeoip: v.optional(v.boolean()),
+  },
+  handler: async (_ctx, args) => {
+    const client = createClient(args.apiKey, args.host)
+    client.groupIdentify({
+      groupType: args.groupType,
+      groupKey: args.groupKey,
+      properties: args.properties,
+      distinctId: args.distinctId,
+      disableGeoip: args.disableGeoip,
+    })
+    await client.shutdown()
+  },
+})
+
+export const alias = action({
+  args: {
+    apiKey: v.string(),
+    host: v.string(),
+    distinctId: v.string(),
+    alias: v.string(),
+    disableGeoip: v.optional(v.boolean()),
+  },
+  handler: async (_ctx, args) => {
+    const client = createClient(args.apiKey, args.host)
+    client.alias({
+      distinctId: args.distinctId,
+      alias: args.alias,
+      disableGeoip: args.disableGeoip,
+    })
+    await client.shutdown()
+  },
+})
+
+export const captureException = action({
+  args: {
+    apiKey: v.string(),
+    host: v.string(),
+    distinctId: v.optional(v.string()),
+    errorMessage: v.string(),
+    errorStack: v.optional(v.string()),
+    errorName: v.optional(v.string()),
+    additionalProperties: v.optional(v.any()),
+  },
+  handler: async (_ctx, args) => {
+    const client = createClient(args.apiKey, args.host)
+    const error = new Error(args.errorMessage)
+    if (args.errorName) error.name = args.errorName
+    if (args.errorStack) error.stack = args.errorStack
+    client.captureException(error, args.distinctId, args.additionalProperties)
+    await client.shutdown()
+  },
+})
+
+// Feature flag actions — these return values and must be called via ctx.runAction
+
+const featureFlagArgs = {
+  apiKey: v.string(),
+  host: v.string(),
+  key: v.string(),
+  distinctId: v.string(),
+  groups: v.optional(v.any()),
+  personProperties: v.optional(v.any()),
+  groupProperties: v.optional(v.any()),
+  sendFeatureFlagEvents: v.optional(v.boolean()),
+  disableGeoip: v.optional(v.boolean()),
+}
+
+function featureFlagOptions(args: {
+  groups?: Record<string, string>
+  personProperties?: Record<string, string>
+  groupProperties?: Record<string, Record<string, string>>
+  sendFeatureFlagEvents?: boolean
+  disableGeoip?: boolean
+}) {
+  return {
+    groups: args.groups,
+    personProperties: args.personProperties,
+    groupProperties: args.groupProperties,
+    sendFeatureFlagEvents: args.sendFeatureFlagEvents,
+    disableGeoip: args.disableGeoip,
+  }
+}
+
+export const getFeatureFlag = action({
+  args: featureFlagArgs,
+  handler: async (_ctx, args): Promise<FeatureFlagValue | null> => {
+    const client = createClient(args.apiKey, args.host)
+    const result = await client.getFeatureFlag(args.key, args.distinctId, featureFlagOptions(args))
+    await client.shutdown()
+    return result ?? null
+  },
+})
+
+export const isFeatureEnabled = action({
+  args: featureFlagArgs,
+  handler: async (_ctx, args) => {
+    const client = createClient(args.apiKey, args.host)
+    const result = await client.isFeatureEnabled(args.key, args.distinctId, featureFlagOptions(args))
+    await client.shutdown()
+    return result ?? null
+  },
+})
+
+export const getFeatureFlagPayload = action({
+  args: {
+    ...featureFlagArgs,
+    matchValue: v.optional(v.union(v.string(), v.boolean())),
+  },
+  handler: async (_ctx, args): Promise<JsonType> => {
+    const client = createClient(args.apiKey, args.host)
+    const result = await client.getFeatureFlagPayload(
+      args.key,
+      args.distinctId,
+      args.matchValue,
+      featureFlagOptions(args)
+    )
+    await client.shutdown()
+    return result ?? null
+  },
+})
+
+export const getFeatureFlagResult = action({
+  args: featureFlagArgs,
+  handler: async (
+    _ctx,
+    args
+  ): Promise<{
+    key: string
+    enabled: boolean
+    variant: string | null
+    payload: JsonType | null
+  } | null> => {
+    const client = createClient(args.apiKey, args.host)
+    const result = await client.getFeatureFlagResult(args.key, args.distinctId, featureFlagOptions(args))
+    await client.shutdown()
+    if (!result) return null
+    return {
+      key: result.key,
+      enabled: result.enabled,
+      variant: result.variant ?? null,
+      payload: result.payload ?? null,
+    }
+  },
+})
+
+const allFlagsArgs = {
+  apiKey: v.string(),
+  host: v.string(),
+  distinctId: v.string(),
+  groups: v.optional(v.any()),
+  personProperties: v.optional(v.any()),
+  groupProperties: v.optional(v.any()),
+  disableGeoip: v.optional(v.boolean()),
+  flagKeys: v.optional(v.array(v.string())),
+}
+
+export const getAllFlags = action({
+  args: allFlagsArgs,
+  handler: async (_ctx, args): Promise<Record<string, FeatureFlagValue>> => {
+    const client = createClient(args.apiKey, args.host)
+    const result = await client.getAllFlags(args.distinctId, {
+      groups: args.groups,
+      personProperties: args.personProperties,
+      groupProperties: args.groupProperties,
+      disableGeoip: args.disableGeoip,
+      flagKeys: args.flagKeys,
+    })
+    await client.shutdown()
+    return result
+  },
+})
+
+export const getAllFlagsAndPayloads = action({
+  args: allFlagsArgs,
+  handler: async (
+    _ctx,
+    args
+  ): Promise<{
+    featureFlags?: Record<string, FeatureFlagValue>
+    featureFlagPayloads?: Record<string, JsonType>
+  }> => {
+    const client = createClient(args.apiKey, args.host)
+    const result = await client.getAllFlagsAndPayloads(args.distinctId, {
+      groups: args.groups,
+      personProperties: args.personProperties,
+      groupProperties: args.groupProperties,
+      disableGeoip: args.disableGeoip,
+      flagKeys: args.flagKeys,
+    })
+    await client.shutdown()
+    return result
+  },
+})

package/src/component/schema.ts

@@ -0,0 +1,3 @@
+import { defineSchema } from 'convex/server'
+
+export default defineSchema({})

package/src/component/setup.test.ts

@@ -0,0 +1,11 @@
+/// <reference types="vite/client" />
+import { test } from '@jest/globals'
+import schema from './schema.js'
+import { convexTest } from 'convex-test'
+export const modules = import.meta.glob('./**/*.*s')
+
+export function initConvexTest() {
+  const t = convexTest(schema, modules)
+  return t
+}
+test('setup', () => {})

package/src/test.ts

@@ -0,0 +1,15 @@
+/// <reference types="vite/client" />
+import type { TestConvex } from 'convex-test'
+import type { GenericSchema, SchemaDefinition } from 'convex/server'
+import schema from './component/schema.js'
+const modules = import.meta.glob('./component/**/*.ts')
+
+/**
+ * Register the component with the test convex instance.
+ * @param t - The test convex instance, e.g. from calling `convexTest`.
+ * @param name - The name of the component, as registered in convex.config.ts.
+ */
+export function register(t: TestConvex<SchemaDefinition<GenericSchema, boolean>>, name: string = 'posthog') {
+  t.registerComponent(name, schema, modules)
+}
+export default { register, schema, modules }