@thisbefine/analytics 0.2.1 → 0.3.1

package/README.md

@@ -169,6 +169,38 @@ analytics.log('Cache miss for user preferences', 'debug', {
 });
 ```
 
+### Lifecycle Events
+
+Track key SaaS milestones with built-in methods. These use reserved event names (prefixed with `$`) and typed properties for consistent analytics.
+
+```typescript
+// User lifecycle
+analytics.signup({ method: 'google', plan: 'free' });
+analytics.login({ method: 'passkey', isNewDevice: true });
+analytics.logout({ reason: 'manual' });
+analytics.accountDeleted({ reason: 'not_using', tenure: 45 });
+
+// Subscription events
+analytics.subscriptionStarted({ plan: 'pro', interval: 'monthly', mrr: 29 });
+analytics.subscriptionCancelled({ plan: 'pro', reason: 'too_expensive', mrr: 29 });
+analytics.subscriptionRenewed({ plan: 'pro', renewalCount: 12 });
+
+// Plan changes
+analytics.planUpgraded({ fromPlan: 'starter', toPlan: 'pro', mrrChange: 20 });
+analytics.planDowngraded({ fromPlan: 'pro', toPlan: 'starter', reason: 'budget' });
+
+// Trials
+analytics.trialStarted({ plan: 'pro', trialDays: 14 });
+analytics.trialEnded({ plan: 'pro', converted: true });
+
+// Team/collaboration
+analytics.inviteSent({ inviteEmail: 'teammate@company.com', role: 'editor' });
+analytics.inviteAccepted({ invitedBy: 'user_123', role: 'editor' });
+
+// Feature adoption
+analytics.featureActivated({ feature: 'dark_mode', isFirstTime: true });
+```
+
 ### Privacy Controls
 
 Because being creepy is bad for business.
@@ -187,6 +219,36 @@ if (analytics.isOptedOut()) {
 analytics.optIn();
 ```
 
+### Consent Management
+
+Granular control over tracking categories for GDPR/CCPA compliance.
+
+```typescript
+// Configure consent categories on init
+const analytics = createAnalytics({
+  apiKey: 'tbf_xxx',
+  consent: {
+    categories: ['analytics', 'marketing', 'functional'],
+    defaultConsent: false, // Don't track until explicit consent
+  },
+});
+
+// Check if a category is enabled
+if (analytics.hasConsent('marketing')) {
+  // Show personalized content
+}
+
+// Get all consented categories
+const categories = analytics.getConsentedCategories();
+
+// Set consent (replaces current consent)
+analytics.setConsent(['analytics', 'functional']);
+
+// Grant/revoke individual categories
+analytics.grantConsent('marketing');
+analytics.revokeConsent('marketing');
+```
+
 ## React Hooks
 
 All hooks are available from both `@thisbefine/analytics/react` and `@thisbefine/analytics/next`.
