feat: event schema types

packages/browser/package.json

@@ -1,6 +1,6 @@
 {
     "name": "posthog-js",
-    "version": "1.275.1",
+    "version": "1.275.2",
     "description": "Posthog-js allows you to automatically capture usage and send events to PostHog.",
     "repository": "https://github.com/PostHog/posthog-js",
     "author": "[email protected]",

packages/browser/src/posthog-core.ts

@@ -97,6 +97,8 @@ import {
     isArray,
     isEmptyObject,
     isObject,
+    TypedEventCapture,
+    createTypedEventCapture,
 } from '@posthog/core'
 import { uuidv7 } from './uuidv7'
 import { WebExperiments } from './web-experiments'
@@ -340,6 +342,8 @@ export class PostHog {
     SentryIntegration: typeof SentryIntegration
     sentryIntegration: (options?: SentryIntegrationOptions) => ReturnType<typeof sentryIntegration>
 
+    readonly typed: TypedEventCapture<this>
+
     private _internalEventEmitter = new SimpleEventEmitter()
 
     // Legacy property to support existing usage - this isn't technically correct but it's what it has always been - a proxy for flags being loaded
@@ -370,6 +374,7 @@ export class PostHog {
         this._visibilityStateListener = null
         this._initialPersonProfilesConfig = null
         this._cachedPersonProperties = null
+        this.typed = createTypedEventCapture(this)
         this.featureFlags = new PostHogFeatureFlags(this)
         this.toolbar = new Toolbar(this)
         this.scrollManager = new ScrollManager(this)

packages/browser/src/types.ts

@@ -3,6 +3,9 @@ import type { SegmentAnalytics } from './extensions/segment-integration'
 import { PostHog } from './posthog-core'
 import { KnownUnsafeEditableEvent } from '@posthog/core'
 import { Survey } from './posthog-surveys-types'
+
+// Re-export PostHogEventSchemas from @posthog/core for typed events
+export type { PostHogEventSchemas } from '@posthog/core'
 // only importing types here, so won't affect the bundle
 // eslint-disable-next-line posthog-js/no-external-replay-imports
 import type { SAMPLED } from './extensions/replay/external/triggerMatching'

packages/core/src/index.ts

@@ -5,3 +5,4 @@ export { uuidv7 } from './vendor/uuidv7'
 export * from './posthog-core'
 export * from './posthog-core-stateless'
 export * from './types'
+export * from './typed-events'

packages/core/src/posthog-core.ts

@@ -28,6 +28,7 @@ import { Compression, PostHogPersistedProperty } from './types'
 import { maybeAdd, PostHogCoreStateless, QuotaLimitedFeature } from './posthog-core-stateless'
 import { uuidv7 } from './vendor/uuidv7'
 import { isPlainError } from './utils'
+import { TypedEventCapture, createTypedEventCapture } from './typed-events'
 
 export abstract class PostHogCore extends PostHogCoreStateless {
   // options
@@ -40,6 +41,9 @@ export abstract class PostHogCore extends PostHogCoreStateless {
   private _sessionMaxLengthSeconds: number = 24 * 60 * 60 // 24 hours
   protected sessionProps: PostHogEventProperties = {}
 
+  // Typed event capture instance
+  public readonly typed: TypedEventCapture<this>
+
   constructor(apiKey: string, options?: PostHogCoreOptions) {
     // Default for stateful mode is to not disable geoip. Only override if explicitly set
     const disableGeoipOption = options?.disableGeoip ?? false
@@ -51,6 +55,9 @@ export abstract class PostHogCore extends PostHogCoreStateless {
 
     this.sendFeatureFlagEvent = options?.sendFeatureFlagEvent ?? true
     this._sessionExpirationTimeSeconds = options?.sessionExpirationTimeSeconds ?? 1800 // 30 minutes
+
+    // Initialize typed event capture
+    this.typed = createTypedEventCapture(this)
   }
 
   protected setupBootstrap(options?: Partial<PostHogCoreOptions>): void {

packages/core/src/typed-events.ts

@@ -0,0 +1,51 @@
+/**
+ * Typed event capture infrastructure for PostHog.
+ *
+ * Event schemas can be augmented in PostHogEventSchemas interface via module augmentation.
+ * This is typically done by generated types from `posthog-cli schema pull`.
+ *
+ * @example
+ * // In your types file or generated file:
+ * declare module '@posthog/core' {
+ *   interface PostHogEventSchemas {
+ *     'user_signed_up': { plan: string; trial: boolean }
+ *     'purchase_completed': { amount: number; currency: string }
+ *   }
+ * }
+ *
+ * // Usage:
+ * posthog.typed.user_signed_up({ plan: 'pro', trial: true })
+ * posthog.typed.purchase_completed({ amount: 99.99, currency: 'USD' })
+ */
+
+import type { PostHogEventSchemas } from './types'
+
+// Utility type that allows schema properties plus any additional properties
+// The schema properties are strictly typed, additional ones are any
+export type EventWithAdditionalProperties<T> = T & Record<string, any>
+
+/**
+ * Mapped type that creates typed methods for each event in PostHogEventSchemas.
+ * Methods are generated dynamically based on the augmented interface.
+ */
+export type TypedEventCapture<Client extends { capture: (event: string, properties?: any) => any }> = {
+  [K in keyof PostHogEventSchemas]: (
+    properties: EventWithAdditionalProperties<PostHogEventSchemas[K]>
+  ) => ReturnType<Client['capture']>
+}
+
+/**
+ * Creates a Proxy that dynamically generates typed event methods
+ * based on the PostHogEventSchemas interface.
+ */
+export function createTypedEventCapture<Client extends { capture: (event: string, properties?: any) => any }>(
+  client: Client
+): TypedEventCapture<Client> {
+  return new Proxy({} as TypedEventCapture<Client>, {
+    get: (_target, eventName: string) => {
+      return (properties: any) => {
+        return client.capture(eventName, properties)
+      }
+    },
+  })
+}

packages/core/src/types.ts

@@ -129,6 +129,12 @@ export type PostHogEventProperties = {
   [key: string]: JsonType
 }
 
+// Event schemas can be augmented by generated types from posthog-cli schema pull
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface PostHogEventSchemas {
+  // This interface is intentionally empty and should be augmented by generated types
+}
+
 export type PostHogGroupProperties = {
   [type: string]: string | number
 }