@yraylabs/boring-analytics 0.1.0

package/README.md

@@ -0,0 +1,253 @@
+# boring-analytics
+
+Official SDK for [Boring Analytics](https://boringanalytics.io) — lightweight product analytics and error monitoring.
+
+- **Zero dependencies** — uses native `fetch` and `crypto`
+- **Works everywhere** — browser, Node.js, Edge runtimes
+- **TypeScript-first** — full type definitions included
+- **Tiny footprint** — tree-shakeable ESM + CJS builds
+- **Auto-batching** — queues events and flushes efficiently
+- **Error monitoring** — captures unhandled errors automatically
+
+## Installation
+
+```bash
+npm install boring-analytics
+```
+
+## Quick Start
+
+```typescript
+import { BoringAnalytics } from 'boring-analytics';
+
+const analytics = new BoringAnalytics({
+  apiKey: 'your-api-key',
+});
+
+// Track events
+analytics.track('button_clicked', {
+  properties: { buttonId: 'signup', page: '/home' },
+});
+
+// Identify users
+analytics.identify('user-123', {
+  traits: { email: 'user@example.com', name: 'Jane' },
+});
+
+// Track page views
+analytics.page('Home');
+```
+
+## Configuration
+
+```typescript
+const analytics = new BoringAnalytics({
+  // Required
+  apiKey: 'your-api-key',
+
+  // Optional
+  endpoint: 'https://api.boringanalytics.io',  // API endpoint
+  flushAt: 20,            // Flush after N queued items (default: 20)
+  flushInterval: 5000,    // Flush every N ms (default: 5000)
+  maxRetries: 3,          // Retry failed requests (default: 3)
+  debug: false,           // Log debug info to console
+
+  // Auto-capture
+  autoCapture: {
+    errors: true,          // Capture unhandled errors (default: true)
+    pageViews: false,      // Auto-track SPA navigation (default: false)
+  },
+
+  // Merged into every event
+  defaultProperties: {
+    appVersion: '1.2.0',
+    environment: 'production',
+  },
+
+  // Called on transport errors
+  onError: (err) => console.error('Analytics error:', err),
+});
+```
+
+## API
+
+### `track(name, options?)`
+
+Track a named event.
+
+```typescript
+analytics.track('purchase_completed', {
+  properties: {
+    orderId: 'order-456',
+    amount: 99.99,
+    currency: 'USD',
+  },
+});
+```
+
+### `identify(userId, options?)`
+
+Identify the current user. Sets the userId for all subsequent calls.
+
+```typescript
+analytics.identify('user-123', {
+  traits: {
+    email: 'user@example.com',
+    name: 'Jane Doe',
+    plan: 'pro',
+  },
+});
+```
+
+### `page(name?, options?)`
+
+Track a page view.
+
+```typescript
+analytics.page('Pricing');
+analytics.page('Product', {
+  properties: { productId: 'abc-123' },
+});
+```
+
+### `screen(name, options?)`
+
+Track a screen view (mobile apps).
+
+```typescript
+analytics.screen('Settings');
+```
+
+### `group(groupId, options?)`
+
+Associate the user with a group/organization.
+
+```typescript
+analytics.group('org-456', {
+  traits: { name: 'Acme Inc', plan: 'enterprise' },
+});
+```
+
+### `alias(userId, previousId)`
+
+Link two user identities.
+
+```typescript
+analytics.alias('user-123', 'anon-789');
+```
+
+### `captureError(error, options?)`
+
+Manually capture an error.
+
+```typescript
+try {
+  await riskyOperation();
+} catch (err) {
+  analytics.captureError(err, {
+    level: 'ERROR',             // DEBUG | INFO | WARNING | ERROR | FATAL
+    tags: { component: 'checkout' },
+    metadata: { orderId: '123' },
+    release: 'v1.2.3',
+    handled: true,
+  });
+}
+```
+
+### `flush()`
+
+Immediately send all queued events.
+
+```typescript
+await analytics.flush();
+```
+
+### `reset()`
+
+Clear the current user identity. Call on logout.
+
+```typescript
+analytics.reset();
+```
+
+### `shutdown()`
+
+Gracefully shut down — flushes remaining events and removes global error handlers.
+
+```typescript
+await analytics.shutdown();
+```
+
+## Auto Page View Tracking
+
+Enable automatic page view tracking for SPAs:
+
+```typescript
+const analytics = new BoringAnalytics({
+  apiKey: 'your-api-key',
+  autoCapture: {
+    pageViews: true,  // Tracks pushState, replaceState, and popstate
+  },
+});
+```
+
+## Error Monitoring
+
+Unhandled errors are captured automatically by default. You can also capture errors manually:
+
+```typescript
+// Automatic (enabled by default)
+// window.onerror and unhandledrejection are captured
+
+// Manual capture
+analytics.captureError(new Error('Something went wrong'), {
+  level: 'WARNING',
+  tags: { feature: 'checkout' },
+});
+```
+
+## Context Enrichment
+
+The SDK automatically captures context in the browser:
+- **Browser**: name, version
+- **OS**: name, version
+- **Device**: type (desktop/mobile/tablet)
+- **Page**: URL, referrer, title, path
+- **User Agent** and **Locale**
+
+You can override or extend context per-call:
+
+```typescript
+analytics.track('event', {
+  context: {
+    location: { country: 'US', city: 'San Francisco' },
+  },
+});
+```
+
+## Server-Side Usage (Node.js)
+
+```typescript
+import { BoringAnalytics } from 'boring-analytics';
+
+const analytics = new BoringAnalytics({
+  apiKey: 'your-server-api-key',
+  autoCapture: { errors: false },
+});
+
+// Track server-side events
+analytics.identify('user-123');
+analytics.track('api_request', {
+  properties: { endpoint: '/users', method: 'GET', duration: 42 },
+});
+
+// Flush before process exits
+process.on('SIGTERM', async () => {
+  await analytics.shutdown();
+  process.exit(0);
+});
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,190 @@
+interface BoringAnalyticsConfig {
+    apiKey: string;
+    endpoint?: string;
+    /** Max events to batch before auto-flushing (default: 20) */
+    flushAt?: number;
+    /** Interval in ms between auto-flushes (default: 5000) */
+    flushInterval?: number;
+    /** Max retry attempts for failed requests (default: 3) */
+    maxRetries?: number;
+    /** Auto-capture settings */
+    autoCapture?: {
+        /** Capture unhandled errors and promise rejections (default: true) */
+        errors?: boolean;
+        /** Auto-track page views on navigation — browser only (default: false) */
+        pageViews?: boolean;
+    };
+    /** Default properties merged into every event */
+    defaultProperties?: Record<string, unknown>;
+    /** Called on transport errors */
+    onError?: (error: Error) => void;
+    /** Enable debug logging to console (default: false) */
+    debug?: boolean;
+}
+type EventType = 'TRACK' | 'IDENTIFY' | 'PAGE' | 'SCREEN' | 'GROUP' | 'ALIAS';
+type ErrorLevel = 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR' | 'FATAL';
+interface EventContext {
+    ip?: string;
+    userAgent?: string;
+    locale?: string;
+    page?: {
+        url?: string;
+        referrer?: string;
+        title?: string;
+        path?: string;
+    };
+    device?: {
+        type?: string;
+    };
+    os?: {
+        name?: string;
+        version?: string;
+    };
+    browser?: {
+        name?: string;
+        version?: string;
+    };
+    location?: {
+        country?: string;
+        city?: string;
+        region?: string;
+    };
+    [key: string]: unknown;
+}
+interface IngestEventPayload {
+    type?: EventType;
+    name: string;
+    properties?: Record<string, unknown>;
+    timestamp?: string;
+    userId?: string;
+    sessionId?: string;
+    anonymousId?: string;
+    context?: EventContext;
+}
+interface IngestErrorPayload {
+    type: string;
+    message: string;
+    stackTrace?: string;
+    level?: ErrorLevel;
+    fingerprint?: string;
+    handled?: boolean;
+    metadata?: Record<string, unknown>;
+    tags?: Record<string, string>;
+    timestamp?: string;
+    userId?: string;
+    sessionId?: string;
+    context?: {
+        ip?: string;
+        userAgent?: string;
+        browser?: string;
+        os?: string;
+        device?: string;
+        url?: string;
+        release?: string;
+        [key: string]: unknown;
+    };
+}
+interface TrackOptions {
+    properties?: Record<string, unknown>;
+    timestamp?: Date;
+    context?: Partial<EventContext>;
+}
+interface IdentifyOptions {
+    traits?: Record<string, unknown>;
+    timestamp?: Date;
+    context?: Partial<EventContext>;
+}
+interface PageOptions {
+    properties?: Record<string, unknown>;
+    timestamp?: Date;
+    context?: Partial<EventContext>;
+}
+interface ScreenOptions {
+    properties?: Record<string, unknown>;
+    timestamp?: Date;
+    context?: Partial<EventContext>;
+}
+interface GroupOptions {
+    traits?: Record<string, unknown>;
+    timestamp?: Date;
+    context?: Partial<EventContext>;
+}
+interface CaptureErrorOptions {
+    level?: ErrorLevel;
+    metadata?: Record<string, unknown>;
+    tags?: Record<string, string>;
+    fingerprint?: string;
+    handled?: boolean;
+    timestamp?: Date;
+    release?: string;
+}
+
+declare class BoringAnalytics {
+    private queue;
+    private session;
+    private errorHandler;
+    private debug;
+    private config;
+    private pageViewUnsubscribe;
+    constructor(config: BoringAnalyticsConfig);
+    /**
+     * Track a named event.
+     *
+     * @example
+     * analytics.track('button_clicked', { properties: { buttonId: 'signup' } });
+     */
+    track(name: string, options?: TrackOptions): void;
+    /**
+     * Identify a user with traits.
+     * Sets the userId for all subsequent calls.
+     *
+     * @example
+     * analytics.identify('user-123', { traits: { email: 'user@example.com' } });
+     */
+    identify(userId: string, options?: IdentifyOptions): void;
+    /**
+     * Track a page view (typically browser).
+     *
+     * @example
+     * analytics.page('Home');
+     * analytics.page('Product', { properties: { productId: '123' } });
+     */
+    page(name?: string, options?: PageOptions): void;
+    /**
+     * Track a screen view (typically mobile).
+     */
+    screen(name: string, options?: ScreenOptions): void;
+    /**
+     * Associate a user with a group.
+     */
+    group(groupId: string, options?: GroupOptions): void;
+    /**
+     * Create an alias between two user identities.
+     */
+    alias(userId: string, previousId: string): void;
+    /**
+     * Capture an error for error monitoring.
+     *
+     * @example
+     * try { riskyOp(); }
+     * catch (err) { analytics.captureError(err, { tags: { env: 'prod' } }); }
+     */
+    captureError(error: Error | string, options?: CaptureErrorOptions): void;
+    /**
+     * Flush all queued events and errors immediately.
+     */
+    flush(): Promise<void>;
+    /**
+     * Reset the current user. Clears userId, generates new anonymousId and sessionId.
+     * Call this on logout.
+     */
+    reset(): void;
+    /**
+     * Gracefully shut down: flush remaining events, remove global handlers.
+     */
+    shutdown(): Promise<void>;
+    private enqueueEvent;
+    private installPageViewTracking;
+}
+
+export { BoringAnalytics, type BoringAnalyticsConfig, type CaptureErrorOptions, type ErrorLevel, type EventContext, type EventType, type GroupOptions, type IdentifyOptions, type IngestErrorPayload, type IngestEventPayload, type PageOptions, type ScreenOptions, type TrackOptions };

package/dist/index.d.ts

@@ -0,0 +1,190 @@
+interface BoringAnalyticsConfig {
+    apiKey: string;
+    endpoint?: string;
+    /** Max events to batch before auto-flushing (default: 20) */
+    flushAt?: number;
+    /** Interval in ms between auto-flushes (default: 5000) */
+    flushInterval?: number;
+    /** Max retry attempts for failed requests (default: 3) */
+    maxRetries?: number;
+    /** Auto-capture settings */
+    autoCapture?: {
+        /** Capture unhandled errors and promise rejections (default: true) */
+        errors?: boolean;
+        /** Auto-track page views on navigation — browser only (default: false) */
+        pageViews?: boolean;
+    };
+    /** Default properties merged into every event */
+    defaultProperties?: Record<string, unknown>;
+    /** Called on transport errors */
+    onError?: (error: Error) => void;
+    /** Enable debug logging to console (default: false) */
+    debug?: boolean;
+}
+type EventType = 'TRACK' | 'IDENTIFY' | 'PAGE' | 'SCREEN' | 'GROUP' | 'ALIAS';
+type ErrorLevel = 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR' | 'FATAL';
+interface EventContext {
+    ip?: string;
+    userAgent?: string;
+    locale?: string;
+    page?: {
+        url?: string;
+        referrer?: string;
+        title?: string;
+        path?: string;
+    };
+    device?: {
+        type?: string;
+    };
+    os?: {
+        name?: string;
+        version?: string;
+    };
+    browser?: {
+        name?: string;
+        version?: string;
+    };
+    location?: {
+        country?: string;
+        city?: string;
+        region?: string;
+    };
+    [key: string]: unknown;
+}
+interface IngestEventPayload {
+    type?: EventType;
+    name: string;
+    properties?: Record<string, unknown>;
+    timestamp?: string;
+    userId?: string;
+    sessionId?: string;
+    anonymousId?: string;
+    context?: EventContext;
+}
+interface IngestErrorPayload {
+    type: string;
+    message: string;
+    stackTrace?: string;
+    level?: ErrorLevel;
+    fingerprint?: string;
+    handled?: boolean;
+    metadata?: Record<string, unknown>;
+    tags?: Record<string, string>;
+    timestamp?: string;
+    userId?: string;
+    sessionId?: string;
+    context?: {
+        ip?: string;
+        userAgent?: string;
+        browser?: string;
+        os?: string;
+        device?: string;
+        url?: string;
+        release?: string;
+        [key: string]: unknown;
+    };
+}
+interface TrackOptions {
+    properties?: Record<string, unknown>;
+    timestamp?: Date;
+    context?: Partial<EventContext>;
+}
+interface IdentifyOptions {
+    traits?: Record<string, unknown>;
+    timestamp?: Date;
+    context?: Partial<EventContext>;
+}
+interface PageOptions {
+    properties?: Record<string, unknown>;
+    timestamp?: Date;
+    context?: Partial<EventContext>;
+}
+interface ScreenOptions {
+    properties?: Record<string, unknown>;
+    timestamp?: Date;
+    context?: Partial<EventContext>;
+}
+interface GroupOptions {
+    traits?: Record<string, unknown>;
+    timestamp?: Date;
+    context?: Partial<EventContext>;
+}
+interface CaptureErrorOptions {
+    level?: ErrorLevel;
+    metadata?: Record<string, unknown>;
+    tags?: Record<string, string>;
+    fingerprint?: string;
+    handled?: boolean;
+    timestamp?: Date;
+    release?: string;
+}
+
+declare class BoringAnalytics {
+    private queue;
+    private session;
+    private errorHandler;
+    private debug;
+    private config;
+    private pageViewUnsubscribe;
+    constructor(config: BoringAnalyticsConfig);
+    /**
+     * Track a named event.
+     *
+     * @example
+     * analytics.track('button_clicked', { properties: { buttonId: 'signup' } });
+     */
+    track(name: string, options?: TrackOptions): void;
+    /**
+     * Identify a user with traits.
+     * Sets the userId for all subsequent calls.
+     *
+     * @example
+     * analytics.identify('user-123', { traits: { email: 'user@example.com' } });
+     */
+    identify(userId: string, options?: IdentifyOptions): void;
+    /**
+     * Track a page view (typically browser).
+     *
+     * @example
+     * analytics.page('Home');
+     * analytics.page('Product', { properties: { productId: '123' } });
+     */
+    page(name?: string, options?: PageOptions): void;
+    /**
+     * Track a screen view (typically mobile).
+     */
+    screen(name: string, options?: ScreenOptions): void;
+    /**
+     * Associate a user with a group.
+     */
+    group(groupId: string, options?: GroupOptions): void;
+    /**
+     * Create an alias between two user identities.
+     */
+    alias(userId: string, previousId: string): void;
+    /**
+     * Capture an error for error monitoring.
+     *
+     * @example
+     * try { riskyOp(); }
+     * catch (err) { analytics.captureError(err, { tags: { env: 'prod' } }); }
+     */
+    captureError(error: Error | string, options?: CaptureErrorOptions): void;
+    /**
+     * Flush all queued events and errors immediately.
+     */
+    flush(): Promise<void>;
+    /**
+     * Reset the current user. Clears userId, generates new anonymousId and sessionId.
+     * Call this on logout.
+     */
+    reset(): void;
+    /**
+     * Gracefully shut down: flush remaining events, remove global handlers.
+     */
+    shutdown(): Promise<void>;
+    private enqueueEvent;
+    private installPageViewTracking;
+}
+
+export { BoringAnalytics, type BoringAnalyticsConfig, type CaptureErrorOptions, type ErrorLevel, type EventContext, type EventType, type GroupOptions, type IdentifyOptions, type IngestErrorPayload, type IngestEventPayload, type PageOptions, type ScreenOptions, type TrackOptions };