@stacksee/analytics 0.2.2 → 0.3.2

package/dist/server.js

@@ -69,7 +69,9 @@ function v(r) {
     providers: r.providers || [],
     debug: r.debug,
     enabled: r.enabled
-  }, t = new u(e);
+  }, t = new u(
+    e
+  );
   return t.initialize(), t;
 }
 export {

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

@@ -1,6 +1,6 @@
-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> {
+type DefaultEventMap = Record<string, Record<string, unknown>>;
+export declare class BrowserAnalytics<TEventMap extends DefaultEventMap = DefaultEventMap> {
     private providers;
     private context;
     private userId?;
@@ -12,7 +12,7 @@ export declare class BrowserAnalytics<TEventName extends string = AnyEventName,
     private _doInitialize;
     private ensureInitialized;
     identify(userId: string, traits?: Record<string, unknown>): void;
-    track(eventName: TEventName, properties: TEventProperties): Promise<void>;
+    track<TEventName extends keyof TEventMap & string>(eventName: TEventName, properties: TEventMap[TEventName]): Promise<void>;
     page(properties?: Record<string, unknown>): void;
     reset(): void;
     updateContext(context: Partial<EventContext>): void;
@@ -22,3 +22,4 @@ export declare class BrowserAnalytics<TEventName extends string = AnyEventName,
     private getOS;
     private getBrowser;
 }
+export {};

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

@@ -1,13 +1,13 @@
-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> {
+type DefaultEventMap = Record<string, Record<string, unknown>>;
+export declare class ServerAnalytics<TEventMap extends DefaultEventMap = DefaultEventMap> {
     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?: {
+    track<TEventName extends keyof TEventMap & string>(eventName: TEventName, properties: TEventMap[TEventName], options?: {
         userId?: string;
         sessionId?: string;
         context?: EventContext;
@@ -18,3 +18,4 @@ export declare class ServerAnalytics<TEventName extends string = AnyEventName, T
     shutdown(): Promise<void>;
     private getCategoryFromEventName;
 }
+export {};

package/dist/src/client.d.ts

@@ -1,5 +1,14 @@
 import { BrowserAnalytics } from './adapters/client/browser-analytics.js';
 import { AnalyticsProvider } from './core/events/types.js';
+import { EventCollection } from './core/events/index.js';
+type DefaultEventMap = Record<string, Record<string, unknown>>;
+type EventMapFromCollection<T> = T extends EventCollection<infer Events> ? {
+    [K in keyof Events as Events[K] extends {
+        name: infer N;
+    } ? N extends string ? N : never : never]: Events[K] extends {
+        properties: infer P;
+    } ? P : never;
+} : never;
 export interface ClientAnalyticsConfig {
     providers?: AnalyticsProvider[];
     debug?: boolean;
@@ -12,8 +21,9 @@ export interface ClientAnalyticsConfig {
  * ```typescript
  * import { createClientAnalytics } from '@stacksee/analytics/client';
  * import { PostHogClientProvider } from '@stacksee/analytics/providers/posthog';
+ * import { AppEvents } from './events';
  *
- * const analytics = createClientAnalytics({
+ * const analytics = createClientAnalytics<typeof AppEvents>({
  *   providers: [
  *     new PostHogClientProvider({
  *       apiKey: 'your-api-key',
@@ -24,16 +34,20 @@ export interface ClientAnalyticsConfig {
  *   enabled: true
  * });
  *
- * // Optional: explicitly initialize (otherwise happens on first track/identify/page call)
- * await analytics.initialize();
+ * // Now event names and properties are fully typed!
+ * analytics.track('user_signed_up', {
+ *   userId: 'user-123',
+ *   email: 'user@example.com',
+ *   plan: 'pro'
+ * });
  * ```
  */
-export declare function createClientAnalytics(config: ClientAnalyticsConfig): BrowserAnalytics;
+export declare function createClientAnalytics<TEvents = never>(config: ClientAnalyticsConfig): BrowserAnalytics<EventMapFromCollection<TEvents>>;
 export { createClientAnalytics as createAnalytics };
 /**
  * Get the current analytics instance
  */
-export declare function getAnalytics(): BrowserAnalytics;
+export declare function getAnalytics(): BrowserAnalytics<DefaultEventMap>;
 /**
  * Convenience function to track events
  */

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

@@ -19,7 +19,7 @@ export interface EventContext {
         os?: string;
         browser?: string;
     };
-    campaign?: {
+    utm?: {
         source?: string;
         medium?: string;
         name?: string;

package/dist/src/server.d.ts

@@ -1,5 +1,13 @@
 import { ServerAnalytics } from './adapters/server/server-analytics.js';
 import { AnalyticsProvider } from './core/events/types.js';
+import { EventCollection } from './core/events/index.js';
+type EventMapFromCollection<T> = T extends EventCollection<infer Events> ? {
+    [K in keyof Events as Events[K] extends {
+        name: infer N;
+    } ? N extends string ? N : never : never]: Events[K] extends {
+        properties: infer P;
+    } ? P : never;
+} : never;
 export interface ServerAnalyticsConfig {
     providers?: AnalyticsProvider[];
     debug?: boolean;
@@ -12,8 +20,9 @@ export interface ServerAnalyticsConfig {
  * ```typescript
  * import { createServerAnalytics } from '@stacksee/analytics/server';
  * import { PostHogServerProvider } from '@stacksee/analytics/providers/posthog';
+ * import { AppEvents } from './events';
  *
- * const analytics = createServerAnalytics({
+ * const analytics = createServerAnalytics<typeof AppEvents>({
  *   providers: [
  *     new PostHogServerProvider({
  *       apiKey: process.env.POSTHOG_API_KEY,
@@ -23,7 +32,14 @@ export interface ServerAnalyticsConfig {
  *   debug: true,
  *   enabled: true
  * });
+ *
+ * // Now event names and properties are fully typed!
+ * await analytics.track('user_signed_up', {
+ *   userId: 'user-123',
+ *   email: 'user@example.com',
+ *   plan: 'pro'
+ * }, { userId: 'user-123' });
  * ```
  */
-export declare function createServerAnalytics(config: ServerAnalyticsConfig): ServerAnalytics;
+export declare function createServerAnalytics<TEvents = never>(config: ServerAnalyticsConfig): ServerAnalytics<EventMapFromCollection<TEvents>>;
 export { ServerAnalytics };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stacksee/analytics",
-  "version": "0.2.2",
+  "version": "0.3.2",
   "description": "A highly typed, provider-agnostic analytics library for TypeScript applications",
   "type": "module",
   "exports": {
@@ -15,6 +15,10 @@
     "./server": {
       "types": "./dist/server.d.ts",
       "import": "./dist/server.js"
+    },
+    "./providers": {
+      "types": "./dist/providers.d.ts",
+      "import": "./dist/providers.js"
     }
   },
   "main": "./dist/index.js",

package/readme.md

@@ -2,6 +2,38 @@
 
 A highly typed, provider-agnostic analytics library for TypeScript applications. Works seamlessly on both client and server sides with full type safety for your custom events.
 
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+  - [1. Define Your Events](#1-define-your-events)
+  - [2. Client-Side Usage](#2-client-side-usage)
+  - [3. Server-Side Usage](#3-server-side-usage)
+- [Async Tracking](#async-tracking-when-to-await-vs-fire-and-forget)
+  - [Fire-and-forget (Client-side typical usage)](#fire-and-forget-client-side-typical-usage)
+  - [Await for critical events (Server-side typical usage)](#await-for-critical-events-server-side-typical-usage)
+  - [Error handling](#error-handling)
+  - [Best practices](#best-practices)
+- [A complete example](#a-complete-example)
+- [Advanced Usage](#advanced-usage)
+  - [Creating a Typed Analytics Service](#creating-a-typed-analytics-service)
+  - [Event Categories](#event-categories)
+  - [Adding Custom Providers](#adding-custom-providers)
+  - [Client-Only and Server-Only Providers](#client-only-and-server-only-providers)
+  - [Using Multiple Providers](#using-multiple-providers)
+- [Server Deployments and waitUntil](#server-deployments-and-waituntil)
+  - [Vercel Functions](#vercel-functions)
+  - [Cloudflare Workers](#cloudflare-workers)
+  - [Netlify Functions](#netlify-functions)
+- [API Reference](#api-reference)
+  - [Client API](#client-api)
+  - [Server API](#server-api)
+  - [Type Helpers](#type-helpers)
+- [Best Practices](#best-practices)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Features
 
 - 🎯 **Type-safe events**: Define your own strongly typed events with full IntelliSense support
@@ -30,8 +62,7 @@ Create strongly typed events specific to your application:
 ```typescript
 import { CreateEventDefinition, EventCollection } from '@stacksee/analytics';
 
-// Define your event types
-export const AppEvents = {
+export const appEvents = {
   userSignedUp: {
     name: 'user_signed_up',
     category: 'user',
@@ -54,9 +85,10 @@ export const AppEvents = {
   }
 } as const satisfies EventCollection<Record<string, CreateEventDefinition<string>>>;
 
-// Extract types for use in your app
-export type AppEventName = keyof typeof AppEvents;
-export type AppEventProperties<T extends AppEventName> = typeof AppEvents[T]['properties'];
+// Optionally extract types for use in your app
+export type AppEvents = typeof appEvents;
+export type AppEventName = keyof typeof appEvents;
+export type AppEventProperties<T extends AppEventName> = typeof appEvents[T]['properties'];
 ```
 
 Tip: If you have a lot of events, you can also divide your events into multiple files, then export them as a single object.
@@ -66,10 +98,11 @@ Tip: If you have a lot of events, you can also divide your events into multiple
 ```typescript
 import { createClientAnalytics } from '@stacksee/analytics/client';
 import { PostHogClientProvider } from '@stacksee/analytics/providers/posthog';
-import { AppEvents } from './events';
+import type { AppEvents } from './events';
 
 // Initialize analytics with providers as plugins
-const analytics = createClientAnalytics({
+// Pass your event collection as a type parameter for full type safety
+const analytics = createClientAnalytics<AppEvents>({
   providers: [
     new PostHogClientProvider({
       apiKey: 'your-posthog-api-key',
@@ -81,20 +114,18 @@ const analytics = createClientAnalytics({
   enabled: true
 });
 
-// Track events with full type safety
-analytics.track(AppEvents.pageViewed.name, {
-  path: '/dashboard',
-  title: 'Dashboard',
-  referrer: document.referrer
-});
-
-analytics.track(AppEvents.userSignedUp.name, {
+// Track events with full type safety - event names and properties are typed!
+analytics.track('user_signed_up', {
   userId: 'user-123',
   email: 'user@example.com',
   plan: 'pro',
   referralSource: 'google'
 });
 
+// TypeScript will error if you use wrong event names or properties
+// analytics.track('wrong_event', {}); // ❌ Error: Argument of type '"wrong_event"' is not assignable
+// analytics.track('user_signed_up', { wrongProp: 'value' }); // ❌ Error: Object literal may only specify known properties
+
 // Identify users
 analytics.identify('user-123', {
   email: 'user@example.com',
@@ -108,10 +139,11 @@ analytics.identify('user-123', {
 ```typescript
 import { createServerAnalytics } from '@stacksee/analytics/server';
 import { PostHogServerProvider } from '@stacksee/analytics/providers/posthog';
-import { AppEvents } from './events';
+import type { AppEvents } from './events';
 
 // Create analytics instance with providers as plugins
-const analytics = createServerAnalytics({
+// Pass your event collection as a type parameter for full type safety
+const analytics = createServerAnalytics<AppEvents>({
   providers: [
     new PostHogServerProvider({
       apiKey: process.env.POSTHOG_API_KEY,
@@ -123,8 +155,8 @@ const analytics = createServerAnalytics({
   enabled: true
 });
 
-// Track events - now returns a Promise
-await analytics.track(AppEvents.featureUsed.name, {
+// Track events - now returns a Promise with full type safety
+await analytics.track('feature_used', {
   featureName: 'export-data',
   userId: 'user-123',
   duration: 1500
@@ -240,7 +272,7 @@ import { PostHogClientProvider } from '@stacksee/analytics/providers/posthog';
 import { PUBLIC_POSTHOG_API_KEY, PUBLIC_POSTHOG_HOST } from '$env/static/public';
 
 // Define your events for the waitlist
-export const AppEvents = {
+export const appEvents = {
   waitlistJoined: {
     name: 'waitlist_joined',
     category: 'user',
@@ -260,11 +292,11 @@ export const AppEvents = {
 } as const;
 
 // Client-side analytics instance
-export const clientAnalytics = createClientAnalytics({
+export const clientAnalytics = createClientAnalytics<AppEvents>({
   providers: [
     new PostHogClientProvider({
-      apiKey: import.meta.env.VITE_POSTHOG_KEY, // Ensure VITE_POSTHOG_KEY is in your .env file
-      host: 'https://app.posthog.com'
+      apiKey: PUBLIC_POSTHOG_API_KEY,
+      host: PUBLIC_POSTHOG_HOST
     })
   ],
   debug: import.meta.env.DEV
@@ -278,21 +310,21 @@ import { PostHogServerProvider } from '@stacksee/analytics/providers/posthog';
 import { AppEvents } from '$lib/config/analytics'; // Import AppEvents
 import { PUBLIC_POSTHOG_API_KEY, PUBLIC_POSTHOG_HOST } from '$env/static/public';
 
-export const serverAnalytics = createServerAnalytics({
+export const serverAnalytics = createServerAnalytics<AppEvents>({
   providers: [
     new PostHogServerProvider({
       apiKey: PUBLIC_POSTHOG_API_KEY,
       host: PUBLIC_POSTHOG_HOST
     })
   ],
-  debug: process.env.NODE_ENV === 'development'
+  debug: import.meta.env.DEV
 });
 ```
 
 ```svelte
 <!-- src/routes/join-waitlist/+page.svelte -->
 <script lang="ts">
-  import { clientAnalytics, AppEvents } from '$lib/config/analytics';
+  import { clientAnalytics } from '$lib/config/analytics';
 
   let email = $state('');
   let loading = $state(false);
@@ -305,7 +337,7 @@ export const serverAnalytics = createServerAnalytics({
 
     try {
       // Track waitlist joined event on the client
-      clientAnalytics.track(AppEvents.waitlistJoined.name, {
+      clientAnalytics.track('waitlist_joined', {
         email,
         source: 'waitlist_page_form'
       });
@@ -360,7 +392,6 @@ export const serverAnalytics = createServerAnalytics({
 ```typescript
 // src/routes/api/join-waitlist/+server.ts
 import { serverAnalytics } from '$lib/server/analytics';
-import { AppEvents } from '$lib/config/analytics'; // Import AppEvents
 import { json, type RequestHandler } from '@sveltejs/kit';
 
 async function approveUserForWaitlist(email: string): Promise<{ userId: string }> {
@@ -382,7 +413,7 @@ export const POST: RequestHandler = async ({ request }) => {
 
     const { userId } = await approveUserForWaitlist(email);
 
-    serverAnalytics.track(AppEvents.waitlistApproved.name, {
+    serverAnalytics.track('waitlist_approved', {
       userId,
       email
     }, {
@@ -414,55 +445,6 @@ export const POST: RequestHandler = async ({ request }) => {
 };
 ```
 
-## Advanced Usage
-
-### Creating a Typed Analytics Service
-
-For better type safety across your application, create a typed wrapper:
-
-```typescript
-import {
-  BrowserAnalytics,
-  ServerAnalytics,
-  ExtractEventNames,
-  ExtractEventPropertiesFromCollection
-} from '@stacksee/analytics';
-import { AppEvents } from './events';
-
-// Type aliases for your app
-type AppEventName = ExtractEventNames<typeof AppEvents>;
-type AppEventProps<T extends AppEventName> = ExtractEventPropertiesFromCollection<typeof AppEvents, T>;
-
-// Client-side typed wrapper
-export class AppAnalytics {
-  constructor(private analytics: BrowserAnalytics) {}
-
-  track<T extends AppEventName>(
-    eventName: T,
-    properties: AppEventProps<T>
-    ): Promise<void> {
-    return this.analytics.track(eventName, properties);
-  }
-
-  // ... other methods
-}
-
-// Server-side typed wrapper
-export class ServerAppAnalytics {
-  constructor(private analytics: ServerAnalytics) {}
-
-  track<T extends AppEventName>(
-    eventName: T,
-    properties: AppEventProps<T>,
-    options?: { userId?: string; sessionId?: string }
-  ): Promise<void> {
-    return this.analytics.track(eventName, properties, options);
-  }
-
-  // ... other methods
-}
-```
-
 ### Event Categories
 
 Event categories help organize your analytics data. The SDK provides predefined categories with TypeScript autocomplete:
@@ -478,7 +460,7 @@ Event categories help organize your analytics data. The SDK provides predefined
 You can also use **custom categories** for your specific needs:
 
 ```typescript
-export const AppEvents = {
+export const appEvents = {
   aiResponse: {
     name: 'ai_response_generated',
     category: 'ai', // Custom category
@@ -536,7 +518,7 @@ export class GoogleAnalyticsProvider extends BaseAnalyticsProvider {
 Then use it as a plugin in your configuration:
 
 ```typescript
-const analytics = await createClientAnalytics({
+const analytics = await createClientAnalytics<typeof AppEvents>({
   providers: [
     new PostHogClientProvider({ apiKey: 'xxx' }),
     new GoogleAnalyticsProvider({ measurementId: 'xxx' })
@@ -588,7 +570,7 @@ Then use the appropriate provider based on your environment:
 import { createClientAnalytics } from '@stacksee/analytics/client';
 import { MixpanelClientProvider } from './providers/mixpanel-client';
 
-const clientAnalytics = createClientAnalytics({
+const clientAnalytics = createClientAnalytics<typeof AppEvents>({
   providers: [
     new MixpanelClientProvider({ projectToken: 'xxx' })
   ]
@@ -598,7 +580,7 @@ const clientAnalytics = createClientAnalytics({
 import { createServerAnalytics } from '@stacksee/analytics/server';
 import { MixpanelServerProvider } from './providers/mixpanel-server';
 
-const serverAnalytics = createServerAnalytics({
+const serverAnalytics = createServerAnalytics<typeof AppEvents>({
   providers: [
     new MixpanelServerProvider({
       projectToken: 'xxx',
@@ -625,7 +607,7 @@ import { PostHogClientProvider } from '@stacksee/analytics/providers/posthog';
 import { GoogleAnalyticsProvider } from './providers/google-analytics';
 import { MixpanelProvider } from './providers/mixpanel';
 
-const analytics = createClientAnalytics({
+const analytics = createClientAnalytics<typeof AppEvents>({
   providers: [
     // PostHog for product analytics
     new PostHogClientProvider({
@@ -666,7 +648,7 @@ Vercel provides a `waitUntil` API that allows you to continue processing after t
 import { waitUntil } from '@vercel/functions';
 
 export default async function handler(req, res) {
-  const analytics = createServerAnalytics({
+  const analytics = createServerAnalytics<typeof AppEvents>({
     providers: [new PostHogServerProvider({ apiKey: process.env.POSTHOG_API_KEY })]
   });
 
@@ -695,7 +677,7 @@ Cloudflare Workers provides a `waitUntil` method on the execution context:
 ```typescript
 export default {
   async fetch(request, env, ctx) {
-    const analytics = createServerAnalytics({
+    const analytics = createServerAnalytics<typeof AppEvents>({
       providers: [new PostHogServerProvider({ apiKey: env.POSTHOG_API_KEY })]
     });
 
@@ -724,7 +706,7 @@ Netlify Functions also support `waitUntil` through their context object:
 
 ```typescript
 export async function handler(event, context) {
-  const analytics = createServerAnalytics({
+  const analytics = createServerAnalytics<AppEvents>({
     providers: [new PostHogServerProvider({ apiKey: process.env.POSTHOG_API_KEY })]
   });
 
@@ -758,15 +740,24 @@ export async function handler(event, context) {
 
 ### Client API
 
-#### `createClientAnalytics(config)`
-Initialize analytics for browser environment.
+#### `createClientAnalytics<TEvents>(config)`
+Initialize analytics for browser environment with optional type-safe events.
 
+- `TEvents` - (optional) Your event collection type for full type safety
 - `config.providers` - Array of analytics provider instances
 - `config.debug` - Enable debug logging
 - `config.enabled` - Enable/disable analytics
 
-#### `BrowserAnalytics`
-- `track(eventName, properties): Promise<void>` - Track an event (returns a promise)
+```typescript
+const analytics = createClientAnalytics<typeof AppEvents>({
+  providers: [/* ... */],
+  debug: true,
+  enabled: true
+});
+```
+
+#### `BrowserAnalytics<TEventMap>`
+- `track(eventName, properties): Promise<void>` - Track an event with type-safe event names and properties
 - `identify(userId, traits)` - Identify a user
 - `page(properties)` - Track a page view
 - `reset()` - Reset user session
@@ -774,15 +765,24 @@ Initialize analytics for browser environment.
 
 ### Server API
 
-#### `createServerAnalytics(config)`
-Create analytics instance for server environment.
+#### `createServerAnalytics<TEvents>(config)`
+Create analytics instance for server environment with optional type-safe events.
 
+- `TEvents` - (optional) Your event collection type for full type safety
 - `config.providers` - Array of analytics provider instances
 - `config.debug` - Enable debug logging
 - `config.enabled` - Enable/disable analytics
 
-#### `ServerAnalytics`
-- `track(eventName, properties, options): Promise<void>` - Track an event with optional context (returns a promise)
+```typescript
+const analytics = createServerAnalytics<AppEvents>({
+  providers: [/* ... */],
+  debug: true,
+  enabled: true
+});
+```
+
+#### `ServerAnalytics<TEventMap>`
+- `track(eventName, properties, options): Promise<void>` - Track an event with type-safe event names and properties
 - `identify(userId, traits)` - Identify a user
 - `page(properties, options)` - Track a page view
 - `shutdown()` - Flush pending events and cleanup