@stacksee/analytics 0.2.2

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+export * from './src/server'
+export {}

package/dist/server.js

@@ -0,0 +1,78 @@
+var o = Object.defineProperty;
+var f = (r, e, t) => e in r ? o(r, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : r[e] = t;
+var a = (r, e, t) => f(r, typeof e != "symbol" ? e + "" : e, t);
+class u {
+  constructor(e) {
+    a(this, "providers", []);
+    a(this, "config");
+    a(this, "initialized", !1);
+    this.config = e, this.providers = e.providers;
+  }
+  initialize() {
+    if (!this.initialized) {
+      for (const e of this.providers)
+        e.initialize();
+      this.initialized = !0;
+    }
+  }
+  identify(e, t) {
+    for (const i of this.providers)
+      i.identify(e, t);
+  }
+  async track(e, t, i) {
+    if (!this.initialized) {
+      console.warn("[Analytics] Not initialized. Call initialize() first.");
+      return;
+    }
+    const n = {
+      action: e,
+      category: this.getCategoryFromEventName(e),
+      properties: t,
+      timestamp: Date.now(),
+      userId: i == null ? void 0 : i.userId,
+      sessionId: i == null ? void 0 : i.sessionId
+    }, c = {
+      ...this.config.defaultContext,
+      ...i == null ? void 0 : i.context
+    }, d = this.providers.map(async (s) => {
+      try {
+        await s.track(n, c);
+      } catch (l) {
+        console.error(
+          `[Analytics] Provider ${s.name} failed to track event:`,
+          l
+        );
+      }
+    });
+    await Promise.all(d);
+  }
+  page(e, t) {
+    if (!this.initialized) return;
+    const i = {
+      ...this.config.defaultContext,
+      ...t == null ? void 0 : t.context
+    };
+    for (const n of this.providers)
+      n.page(e, i);
+  }
+  async shutdown() {
+    const e = this.providers.map((t) => "shutdown" in t && typeof t.shutdown == "function" ? t.shutdown() : Promise.resolve());
+    await Promise.all(e);
+  }
+  getCategoryFromEventName(e) {
+    const t = e.split("_");
+    return t.length > 1 && t[0] ? t[0] : "engagement";
+  }
+}
+function v(r) {
+  const e = {
+    providers: r.providers || [],
+    debug: r.debug,
+    enabled: r.enabled
+  }, t = new u(e);
+  return t.initialize(), t;
+}
+export {
+  u as ServerAnalytics,
+  v as createServerAnalytics
+};

package/dist/src/adapters/client/browser-analytics.d.ts

@@ -0,0 +1,24 @@
+import { AnyEventName, AnyEventProperties } from '../../core/events/index.js';
+import { AnalyticsConfig, EventContext } from '../../core/events/types.js';
+export declare class BrowserAnalytics<TEventName extends string = AnyEventName, TEventProperties extends Record<string, unknown> = AnyEventProperties> {
+    private providers;
+    private context;
+    private userId?;
+    private sessionId?;
+    private initialized;
+    private initializePromise?;
+    constructor(config: AnalyticsConfig);
+    initialize(): Promise<void>;
+    private _doInitialize;
+    private ensureInitialized;
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    track(eventName: TEventName, properties: TEventProperties): Promise<void>;
+    page(properties?: Record<string, unknown>): void;
+    reset(): void;
+    updateContext(context: Partial<EventContext>): void;
+    private getCategoryFromEventName;
+    private generateSessionId;
+    private getDeviceType;
+    private getOS;
+    private getBrowser;
+}

package/dist/src/adapters/server/server-analytics.d.ts

@@ -0,0 +1,20 @@
+import { AnyEventName, AnyEventProperties } from '../../core/events/index.js';
+import { AnalyticsConfig, EventContext } from '../../core/events/types.js';
+export declare class ServerAnalytics<TEventName extends string = AnyEventName, TEventProperties extends Record<string, unknown> = AnyEventProperties> {
+    private providers;
+    private config;
+    private initialized;
+    constructor(config: AnalyticsConfig);
+    initialize(): void;
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    track(eventName: TEventName, properties: TEventProperties, options?: {
+        userId?: string;
+        sessionId?: string;
+        context?: EventContext;
+    }): Promise<void>;
+    page(properties?: Record<string, unknown>, options?: {
+        context?: EventContext;
+    }): void;
+    shutdown(): Promise<void>;
+    private getCategoryFromEventName;
+}

package/dist/src/client/index.d.ts

@@ -0,0 +1,7 @@
+export { createClientAnalytics, createAnalytics, getAnalytics, track, identify, page, reset, type ClientAnalyticsConfig, } from '../client.js';
+export { BrowserAnalytics } from '../adapters/client/browser-analytics.js';
+export { PostHogClientProvider } from '../providers/posthog/client.js';
+export type { PostHogConfig } from '../providers/posthog/types.js';
+export { BaseAnalyticsProvider } from '../providers/base.provider.js';
+export type { EventCategory, BaseEvent, EventContext, AnalyticsProvider, AnalyticsConfig, } from '../core/events/types.js';
+export type { CreateEventDefinition, ExtractEventNames, ExtractEventPropertiesFromCollection, EventCollection, AnyEventName, AnyEventProperties, } from '../core/events/index.js';

package/dist/src/client.d.ts

@@ -0,0 +1,57 @@
+import { BrowserAnalytics } from './adapters/client/browser-analytics.js';
+import { AnalyticsProvider } from './core/events/types.js';
+export interface ClientAnalyticsConfig {
+    providers?: AnalyticsProvider[];
+    debug?: boolean;
+    enabled?: boolean;
+}
+/**
+ * Initialize analytics for the browser
+ *
+ * @example
+ * ```typescript
+ * import { createClientAnalytics } from '@stacksee/analytics/client';
+ * import { PostHogClientProvider } from '@stacksee/analytics/providers/posthog';
+ *
+ * const analytics = createClientAnalytics({
+ *   providers: [
+ *     new PostHogClientProvider({
+ *       apiKey: 'your-api-key',
+ *       host: 'https://app.posthog.com'
+ *     })
+ *   ],
+ *   debug: true,
+ *   enabled: true
+ * });
+ *
+ * // Optional: explicitly initialize (otherwise happens on first track/identify/page call)
+ * await analytics.initialize();
+ * ```
+ */
+export declare function createClientAnalytics(config: ClientAnalyticsConfig): BrowserAnalytics;
+export { createClientAnalytics as createAnalytics };
+/**
+ * Get the current analytics instance
+ */
+export declare function getAnalytics(): BrowserAnalytics;
+/**
+ * Convenience function to track events
+ */
+export declare function track(eventName: string, properties: Record<string, unknown>): Promise<void>;
+/**
+ * Convenience function to identify users
+ */
+export declare function identify(userId: string, traits?: Record<string, unknown>): void;
+/**
+ * Convenience function to track page views
+ */
+export declare function page(properties?: Record<string, unknown>): void;
+/**
+ * Convenience function to reset user session
+ */
+export declare function reset(): void;
+/**
+ * Reset the analytics instance (for testing purposes)
+ * @internal
+ */
+export declare function resetAnalyticsInstance(): void;

package/dist/src/core/events/index.d.ts

@@ -0,0 +1,18 @@
+export * from './types.js';
+export type CreateEventDefinition<TName extends string, TProperties extends Record<string, unknown> = Record<string, unknown>> = {
+    name: TName;
+    category: import('./types.js').EventCategory;
+    properties: TProperties;
+};
+export type ExtractEventNames<T extends Record<string, {
+    name: string;
+}>> = T[keyof T]["name"];
+export type ExtractEventPropertiesFromCollection<T extends Record<string, {
+    name: string;
+    properties: Record<string, unknown>;
+}>, TEventName extends ExtractEventNames<T>> = Extract<T[keyof T], {
+    name: TEventName;
+}>["properties"];
+export type EventCollection<T extends Record<string, CreateEventDefinition<string>>> = T;
+export type AnyEventName = string;
+export type AnyEventProperties = Record<string, unknown>;

package/dist/src/core/events/types.d.ts

@@ -0,0 +1,48 @@
+export type PredefinedEventCategory = "engagement" | "user" | "navigation" | "error" | "performance" | "conversion";
+export type EventCategory = PredefinedEventCategory | (string & Record<never, never>);
+export interface BaseEvent {
+    category: EventCategory;
+    action: string;
+    timestamp?: number;
+    userId?: string;
+    sessionId?: string;
+    properties?: Record<string, unknown>;
+}
+export interface EventContext {
+    page?: {
+        path: string;
+        title?: string;
+        referrer?: string;
+    };
+    device?: {
+        type?: string;
+        os?: string;
+        browser?: string;
+    };
+    campaign?: {
+        source?: string;
+        medium?: string;
+        name?: string;
+    };
+}
+export interface AnalyticsProvider {
+    name: string;
+    initialize(): Promise<void> | void;
+    identify(userId: string, traits?: Record<string, unknown>): Promise<void> | void;
+    track(event: BaseEvent, context?: EventContext): Promise<void> | void;
+    page(properties?: Record<string, unknown>, context?: EventContext): Promise<void> | void;
+    reset(): Promise<void> | void;
+}
+export interface AnalyticsConfig {
+    providers: AnalyticsProvider[];
+    debug?: boolean;
+    enabled?: boolean;
+    defaultContext?: Partial<EventContext>;
+}
+export type EventDefinition<T extends string, P = Record<string, unknown>> = {
+    name: T;
+    category: EventCategory;
+    properties?: P;
+};
+export type ExtractEventName<T> = T extends EventDefinition<infer N, unknown> ? N : never;
+export type ExtractEventProperties<T> = T extends EventDefinition<string, infer P> ? P : never;

package/dist/src/index.d.ts

@@ -0,0 +1,6 @@
+export type { EventCategory, BaseEvent, EventContext, AnalyticsProvider, AnalyticsConfig, } from './core/events/types.js';
+export type { CreateEventDefinition, ExtractEventNames, ExtractEventPropertiesFromCollection, EventCollection, AnyEventName, AnyEventProperties, } from './core/events/index.js';
+export { createAnalytics as createClientAnalytics, getAnalytics, track as trackClient, identify as identifyClient, page as pageClient, reset as resetClient, type ClientAnalyticsConfig, } from './client.js';
+export { createServerAnalytics, ServerAnalytics, type ServerAnalyticsConfig, } from './server.js';
+export { BaseAnalyticsProvider, PostHogClientProvider, PostHogServerProvider, type PostHogConfig, } from './providers/index.js';
+export { BrowserAnalytics } from './adapters/client/browser-analytics.js';

package/dist/src/providers/base.provider.d.ts

@@ -0,0 +1,17 @@
+import { AnalyticsProvider, BaseEvent, EventContext } from '../core/events/types.js';
+export declare abstract class BaseAnalyticsProvider implements AnalyticsProvider {
+    abstract name: string;
+    protected debug: boolean;
+    protected enabled: boolean;
+    constructor(config?: {
+        debug?: boolean;
+        enabled?: boolean;
+    });
+    abstract initialize(): Promise<void> | void;
+    abstract identify(userId: string, traits?: Record<string, unknown>): Promise<void> | void;
+    abstract track(event: BaseEvent, context?: EventContext): Promise<void> | void;
+    abstract page(properties?: Record<string, unknown>, context?: EventContext): Promise<void> | void;
+    abstract reset(): Promise<void> | void;
+    protected log(message: string, data?: unknown): void;
+    protected isEnabled(): boolean;
+}

package/dist/src/providers/index.d.ts

@@ -0,0 +1,4 @@
+export { BaseAnalyticsProvider } from './base.provider.js';
+export { PostHogClientProvider } from './posthog/client.js';
+export { PostHogServerProvider } from './posthog/server.js';
+export type { PostHogConfig } from './posthog/types.js';

package/dist/src/providers/posthog/client.d.ts

@@ -0,0 +1,24 @@
+import { BaseEvent, EventContext } from '../../core/events/types.js';
+import { BaseAnalyticsProvider } from '../base.provider.js';
+import { PostHogConfig } from './types.js';
+import { PostHog } from 'posthog-js';
+declare global {
+    interface Window {
+        posthog?: PostHog;
+    }
+}
+export declare class PostHogClientProvider extends BaseAnalyticsProvider {
+    name: string;
+    private posthog?;
+    private initialized;
+    private config;
+    constructor(config: PostHogConfig & {
+        debug?: boolean;
+        enabled?: boolean;
+    });
+    initialize(): Promise<void>;
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    track(event: BaseEvent, context?: EventContext): void;
+    page(properties?: Record<string, unknown>, context?: EventContext): void;
+    reset(): void;
+}

package/dist/src/providers/posthog/server.d.ts

@@ -0,0 +1,19 @@
+import { BaseEvent, EventContext } from '../../core/events/types.js';
+import { BaseAnalyticsProvider } from '../base.provider.js';
+import { PostHogConfig } from './types.js';
+export declare class PostHogServerProvider extends BaseAnalyticsProvider {
+    name: string;
+    private client?;
+    private initialized;
+    private config;
+    constructor(config: PostHogConfig & {
+        debug?: boolean;
+        enabled?: boolean;
+    });
+    initialize(): void;
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    track(event: BaseEvent, context?: EventContext): void;
+    page(properties?: Record<string, unknown>, context?: EventContext): void;
+    reset(): Promise<void>;
+    shutdown(): Promise<void>;
+}

package/dist/src/providers/posthog/types.d.ts

@@ -0,0 +1,27 @@
+export interface PostHogConfig {
+    apiKey: string;
+    host?: string;
+    autocapture?: boolean;
+    capturePageview?: boolean;
+    capturePageleave?: boolean;
+    debug?: boolean;
+    disableCookie?: boolean;
+    persistenceType?: "cookie" | "localStorage" | "memory";
+    personProfiles?: "always" | "never" | "identified_only";
+}
+export interface PostHogInstance {
+    init(apiKey: string, config?: Partial<PostHogConfig>): void;
+    identify(distinctId: string, properties?: Record<string, unknown>): void;
+    capture(event: string, properties?: Record<string, unknown>): void;
+    reset(): void;
+    debug(enabled?: boolean): void;
+    opt_out_capturing(): void;
+    opt_in_capturing(): void;
+    has_opted_out_capturing(): boolean;
+    get_distinct_id(): string;
+    alias(alias: string): void;
+    set_config(config: Partial<PostHogConfig>): void;
+    get_config<K extends keyof PostHogConfig>(key: K): PostHogConfig[K];
+    capture_pageview(): void;
+    capture_pageleave(): void;
+}

package/dist/src/server/index.d.ts

@@ -0,0 +1,6 @@
+export { createServerAnalytics, ServerAnalytics, type ServerAnalyticsConfig, } from '../server.js';
+export { PostHogServerProvider } from '../providers/posthog/server.js';
+export type { PostHogConfig } from '../providers/posthog/types.js';
+export { BaseAnalyticsProvider } from '../providers/base.provider.js';
+export type { EventCategory, BaseEvent, EventContext, AnalyticsProvider, AnalyticsConfig, } from '../core/events/types.js';
+export type { CreateEventDefinition, ExtractEventNames, ExtractEventPropertiesFromCollection, EventCollection, AnyEventName, AnyEventProperties, } from '../core/events/index.js';

package/dist/src/server.d.ts

@@ -0,0 +1,29 @@
+import { ServerAnalytics } from './adapters/server/server-analytics.js';
+import { AnalyticsProvider } from './core/events/types.js';
+export interface ServerAnalyticsConfig {
+    providers?: AnalyticsProvider[];
+    debug?: boolean;
+    enabled?: boolean;
+}
+/**
+ * Create a server analytics instance
+ *
+ * @example
+ * ```typescript
+ * import { createServerAnalytics } from '@stacksee/analytics/server';
+ * import { PostHogServerProvider } from '@stacksee/analytics/providers/posthog';
+ *
+ * const analytics = createServerAnalytics({
+ *   providers: [
+ *     new PostHogServerProvider({
+ *       apiKey: process.env.POSTHOG_API_KEY,
+ *       host: process.env.POSTHOG_HOST
+ *     })
+ *   ],
+ *   debug: true,
+ *   enabled: true
+ * });
+ * ```
+ */
+export declare function createServerAnalytics(config: ServerAnalyticsConfig): ServerAnalytics;
+export { ServerAnalytics };

package/dist/test/base-provider.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/client-analytics.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/events.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/mock-provider.d.ts

@@ -0,0 +1,29 @@
+import { BaseAnalyticsProvider } from '../src/providers/base.provider';
+import { BaseEvent, EventContext } from '../src/core/events/types';
+export declare class MockAnalyticsProvider extends BaseAnalyticsProvider {
+    name: string;
+    private initialized;
+    calls: {
+        initialize: number;
+        identify: Array<{
+            userId: string;
+            traits?: Record<string, unknown>;
+        }>;
+        track: Array<{
+            event: BaseEvent;
+            context?: EventContext;
+        }>;
+        page: Array<{
+            properties?: Record<string, unknown>;
+            context?: EventContext;
+        }>;
+        reset: number;
+    };
+    initialize(): void;
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    track(event: BaseEvent, context?: EventContext): void;
+    page(properties?: Record<string, unknown>, context?: EventContext): void;
+    reset(): void;
+    clearCalls(): void;
+    isInitialized(): boolean;
+}

package/dist/test/server-analytics.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@stacksee/analytics",
+  "version": "0.2.2",
+  "description": "A highly typed, provider-agnostic analytics library for TypeScript applications",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "analytics",
+    "typescript",
+    "posthog",
+    "tracking",
+    "events",
+    "type-safe"
+  ],
+  "author": "Chris Jayden <https://github.com/multiplehats>",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stackseehq/analytics.git"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "1.9.4",
+    "@changesets/cli": "^2.29.4",
+    "@svitejs/changesets-changelog-github-compact": "^1.2.0",
+    "@types/node": "^20.14.11",
+    "@vitest/coverage-v8": "2.1.9",
+    "globals": "^15.8.0",
+    "jsdom": "^26.1.0",
+    "prettier": "^3.3.3",
+    "typescript": "~5.5.3",
+    "vite": "^6.3.5",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^2.0.3"
+  },
+  "optionalDependencies": {
+    "posthog-js": "^1.96.0",
+    "posthog-node": "^3.2.0"
+  },
+  "engines": {
+    "pnpm": ">=9.0.0",
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "vite build",
+    "deploy": "npm publish",
+    "typecheck": "tsc --noEmit",
+    "ci:publish": "pnpm build && changeset publish",
+    "lint": "biome lint .",
+    "format": "biome format --write .",
+    "biome": "biome"
+  }
+}