autotel-posthog 0.1.0

package/dist/subscriber.d.ts

@@ -0,0 +1,369 @@
+import { EventPayload, EventSubscriber } from "autotel-subscribers";
+import { EventAttributes } from "autotel/event-subscriber";
+import { PostHog } from "posthog-node";
+//#region src/values.d.ts
+/**
+ * Reading values that arrive from outside: a page's PostHog instance, an
+ * event's properties, an error someone threw. Nothing about them is known
+ * until one of these asks, and each answers with the type it looked for or
+ * `undefined`.
+ *
+ * This is the boundary. The `typeof` checks and the `unknown` parameters below
+ * are what a boundary is made of; past it, the package works with types.
+ *
+ * Internal - not exported from the package entry points.
+ */
+/** An object whose fields have not been read yet. */
+interface UnknownRecord {
+  [key: string]: unknown;
+}
+//#endregion
+//#region src/subscriber/index.d.ts
+/**
+ * Error context for enhanced error handling
+ *
+ * Provides detailed context about the event that caused an error.
+ */
+interface ErrorContext {
+  /** The error that occurred */
+  error: Error;
+  /** Event name (if applicable) */
+  eventName?: string;
+  /** Event type (event, funnel, outcome, value) */
+  eventType?: 'event' | 'funnel' | 'outcome' | 'value';
+  /** Event attributes (filtered) */
+  attributes?: EventAttributes;
+  /** Subscriber name */
+  subscriberName: string;
+}
+type StringRedactor = (value: string) => string;
+interface PostHogConfig {
+  /** PostHog API key (starts with phc_) - required if not providing custom client */
+  apiKey?: string;
+  /** PostHog host (defaults to US cloud) */
+  host?: string;
+  /** Enable/disable the subscriber */
+  enabled?: boolean;
+  /** Custom PostHog client instance (bypasses apiKey/host) */
+  client?: PostHog;
+  /**
+   * Use global browser client (window.posthog)
+   *
+   * When true, uses the PostHog client already loaded on the page via script tag.
+   * This is useful for Next.js apps that initialize PostHog in _app.tsx.
+   *
+   * @example
+   * ```typescript
+   * // Browser - uses window.posthog
+   * const subscriber = new PostHogSubscriber({
+   *   useGlobalClient: true,
+   * });
+   * ```
+   */
+  useGlobalClient?: boolean;
+  /**
+   * Serverless mode preset (AWS Lambda, Vercel Functions, Next.js API routes)
+   *
+   * When true, auto-configures for serverless environments:
+   * - flushAt: 1 (send immediately, don't batch)
+   * - flushInterval: 0 (disable interval-based flushing)
+   * - requestTimeout: 3000 (shorter timeout for fast responses)
+   *
+   * @example
+   * ```typescript
+   * // Vercel / Next.js API route
+   * const subscriber = new PostHogSubscriber({
+   *   apiKey: 'phc_...',
+   *   serverless: true,
+   * });
+   * ```
+   */
+  serverless?: boolean;
+  /** Flush batch when it reaches this size (default: 20, set to 1 for immediate send) */
+  flushAt?: number;
+  /** Flush interval in milliseconds (default: 10000, set to 0 to disable) */
+  flushInterval?: number;
+  /** Disable geoip lookup to reduce request size (default: false) */
+  disableGeoip?: boolean;
+  /** Request timeout in milliseconds (default: 10000) */
+  requestTimeout?: number;
+  /** Send feature flag evaluation events (default: true) */
+  sendFeatureFlags?: boolean;
+  /**
+   * Automatically filter out undefined and null values from attributes
+   *
+   * When true (default), undefined and null values are removed before sending.
+   * This improves DX when passing objects with optional properties.
+   *
+   * @default true
+   *
+   * @example
+   * ```typescript
+   * // With filterUndefinedValues: true (default)
+   * subscriber.trackEvent('user.action', {
+   *   userId: user.id,
+   *   email: user.email,        // might be undefined - will be filtered
+   *   plan: user.subscription,  // might be null - will be filtered
+   * });
+   * ```
+   */
+  filterUndefinedValues?: boolean;
+  /** Error callback for debugging and monitoring */
+  onError?: (error: Error) => void;
+  /**
+   * Enhanced error callback with event context
+   *
+   * Provides detailed context about the event that caused the error.
+   * If both onError and onErrorWithContext are provided, both are called.
+   *
+   * @example
+   * ```typescript
+   * const subscriber = new PostHogSubscriber({
+   *   apiKey: 'phc_...',
+   *   onErrorWithContext: (ctx) => {
+   *     console.error(`Failed to track ${ctx.eventType}: ${ctx.eventName}`, ctx.error);
+   *     Sentry.captureException(ctx.error, { extra: ctx });
+   *   }
+   * });
+   * ```
+   */
+  onErrorWithContext?: (context: ErrorContext) => void;
+  /** Known attribute paths to redact using slow-redact (path-based, immutable). */
+  redactPaths?: string[];
+  /** String redactor for value-based PII scanning. Applied after path-based redaction. */
+  stringRedactor?: StringRedactor;
+  /** Enable debug logging (default: false) */
+  debug?: boolean;
+}
+/**
+ * PostHog feature flag options
+ */
+interface FeatureFlagOptions {
+  /** Group context for group-based feature flags */
+  groups?: Record<string, string | number>;
+  /** Group properties for feature flag evaluation */
+  groupProperties?: Record<string, Record<string, any>>;
+  /** Person properties for feature flag evaluation */
+  personProperties?: Record<string, any>;
+  /** Only evaluate locally, don't send $feature_flag_called event */
+  onlyEvaluateLocally?: boolean;
+  /** Send feature flag events even if disabled globally */
+  sendFeatureFlagEvents?: boolean;
+}
+/**
+ * Person properties for identify calls
+ */
+interface PersonProperties {
+  /** Set properties (will update existing values) */
+  $set?: Record<string, any>;
+  /** Set properties only if they don't exist */
+  $set_once?: Record<string, any>;
+  /** Any custom properties */
+  [key: string]: any;
+}
+declare class PostHogSubscriber extends EventSubscriber {
+  readonly name = "PostHogSubscriber";
+  readonly version = "2.0.0";
+  private posthog;
+  private config;
+  private initPromise;
+  /** True when using browser's window.posthog (different API signature) */
+  private isBrowserClient;
+  /**
+   * The same client seen through the browser SDK's shape.
+   *
+   * The two SDKs disagree about `capture`: Node takes one object, the browser
+   * takes a name and properties. Rather than cast at each call site, the cast
+   * happens once here and the calls are typed against `posthog-js` itself — so
+   * a change to the browser signature is a compile error rather than a runtime
+   * one in a page.
+   */
+  private get browserClient();
+  private pathRedactor;
+  private stringRedactor;
+  constructor(config: PostHogConfig);
+  private initialize;
+  private setupErrorHandling;
+  private ensureInitialized;
+  /**
+   * Feature-flag options as posthog-node's own parameter type.
+   *
+   * SAFETY: FeatureFlagOptions above mirrors the fields posthog-node accepts -
+   * groups, person and group properties, and the two evaluation switches. The
+   * SDK declares them inline on each method rather than as a named type, so
+   * the correspondence is stated here once instead of at each call.
+   */
+  private flagOptions;
+  private extractDistinctId;
+  private redactProperties;
+  private redactStringValues;
+  private redactArray;
+  /** One value, redacted: a string masked, a container walked. */
+  private redactValue;
+  /**
+   * Set the string redactor. Called by autotel init() when attributeRedactor is configured.
+   * Can also be called manually.
+   */
+  setStringRedactor(redactor: StringRedactor): void;
+  /**
+   * Send payload to PostHog
+   *
+   * Maps autotel context to PostHog-specific field names:
+   * - autotel.trace_id → $trace_id
+   * - autotel.span_id → $span_id
+   * - autotel.correlation_id → $correlation_id
+   * - autotel.trace_url → $trace_url
+   */
+  protected sendToDestination(payload: EventPayload): Promise<void>;
+  /**
+   * Check if a feature flag is enabled for a user
+   *
+   * @param flagKey - Feature flag key
+   * @param distinctId - User ID or anonymous ID
+   * @param options - Feature flag evaluation options
+   * @returns true if enabled, false otherwise
+   *
+   * @example
+   * ```typescript
+   * const isEnabled = await subscriber.isFeatureEnabled('new-checkout', 'user-123');
+   *
+   * // With groups
+   * const isEnabled = await subscriber.isFeatureEnabled('beta-features', 'user-123', {
+   *   groups: { company: 'acme-corp' }
+   * });
+   * ```
+   */
+  isFeatureEnabled(flagKey: string, distinctId: string, options?: FeatureFlagOptions): Promise<boolean>;
+  /**
+   * Get feature flag value for a user
+   *
+   * @param flagKey - Feature flag key
+   * @param distinctId - User ID or anonymous ID
+   * @param options - Feature flag evaluation options
+   * @returns Flag value (string, boolean, or undefined)
+   *
+   * @example
+   * ```typescript
+   * const variant = await subscriber.getFeatureFlag('experiment-variant', 'user-123');
+   * // Returns: 'control' | 'test' | 'test-2' | undefined
+   *
+   * // With person properties
+   * const variant = await subscriber.getFeatureFlag('premium-feature', 'user-123', {
+   *   personProperties: { plan: 'premium' }
+   * });
+   * ```
+   */
+  getFeatureFlag(flagKey: string, distinctId: string, options?: FeatureFlagOptions): Promise<string | boolean | undefined>;
+  /**
+   * Get all feature flags for a user
+   *
+   * @param distinctId - User ID or anonymous ID
+   * @param options - Feature flag evaluation options
+   * @returns Object mapping flag keys to their values
+   *
+   * @example
+   * ```typescript
+   * const flags = await subscriber.getAllFlags('user-123');
+   * // Returns: { 'new-checkout': true, 'experiment-variant': 'test', ... }
+   * ```
+   */
+  getAllFlags(distinctId: string, options?: FeatureFlagOptions): Promise<Record<string, string | number | boolean>>;
+  /**
+   * Reload feature flags from PostHog server
+   *
+   * Call this to refresh feature flag definitions without restarting.
+   *
+   * @example
+   * ```typescript
+   * await subscriber.reloadFeatureFlags();
+   * ```
+   */
+  reloadFeatureFlags(): Promise<void>;
+  /**
+   * Identify a user and set their properties
+   *
+   * @param distinctId - User ID
+   * @param properties - Person properties ($set, $set_once, or custom properties)
+   *
+   * @example
+   * ```typescript
+   * // Set properties (will update existing values)
+   * await subscriber.identify('user-123', {
+   *   $set: {
+   *     email: 'user@example.com',
+   *     plan: 'premium'
+   *   }
+   * });
+   *
+   * // Set properties only once (won't update if already exists)
+   * await subscriber.identify('user-123', {
+   *   $set_once: {
+   *     signup_date: '2025-01-17'
+   *   }
+   * });
+   * ```
+   */
+  identify(distinctId: string, properties?: PersonProperties): Promise<void>;
+  /**
+   * Identify a group and set its properties
+   *
+   * Groups are useful for B2B SaaS to track organizations, teams, or accounts.
+   *
+   * @param groupType - Type of group (e.g., 'company', 'organization', 'team')
+   * @param groupKey - Unique identifier for the group
+   * @param properties - Group properties
+   *
+   * @example
+   * ```typescript
+   * await subscriber.groupIdentify('company', 'acme-corp', {
+   *   $set: {
+   *     name: 'Acme Corporation',
+   *     industry: 'saas',
+   *     employees: 500,
+   *     plan: 'enterprise'
+   *   }
+   * });
+   * ```
+   */
+  groupIdentify(groupType: string, groupKey: string | number, properties?: Record<string, any>): Promise<void>;
+  /**
+   * Track an event with group context
+   *
+   * Use this to associate events with groups (e.g., organizations).
+   *
+   * @param name - Event name
+   * @param attributes - Event attributes
+   * @param groups - Group context (e.g., { company: 'acme-corp' })
+   *
+   * @example
+   * ```typescript
+   * await subscriber.trackEventWithGroups('feature.used', {
+   *   userId: 'user-123',
+   *   feature: 'advanced-events'
+   * }, {
+   *   company: 'acme-corp'
+   * });
+   * ```
+   */
+  trackEventWithGroups(name: string, attributes?: EventAttributes, groups?: Record<string, string | number>): Promise<void>;
+  /**
+   * Capture an exception and send to PostHog error tracking.
+   *
+   * If using browser client (window.posthog), delegates to its captureException.
+   * Otherwise, formats and sends via posthog-node capture API.
+   */
+  captureException(error: unknown, options?: {
+    distinctId?: string;
+    additionalProperties?: UnknownRecord;
+  }): Promise<void>;
+  /**
+   * Flush pending events and clean up resources
+   */
+  shutdown(): Promise<void>;
+  /**
+   * Handle errors with custom error handler
+   */
+  protected handleError(error: Error, payload: EventPayload): void;
+}
+//#endregion
+export { ErrorContext, FeatureFlagOptions, PersonProperties, PostHogConfig, PostHogSubscriber };