@stacksee/analytics 0.11.0 → 0.11.1

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

@@ -394,6 +394,42 @@ export declare class BrowserAnalytics<TEventMap extends DefaultEventMap = Defaul
      * ```
      */
     reset(): void;
+    /**
+     * Manually flush all queued events to providers.
+     *
+     * This method is useful when you need to ensure events are sent immediately,
+     * such as before navigation or critical user actions. Providers that support
+     * batching (like ProxyProvider) will flush their queues when this is called.
+     *
+     * If `useBeacon` is true, providers that support it will use the Beacon API
+     * for more reliable delivery during page unload.
+     *
+     * @param useBeacon Whether to use the Beacon API for flushing (default: false)
+     * @returns Promise that resolves when all providers have flushed
+     *
+     * @example
+     * ```typescript
+     * // Flush before navigation
+     * analytics.track('button_clicked', { buttonId: 'checkout' });
+     * await analytics.flush();
+     * window.location.href = '/checkout';
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Flush with beacon API before page unload
+     * await analytics.flush(true);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Ensure critical events are sent immediately
+     * await analytics.track('purchase_completed', { orderId: '123' });
+     * await analytics.flush(); // Wait for confirmation
+     * showThankYouPage();
+     * ```
+     */
+    flush(useBeacon?: boolean): Promise<void>;
     /**
      * Updates the analytics context with new information.
      *

package/dist/client.d.ts

@@ -60,6 +60,10 @@ export declare function pageLeave(properties?: Record<string, unknown>): void;
  * Convenience function to reset user session
  */
 export declare function reset(): void;
+/**
+ * Convenience function to flush queued events
+ */
+export declare function flush(useBeacon?: boolean): Promise<void>;
 /**
  * Reset the analytics instance (for testing purposes)
  * @internal

package/dist/client.js

@@ -1,6 +1,6 @@
 var c = Object.defineProperty;
-var u = (t, e, i) => e in t ? c(t, e, { enumerable: !0, configurable: !0, writable: !0, value: i }) : t[e] = i;
-var s = (t, e, i) => u(t, typeof e != "symbol" ? e + "" : e, i);
+var u = (r, e, i) => e in r ? c(r, e, { enumerable: !0, configurable: !0, writable: !0, value: i }) : r[e] = i;
+var n = (r, e, i) => u(r, typeof e != "symbol" ? e + "" : e, i);
 import { i as f } from "./client-DTHZYkxx.js";
 import { P } from "./client-DTHZYkxx.js";
 import { B as k } from "./base.provider-AfFL5W_P.js";
@@ -36,13 +36,13 @@ class p {
    * ```
    */
   constructor(e) {
-    s(this, "providerConfigs", []);
-    s(this, "context", {});
-    s(this, "userId");
-    s(this, "sessionId");
-    s(this, "userTraits");
-    s(this, "initialized", !1);
-    s(this, "initializePromise");
+    n(this, "providerConfigs", []);
+    n(this, "context", {});
+    n(this, "userId");
+    n(this, "sessionId");
+    n(this, "userTraits");
+    n(this, "initialized", !1);
+    n(this, "initializePromise");
     this.providerConfigs = this.normalizeProviders(e.providers), e.defaultContext && (this.context = { ...e.defaultContext }), this.sessionId = this.generateSessionId();
   }
   /**
@@ -57,26 +57,26 @@ class p {
       "pageLeave",
       "reset"
     ];
-    return e.map((r) => {
-      if ("initialize" in r && "track" in r)
+    return e.map((t) => {
+      if ("initialize" in t && "track" in t)
         return {
-          provider: r,
+          provider: t,
           enabledMethods: new Set(i)
         };
-      const n = r;
-      n.methods && n.exclude && console.warn(
-        `[Analytics] Provider ${n.provider.name} has both 'methods' and 'exclude' specified. Using 'methods' and ignoring 'exclude'.`
+      const s = t;
+      s.methods && s.exclude && console.warn(
+        `[Analytics] Provider ${s.provider.name} has both 'methods' and 'exclude' specified. Using 'methods' and ignoring 'exclude'.`
       );
       let o;
-      return n.methods ? o = new Set(n.methods) : n.exclude ? o = new Set(
+      return s.methods ? o = new Set(s.methods) : s.exclude ? o = new Set(
         i.filter(
           (d) => {
             var h;
-            return !((h = n.exclude) != null && h.includes(d));
+            return !((h = s.exclude) != null && h.includes(d));
           }
         )
       ) : o = new Set(i), {
-        provider: n.provider,
+        provider: s.provider,
         enabledMethods: o
       };
     });
@@ -209,11 +209,11 @@ class p {
    * ```
    */
   identify(e, i) {
-    this.userId = e, this.userTraits = i, this.ensureInitialized().catch((r) => {
-      console.error("[Analytics] Failed to initialize during identify:", r);
+    this.userId = e, this.userTraits = i, this.ensureInitialized().catch((t) => {
+      console.error("[Analytics] Failed to initialize during identify:", t);
     });
-    for (const r of this.providerConfigs)
-      this.shouldCallMethod(r, "identify") && r.provider.identify(e, i);
+    for (const t of this.providerConfigs)
+      this.shouldCallMethod(t, "identify") && t.provider.identify(e, i);
   }
   /**
    * Tracks a custom event with properties.
@@ -292,14 +292,14 @@ class p {
    */
   async track(e, i) {
     await this.ensureInitialized();
-    const r = {
+    const t = {
       action: e,
       category: this.getCategoryFromEventName(e),
       properties: i,
       timestamp: Date.now(),
       userId: this.userId,
       sessionId: this.sessionId
-    }, n = {
+    }, s = {
       ...this.context,
       user: this.userId || this.userTraits ? {
         userId: this.userId,
@@ -308,7 +308,7 @@ class p {
       } : void 0
     }, o = this.providerConfigs.filter((d) => this.shouldCallMethod(d, "track")).map(async (d) => {
       try {
-        await d.provider.track(r, n);
+        await d.provider.track(t, s);
       } catch (h) {
         console.error(
           `[Analytics] Provider ${d.provider.name} failed to track event:`,
@@ -513,6 +513,55 @@ class p {
     for (const e of this.providerConfigs)
       this.shouldCallMethod(e, "reset") && e.provider.reset();
   }
+  /**
+   * Manually flush all queued events to providers.
+   *
+   * This method is useful when you need to ensure events are sent immediately,
+   * such as before navigation or critical user actions. Providers that support
+   * batching (like ProxyProvider) will flush their queues when this is called.
+   *
+   * If `useBeacon` is true, providers that support it will use the Beacon API
+   * for more reliable delivery during page unload.
+   *
+   * @param useBeacon Whether to use the Beacon API for flushing (default: false)
+   * @returns Promise that resolves when all providers have flushed
+   *
+   * @example
+   * ```typescript
+   * // Flush before navigation
+   * analytics.track('button_clicked', { buttonId: 'checkout' });
+   * await analytics.flush();
+   * window.location.href = '/checkout';
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Flush with beacon API before page unload
+   * await analytics.flush(true);
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Ensure critical events are sent immediately
+   * await analytics.track('purchase_completed', { orderId: '123' });
+   * await analytics.flush(); // Wait for confirmation
+   * showThankYouPage();
+   * ```
+   */
+  async flush(e = !1) {
+    const i = this.providerConfigs.map(async (t) => {
+      if (t.provider.flush && typeof t.provider.flush == "function")
+        try {
+          await t.provider.flush(e);
+        } catch (s) {
+          console.error(
+            `[Analytics] Provider ${t.provider.name} failed to flush:`,
+            s
+          );
+        }
+    });
+    await Promise.all(i);
+  }
   /**
    * Updates the analytics context with new information.
    *
@@ -574,14 +623,14 @@ class p {
    * ```
    */
   updateContext(e) {
-    var i, r, n;
+    var i, t, s;
     this.context = {
       ...this.context,
       ...e,
       page: e.page ? {
         path: e.page.path || ((i = this.context.page) == null ? void 0 : i.path) || window.location.pathname,
-        title: e.page.title || ((r = this.context.page) == null ? void 0 : r.title),
-        referrer: e.page.referrer || ((n = this.context.page) == null ? void 0 : n.referrer)
+        title: e.page.title || ((t = this.context.page) == null ? void 0 : t.title),
+        referrer: e.page.referrer || ((s = this.context.page) == null ? void 0 : s.referrer)
       } : this.context.page,
       device: {
         ...this.context.device,
@@ -616,13 +665,13 @@ class p {
   }
 }
 let a = null;
-function v(t) {
+function v(r) {
   if (a)
     return console.warn("[Analytics] Already initialized"), a;
   const e = {
-    providers: t.providers || [],
-    debug: t.debug,
-    enabled: t.enabled
+    providers: r.providers || [],
+    debug: r.debug,
+    enabled: r.enabled
   };
   return a = new p(e), a.initialize().catch((i) => {
     console.error("[Analytics] Failed to initialize:", i);
@@ -635,17 +684,17 @@ function l() {
     );
   return a;
 }
-function w(t, e) {
-  return l().track(t, e);
+function y(r, e) {
+  return l().track(r, e);
 }
-function y(t, e) {
-  l().identify(t, e);
+function w(r, e) {
+  l().identify(r, e);
 }
-function x(t) {
-  l().pageView(t);
+function x(r) {
+  l().pageView(r);
 }
-function z(t) {
-  l().pageLeave(t);
+function z(r) {
+  l().pageLeave(r);
 }
 function C() {
   l().reset();
@@ -657,9 +706,9 @@ export {
   v as createAnalytics,
   v as createClientAnalytics,
   l as getAnalytics,
-  y as identify,
+  w as identify,
   z as pageLeave,
   x as pageView,
   C as reset,
-  w as track
+  y as track
 };

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

@@ -67,6 +67,7 @@ export interface AnalyticsProvider {
     pageView(properties?: Record<string, unknown>, context?: EventContext): Promise<void> | void;
     pageLeave?(properties?: Record<string, unknown>, context?: EventContext): Promise<void> | void;
     reset(): Promise<void> | void;
+    flush?(useBeacon?: boolean): Promise<void> | void;
 }
 /**
  * Provider methods that can be selectively enabled/disabled through routing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stacksee/analytics",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "A highly typed, provider-agnostic analytics library for TypeScript applications",
   "type": "module",
   "exports": {