@@ -289,9 +351,10 @@ const analytics = createAnalytics({
   // Required
   apiKey: 'tbf_xxx',
 
-  // Optional
+  // Optional - Basic
   host: 'https://thisbefine.com',     // API endpoint
   debug: false,                        // Console logging
+  structuredLogging: false,            // Output debug logs as JSON
   flushAt: 20,                         // Batch size before sending
   flushInterval: 10000,                // Ms between flushes
   sessionTimeout: 1800000,             // 30 min session timeout
@@ -299,12 +362,46 @@ const analytics = createAnalytics({
   respectDNT: true,                    // Honor Do Not Track
   maxRetries: 3,                       // Retry failed requests
 
-  // Error tracking config
+  // Error tracking
   errors: {
     enabled: true,
     captureUnhandled: true,
     captureConsoleErrors: true,
   },
+
+  // Lifecycle hooks
+  onFlushError: (error, failedEvents) => {
+    console.error('Failed to send events:', error);
+    // Log to your error tracking service
+  },
+  beforeSend: (event) => {
+    // Scrub PII from event properties
+    if (event.type === 'track' && event.properties?.email) {
+      const { email, ...rest } = event.properties;
+      return { ...event, properties: rest };
+    }
+    // Return null to discard the event
+    return event;
+  },
+
+  // Queue persistence (crash recovery)
+  persistQueue: true,                  // Save queue to localStorage
+  maxPersistedEvents: 1000,            // Max events to persist
+
+  // Privacy & consent
+  anonymousIdMaxAge: 2592000000,       // Rotate anonymous ID every 30 days
+  consent: {
+    categories: ['analytics', 'marketing', 'functional'],
+    defaultConsent: true,              // Track by default (respects DNT)
+  },
+
+  // Rate limiting & sampling
+  maxEventsPerSecond: 100,             // Drop events exceeding this rate
+  sampleRate: 1,                       // 1 = 100%, 0.5 = 50% of events
+
+  // Circuit breaker (stops hammering failed servers)
+  circuitBreakerThreshold: 5,          // Open after N consecutive failures
+  circuitBreakerResetTimeout: 30000,   // Try again after 30s
 });
 ```
 
@@ -334,12 +431,44 @@ const analytics = createAnalytics({
 | `page(name?, properties?)` | Track a page view |
 | `group(accountId, traits?)` | Associate user with account |
 | `reset()` | Clear user data (call on logout) |
-| `flush()` | Force send queued events |
+| `flush()` | Force send queued events (returns `FlushResult`) |
+| `destroy()` | Clean up resources, flush remaining events |
 | `optOut()` | Disable tracking |
 | `optIn()` | Re-enable tracking |
 | `isOptedOut()` | Check opt-out status |
 | `getUser()` | Get current user state |
 
+### Consent Methods
+
+| Method | Description |
+|--------|-------------|
+| `hasConsent(category)` | Check if a category is enabled |
+| `getConsentedCategories()` | Get all consented categories |
+| `setConsent(categories)` | Set consent (replaces current) |
+| `grantConsent(category)` | Enable a category |
+| `revokeConsent(category)` | Disable a category |
+
+Categories: `analytics` | `marketing` | `functional`
+
+### Lifecycle Methods
+
+| Method | Description |
+|--------|-------------|
+| `signup(props?)` | Track user signup |
+| `login(props?)` | Track user login |
+| `logout(props?)` | Track user logout |
+| `accountDeleted(props?)` | Track account deletion |
+| `subscriptionStarted(props)` | Track subscription start |
+| `subscriptionCancelled(props)` | Track subscription cancellation |
+| `subscriptionRenewed(props)` | Track subscription renewal |
+| `planUpgraded(props)` | Track plan upgrade |
+| `planDowngraded(props)` | Track plan downgrade |
+| `trialStarted(props)` | Track trial start |
+| `trialEnded(props)` | Track trial end |
+| `inviteSent(props?)` | Track invite sent |
+| `inviteAccepted(props?)` | Track invite accepted |
+| `featureActivated(props)` | Track feature activation |
+
 ### Error Tracking Methods
 
 | Method | Description |
@@ -376,11 +505,40 @@ Full type definitions included:
 
 ```typescript
 import type {
+  // Core types
   Analytics,
   AnalyticsConfig,
   UserState,
   UserTraits,
   AccountTraits,
+  FlushResult,
+
+  // Event types
+  AnalyticsEvent,
+  TrackEvent,
+  IdentifyEvent,
+  PageEvent,
+  GroupEvent,
+
+  // Hooks
+  BeforeSend,
+  OnFlushError,
+
+  // Lifecycle event props
+  SignupProps,
+  LoginProps,
+  LogoutProps,
+  AccountDeletedProps,
+  SubscriptionStartedProps,
+  SubscriptionCancelledProps,
+  SubscriptionRenewedProps,
+  PlanUpgradedProps,
+  PlanDowngradedProps,
+  TrialStartedProps,
+  TrialEndedProps,
+  InviteSentProps,
+  InviteAcceptedProps,
+  FeatureActivatedProps,
 } from '@thisbefine/analytics';
 ```
 

package/dist/core/analytics.d.ts

@@ -1,6 +1,6 @@
 import { type AccountDeletedProps, type FeatureActivatedProps, type InviteAcceptedProps, type InviteSentProps, type LoginProps, type LogoutProps, type PlanDowngradedProps, type PlanUpgradedProps, type SignupProps, type SubscriptionCancelledProps, type SubscriptionRenewedProps, type SubscriptionStartedProps, type TrialEndedProps, type TrialStartedProps } from "./lifecycle";
 import type { LogLevel } from "./logging";
-import type { AccountTraits, Analytics, AnalyticsConfig, UserState, UserTraits } from "./types";
+import type { AccountTraits, Analytics, AnalyticsConfig, ConsentCategory, FlushResult, UserState, UserTraits } from "./types";
 /**
  * Main Analytics class - the primary entry point for the SDK
  *
@@ -22,11 +22,26 @@ export declare class AnalyticsImpl implements Analytics {
     private errorCapture;
     private initialized;
     private logger;
+    private eventTimestamps;
+    private rateLimitWarned;
     constructor(config: AnalyticsConfig);
     /**
      * Resolve configuration with defaults
      */
     private resolveConfig;
+    /**
+     * Queue an event, applying sampling, rate limiting and beforeSend hook if configured
+     */
+    private queueEvent;
+    /**
+     * Check if event should be sampled based on sampleRate
+     */
+    private shouldSample;
+    /**
+     * Check if event should be allowed based on rate limit
+     * Uses a sliding window algorithm
+     */
+    private checkRateLimit;
     /**
      * Track a custom event
      */
@@ -69,8 +84,15 @@ export declare class AnalyticsImpl implements Analytics {
     reset(): void;
     /**
      * Manually flush the event queue
+     * @returns FlushResult with success status, event count, and any errors
+     */
+    flush(): Promise<FlushResult>;
+    /**
+     * Destroy the analytics instance, cleaning up all resources.
+     * Flushes remaining events before cleanup.
+     * After calling this, the instance should not be used.
      */
-    flush(): Promise<void>;
+    destroy(): Promise<void>;
     /**
      * Opt out of tracking
      */
@@ -83,6 +105,26 @@ export declare class AnalyticsImpl implements Analytics {
      * Check if user has opted out
      */
     isOptedOut(): boolean;
+    /**
+     * Check if a specific consent category is enabled
+     */
+    hasConsent(category: ConsentCategory): boolean;
+    /**
+     * Get all currently consented categories
+     */
+    getConsentedCategories(): ConsentCategory[];
+    /**
+     * Set consent for specific categories
+     */
+    setConsent(categories: ConsentCategory[]): void;
+    /**
+     * Grant consent for a specific category
+     */
+    grantConsent(category: ConsentCategory): void;
+    /**
+     * Revoke consent for a specific category
+     */
+    revokeConsent(category: ConsentCategory): void;
     /**
      * Get current user state
      */

package/dist/core/analytics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../src/core/analytics.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../src/core/analytics.ts"],"names":[],"mappings":"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"}

package/dist/core/analytics.js

@@ -5,7 +5,7 @@ import { log as sendLog } from "./logging";
 import { Privacy } from "./privacy";
 import { Queue } from "./queue";
 import { Session } from "./session";
-import { Storage } from "./storage";
+import { generateId, Storage } from "./storage";
 import { DEFAULT_CONFIG, LIBRARY_INFO } from "./types";
 import { validateAccountId, validateEventName, validateProperties, validateUserId, } from "./validation";
 /**
@@ -24,11 +24,13 @@ export class AnalyticsImpl {
     constructor(config) {
         this.errorCapture = null;
         this.initialized = false;
+        this.eventTimestamps = [];
+        this.rateLimitWarned = false;
         this.config = this.resolveConfig(config);
-        this.logger = createLogger("Analytics", this.config.debug);
+        this.logger = createLogger("Analytics", this.config.debug, this.config.structuredLogging);
         this.storage = new Storage(this.config.cookieDomain);
-        this.session = new Session(this.storage, this.config.sessionTimeout, this.config.debug);
-        this.privacy = new Privacy(this.storage, this.config.respectDNT, this.config.debug);
+        this.session = new Session(this.storage, this.config.sessionTimeout, this.config.debug, this.config.anonymousIdMaxAge);
+        this.privacy = new Privacy(this.storage, this.config.respectDNT, this.config.debug, this.config.consent);
         this.queue = new Queue(this.config);
         if (this.config.errors?.enabled !== false) {
             this.errorCapture = new ErrorCapture(this.config, this.session, this.config.errors);
@@ -57,8 +59,84 @@ export class AnalyticsImpl {
             respectDNT: config.respectDNT ?? DEFAULT_CONFIG.respectDNT,
             maxRetries: config.maxRetries ?? DEFAULT_CONFIG.maxRetries,
             errors: config.errors,
+            onFlushError: config.onFlushError,
+            persistQueue: config.persistQueue ?? DEFAULT_CONFIG.persistQueue,
+            maxPersistedEvents: config.maxPersistedEvents ?? DEFAULT_CONFIG.maxPersistedEvents,
+            beforeSend: config.beforeSend,
+            anonymousIdMaxAge: config.anonymousIdMaxAge ?? DEFAULT_CONFIG.anonymousIdMaxAge,
+            circuitBreakerThreshold: config.circuitBreakerThreshold ??
+                DEFAULT_CONFIG.circuitBreakerThreshold,
+            circuitBreakerResetTimeout: config.circuitBreakerResetTimeout ??
+                DEFAULT_CONFIG.circuitBreakerResetTimeout,
+            consent: config.consent,
+            maxEventsPerSecond: config.maxEventsPerSecond ?? DEFAULT_CONFIG.maxEventsPerSecond,
+            sampleRate: Math.max(0, Math.min(1, config.sampleRate ?? DEFAULT_CONFIG.sampleRate)),
+            structuredLogging: config.structuredLogging ?? DEFAULT_CONFIG.structuredLogging,
         };
     }
+    /**
+     * Queue an event, applying sampling, rate limiting and beforeSend hook if configured
+     */
+    queueEvent(event) {
+        if (!this.shouldSample()) {
+            this.logger.log("Event dropped by sampling");
+            return;
+        }
+        if (!this.checkRateLimit()) {
+            return;
+        }
+        let finalEvent = event;
+        if (this.config.beforeSend) {
+            try {
+                finalEvent = this.config.beforeSend(event);
+                if (finalEvent === null) {
+                    this.logger.log("Event discarded by beforeSend hook:", event.type);
+                    return;
+                }
+            }
+            catch (error) {
+                this.logger.warn("beforeSend hook threw an error:", error);
+                finalEvent = event;
+            }
+        }
+        this.queue.push(finalEvent);
+    }
+    /**
+     * Check if event should be sampled based on sampleRate
+     */
+    shouldSample() {
+        const sampleRate = this.config.sampleRate;
+        if (sampleRate >= 1)
+            return true;
+        if (sampleRate <= 0)
+            return false;
+        return Math.random() < sampleRate;
+    }
+    /**
+     * Check if event should be allowed based on rate limit
+     * Uses a sliding window algorithm
+     */
+    checkRateLimit() {
+        const maxEvents = this.config.maxEventsPerSecond;
+        if (maxEvents <= 0) {
+            return true;
+        }
+        const now = Date.now();
+        const windowStart = now - 1000;
+        this.eventTimestamps = this.eventTimestamps.filter((t) => t > windowStart);
+        if (this.eventTimestamps.length >= maxEvents) {
+            if (!this.rateLimitWarned) {
+                this.logger.warn(`Rate limit exceeded (${maxEvents} events/second). Events are being dropped.`);
+                this.rateLimitWarned = true;
+                setTimeout(() => {
+                    this.rateLimitWarned = false;
+                }, 5000);
+            }
+            return false;
+        }
+        this.eventTimestamps.push(now);
+        return true;
+    }
     /**
      * Track a custom event
      */
@@ -77,6 +155,7 @@ export class AnalyticsImpl {
         }
         const trackEvent = {
             type: "track",
+            messageId: generateId(),
             event,
             properties,
             timestamp: new Date().toISOString(),
@@ -86,7 +165,7 @@ export class AnalyticsImpl {
             accountId: this.session.getAccountId(),
             context: this.getContext(),
         };
-        this.queue.push(trackEvent);
+        this.queueEvent(trackEvent);
         this.session.updateLastActivity();
     }
     /**
@@ -111,6 +190,7 @@ export class AnalyticsImpl {
         }
         const identifyEvent = {
             type: "identify",
+            messageId: generateId(),
             userId,
             traits,
             timestamp: new Date().toISOString(),
@@ -119,7 +199,7 @@ export class AnalyticsImpl {
             accountId: this.session.getAccountId(),
             context: this.getContext(),
         };
-        this.queue.push(identifyEvent);
+        this.queueEvent(identifyEvent);
         this.session.updateLastActivity();
     }
     /**
@@ -137,6 +217,7 @@ export class AnalyticsImpl {
         const referrer = typeof document !== "undefined" ? document.referrer : undefined;
         const pageEvent = {
             type: "page",
+            messageId: generateId(),
             name,
             properties,
             url,
@@ -148,7 +229,7 @@ export class AnalyticsImpl {
             accountId: this.session.getAccountId(),
             context: this.getContext(),
         };
-        this.queue.push(pageEvent);
+        this.queueEvent(pageEvent);
         this.session.updateLastActivity();
     }
     /**
@@ -173,6 +254,7 @@ export class AnalyticsImpl {
         }
         const groupEvent = {
             type: "group",
+            messageId: generateId(),
             accountId,
             traits,
             timestamp: new Date().toISOString(),
@@ -181,7 +263,7 @@ export class AnalyticsImpl {
             sessionId: this.session.getSessionId(),
             context: this.getContext(),
         };
-        this.queue.push(groupEvent);
+        this.queueEvent(groupEvent);
         this.session.updateLastActivity();
     }
     /**
@@ -225,9 +307,26 @@ export class AnalyticsImpl {
     }
     /**
      * Manually flush the event queue
+     * @returns FlushResult with success status, event count, and any errors
      */
     async flush() {
-        await this.queue.flush();
+        return this.queue.flush();
+    }
+    /**
+     * Destroy the analytics instance, cleaning up all resources.
+     * Flushes remaining events before cleanup.
+     * After calling this, the instance should not be used.
+     */
+    async destroy() {
+        this.logger.log("Destroying analytics instance...");
+        await this.queue.destroy();
+        this.session.destroy();
+        this.errorCapture?.uninstall();
+        this.initialized = false;
+        if (globalInstance === this) {
+            globalInstance = null;
+        }
+        this.logger.log("Analytics instance destroyed");
     }
     /**
      * Opt out of tracking
@@ -247,6 +346,36 @@ export class AnalyticsImpl {
     isOptedOut() {
         return this.privacy.isOptedOut();
     }
+    /**
+     * Check if a specific consent category is enabled
+     */
+    hasConsent(category) {
+        return this.privacy.hasConsent(category);
+    }
+    /**
+     * Get all currently consented categories
+     */
+    getConsentedCategories() {
+        return this.privacy.getConsentedCategories();
+    }
+    /**
+     * Set consent for specific categories
+     */
+    setConsent(categories) {
+        this.privacy.setConsent(categories);
+    }
+    /**
+     * Grant consent for a specific category
+     */
+    grantConsent(category) {
+        this.privacy.grantConsent(category);
+    }
+    /**
+     * Revoke consent for a specific category
+     */
+    revokeConsent(category) {
+        this.privacy.revokeConsent(category);
+    }
     /**
      * Get current user state
      */
@@ -323,7 +452,8 @@ export class AnalyticsImpl {
      */
     subscriptionStarted(props) {
         if (!props?.plan) {
-            this.logger.warn("subscriptionStarted: plan is required");
+            this.logger.warn("subscriptionStarted: plan is required, event not sent");
+            return;
         }
         this.track(LIFECYCLE_EVENTS.SUBSCRIPTION_STARTED, props);
     }
@@ -332,7 +462,8 @@ export class AnalyticsImpl {
      */
     subscriptionCancelled(props) {
         if (!props?.plan) {
-            this.logger.warn("subscriptionCancelled: plan is required");
+            this.logger.warn("subscriptionCancelled: plan is required, event not sent");
+            return;
         }
         this.track(LIFECYCLE_EVENTS.SUBSCRIPTION_CANCELLED, props);
     }
@@ -341,7 +472,8 @@ export class AnalyticsImpl {
      */
     subscriptionRenewed(props) {
         if (!props?.plan) {
-            this.logger.warn("subscriptionRenewed: plan is required");
+            this.logger.warn("subscriptionRenewed: plan is required, event not sent");
+            return;
         }
         this.track(LIFECYCLE_EVENTS.SUBSCRIPTION_RENEWED, props);
     }
@@ -350,7 +482,8 @@ export class AnalyticsImpl {
      */
     planUpgraded(props) {
         if (!props?.fromPlan || !props?.toPlan) {
-            this.logger.warn("planUpgraded: fromPlan and toPlan are required");
+            this.logger.warn("planUpgraded: fromPlan and toPlan are required, event not sent");
+            return;
         }
         this.track(LIFECYCLE_EVENTS.PLAN_UPGRADED, props);
     }
@@ -359,7 +492,8 @@ export class AnalyticsImpl {
      */
     planDowngraded(props) {
         if (!props?.fromPlan || !props?.toPlan) {
-            this.logger.warn("planDowngraded: fromPlan and toPlan are required");
+            this.logger.warn("planDowngraded: fromPlan and toPlan are required, event not sent");
+            return;
         }
         this.track(LIFECYCLE_EVENTS.PLAN_DOWNGRADED, props);
     }
@@ -368,7 +502,8 @@ export class AnalyticsImpl {
      */
     trialStarted(props) {
         if (!props?.plan) {
-            this.logger.warn("trialStarted: plan is required");
+            this.logger.warn("trialStarted: plan is required, event not sent");
+            return;
         }
         this.track(LIFECYCLE_EVENTS.TRIAL_STARTED, props);
     }
@@ -377,7 +512,8 @@ export class AnalyticsImpl {
      */
     trialEnded(props) {
         if (!props?.plan || props?.converted === undefined) {
-            this.logger.warn("trialEnded: plan and converted are required");
+            this.logger.warn("trialEnded: plan and converted are required, event not sent");
+            return;
         }
         this.track(LIFECYCLE_EVENTS.TRIAL_ENDED, props);
     }
@@ -398,7 +534,8 @@ export class AnalyticsImpl {
      */
     featureActivated(props) {
         if (!props?.feature) {
-            this.logger.warn("featureActivated: feature is required");
+            this.logger.warn("featureActivated: feature is required, event not sent");
+            return;
         }
         this.track(LIFECYCLE_EVENTS.FEATURE_ACTIVATED, props);
     }