@stacksee/analytics 0.5.0 → 0.7.0

package/dist/web-CvEQewPd.js

@@ -0,0 +1,220 @@
+import { r as O, a as P, b as E } from "./axios-gULqh8dv.js";
+function j(f, p) {
+  for (var d = 0; d < p.length; d++) {
+    const o = p[d];
+    if (typeof o != "string" && !Array.isArray(o)) {
+      for (const a in o)
+        if (a !== "default" && !(a in f)) {
+          const u = Object.getOwnPropertyDescriptor(o, a);
+          u && Object.defineProperty(f, a, u.get ? u : {
+            enumerable: !0,
+            get: () => o[a]
+          });
+        }
+    }
+  }
+  return Object.freeze(Object.defineProperty(f, Symbol.toStringTag, { value: "Module" }));
+}
+var r = {}, w;
+function C() {
+  if (w) return r;
+  w = 1;
+  var f = r && r.__createBinding || (Object.create ? function(c, e, t, n) {
+    n === void 0 && (n = t);
+    var i = Object.getOwnPropertyDescriptor(e, t);
+    (!i || ("get" in i ? !e.__esModule : i.writable || i.configurable)) && (i = { enumerable: !0, get: function() {
+      return e[t];
+    } }), Object.defineProperty(c, n, i);
+  } : function(c, e, t, n) {
+    n === void 0 && (n = t), c[n] = e[t];
+  }), p = r && r.__setModuleDefault || (Object.create ? function(c, e) {
+    Object.defineProperty(c, "default", { enumerable: !0, value: e });
+  } : function(c, e) {
+    c.default = e;
+  }), d = r && r.__importStar || /* @__PURE__ */ function() {
+    var c = function(e) {
+      return c = Object.getOwnPropertyNames || function(t) {
+        var n = [];
+        for (var i in t) Object.prototype.hasOwnProperty.call(t, i) && (n[n.length] = i);
+        return n;
+      }, c(e);
+    };
+    return function(e) {
+      if (e && e.__esModule) return e;
+      var t = {};
+      if (e != null) for (var n = c(e), i = 0; i < n.length; i++) n[i] !== "default" && f(t, e, n[i]);
+      return p(t, e), t;
+    };
+  }(), o = r && r.__awaiter || function(c, e, t, n) {
+    function i(s) {
+      return s instanceof t ? s : new t(function(l) {
+        l(s);
+      });
+    }
+    return new (t || (t = Promise))(function(s, l) {
+      function g(h) {
+        try {
+          b(n.next(h));
+        } catch (v) {
+          l(v);
+        }
+      }
+      function y(h) {
+        try {
+          b(n.throw(h));
+        } catch (v) {
+          l(v);
+        }
+      }
+      function b(h) {
+        h.done ? s(h.value) : i(h.value).then(g, y);
+      }
+      b((n = n.apply(c, e || [])).next());
+    });
+  };
+  Object.defineProperty(r, "__esModule", { value: !0 }), r.Client = r.Pirsch = r.PirschWebClient = void 0;
+  const a = O(), u = P(), m = d(/* @__PURE__ */ E());
+  class _ extends a.PirschCommon {
+    /**
+     * The constructor creates a new client.
+     *
+     * @param {object} configuration You need to pass in the **Identification Code** you have configured on the Pirsch dashboard.
+     * It's also recommended to set the proper protocol for your website, else it will be set to `https` by default.
+     * All other configuration parameters can be left to their defaults.
+     * @param {string} configuration.baseUrl The base URL for the pirsch API
+     * @param {number} configuration.timeout The default HTTP timeout in milliseconds
+     * @param {string} configuration.identificationCode The identification code
+     * @param {string} configuration.hostname The hostname to rewrite the URL. Usually only required for testing
+     *
+     */
+    constructor(e) {
+      if (super(), "clientId" in e || "clientSecret" in e)
+        throw new Error("Do not pass OAuth secrets such as 'clientId' or 'clientSecret' to the web client!");
+      if ("accessToken" in e)
+        throw new Error("Do not pass secrets such as 'accessToken' to the web client!");
+      const { baseUrl: t = u.PIRSCH_DEFAULT_BASE_URL, timeout: n = u.PIRSCH_DEFAULT_TIMEOUT, identificationCode: i, hostname: s } = e;
+      this.assertIdentificationCodeCredentials({ identificationCode: i }), this.baseUrl = t, this.timeout = n, this.identificationCode = i, this.hostname = s, this.httpClient = m.default.create({ baseURL: this.baseUrl, timeout: this.timeout });
+    }
+    /**
+     * hit sends a hit to Pirsch.
+     *
+     * @param hit optional override data for the request.
+     */
+    hit(e) {
+      return o(this, void 0, void 0, function* () {
+        const t = Object.assign(Object.assign({}, this.hitFromBrowser()), e), n = this.browserHitToGetParameters(t);
+        yield this.get(u.PirschEndpoint.HIT, { parameters: n });
+      });
+    }
+    /**
+     * event sends an event to Pirsch.
+     *
+     * @param name the name for the event
+     * @param duration optional duration for the event
+     * @param meta optional object containing metadata (only scalar values, like strings, numbers, and booleans)
+     * @param hit optional override data for the request
+     */
+    event(e) {
+      return o(this, arguments, void 0, function* (t, n = 0, i, s) {
+        const l = Object.assign(Object.assign({}, this.hitFromBrowser()), s);
+        return this.beacon(u.PirschEndpoint.EVENT, Object.assign({ identification_code: this.identificationCode, event_name: t, event_duration: n, event_meta: this.prepareScalarObject(i) }, l)), Promise.resolve();
+      });
+    }
+    /**
+     * customHit sends a hit to Pirsch.
+     *
+     * @param hit data for the request.
+     */
+    customHit(e) {
+      return o(this, void 0, void 0, function* () {
+        const t = this.browserHitToGetParameters(e);
+        yield this.get(u.PirschEndpoint.HIT, { parameters: t });
+      });
+    }
+    /**
+     * customEvent sends an event to Pirsch.
+     *
+     * @param name the name for the event
+     * @param duration optional duration for the event
+     * @param hit data for the request
+     * @param meta optional object containing metadata (only scalar values, like strings, numbers, and booleans)
+     */
+    customEvent(e) {
+      return o(this, arguments, void 0, function* (t, n = 0, i, s) {
+        return this.beacon(u.PirschEndpoint.EVENT, Object.assign({ identification_code: this.identificationCode, event_name: t, event_duration: n, event_meta: this.prepareScalarObject(s) }, i)), Promise.resolve();
+      });
+    }
+    /**
+     * hitFromBrowser returns the required data to send a hit to Pirsch.
+     *
+     * @returns Hit object containing all necessary fields.
+     */
+    hitFromBrowser() {
+      return {
+        url: this.generateUrl(),
+        title: document.title,
+        referrer: document.referrer,
+        screen_width: screen.width,
+        screen_height: screen.height
+      };
+    }
+    browserHitToGetParameters(e) {
+      const t = {
+        nc: Date.now(),
+        code: this.identificationCode,
+        url: e.url
+      };
+      if (e.title && (t.t = e.title), e.referrer && (t.ref = e.referrer), e.screen_width && (t.w = e.screen_width), e.screen_height && (t.h = e.screen_height), e.tags)
+        for (const [n, i] of Object.entries(e.tags))
+          t[`tag_${n.replaceAll("-", " ")}`] = i || 1;
+      return t;
+    }
+    generateUrl() {
+      return (this.hostname ? location.href.replace(location.hostname, this.hostname) : location.href).slice(0, u.PIRSCH_URL_LENGTH_LIMIT);
+    }
+    get(e, t) {
+      return o(this, void 0, void 0, function* () {
+        try {
+          return (yield this.httpClient.get(e, this.createOptions(Object.assign({}, t)))).data;
+        } catch (n) {
+          throw yield this.toApiError(n);
+        }
+      });
+    }
+    post(e, t, n) {
+      return o(this, void 0, void 0, function* () {
+        try {
+          return (yield this.httpClient.post(e, t, this.createOptions(n ?? {}))).data;
+        } catch (i) {
+          throw yield this.toApiError(i);
+        }
+      });
+    }
+    beacon(e, t) {
+      return o(this, void 0, void 0, function* () {
+        if (!navigator.sendBeacon([this.baseUrl, e].join("/"), JSON.stringify(t)))
+          throw yield this.toApiError("sendBeacon failed");
+      });
+    }
+    toApiError(e) {
+      return o(this, void 0, void 0, function* () {
+        var t, n, i, s, l;
+        return e instanceof a.PirschApiError ? e : e instanceof m.AxiosError ? new a.PirschApiError((n = (t = e.response) === null || t === void 0 ? void 0 : t.status) !== null && n !== void 0 ? n : 400, (i = e.response) === null || i === void 0 ? void 0 : i.data) : typeof e == "object" && e !== null && "response" in e && typeof e.response == "object" && e.response !== null && "status" in e.response && "data" in e.response ? new a.PirschApiError((s = e.response.status) !== null && s !== void 0 ? s : 400, (l = e.response) === null || l === void 0 ? void 0 : l.data) : e instanceof Error ? new a.PirschUnknownApiError(e.message) : typeof e == "object" && e !== null && "message" in e && typeof e.message == "string" ? new a.PirschUnknownApiError(e.message) : new a.PirschUnknownApiError(JSON.stringify(e));
+      });
+    }
+    createOptions({ headers: e, parameters: t }) {
+      return {
+        headers: e,
+        params: t
+      };
+    }
+  }
+  return r.PirschWebClient = _, r.Pirsch = _, r.Client = _, r;
+}
+var A = C();
+const U = /* @__PURE__ */ j({
+  __proto__: null
+}, [A]);
+export {
+  U as w
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stacksee/analytics",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "A highly typed, provider-agnostic analytics library for TypeScript applications",
   "type": "module",
   "exports": {
@@ -61,6 +61,8 @@
     "vitest": "^2.0.3"
   },
   "optionalDependencies": {
+    "@bentonow/bento-node-sdk": "^0.2.1",
+    "pirsch-sdk": "^2.9.1",
     "posthog-js": "^1.268.2",
     "posthog-node": "^5.9.0"
   },

package/readme.md

@@ -5,6 +5,7 @@ A highly typed, zero-dependency, provider-agnostic analytics library for TypeScr
 ## Table of Contents
 
 - [Features](#features)
+- [Providers](#providers)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
   - [1. Define Your Events](#1-define-your-events)
@@ -44,6 +45,35 @@ A highly typed, zero-dependency, provider-agnostic analytics library for TypeScr
 - 🌎 **Edge ready**: The server client is compatible with edge runtime (e.g. Cloudflare Workers, Vercel Edge functions)
 - 🔧 **Extensible**: Simple interface to add new providers
 
+## Providers
+
+The library includes built-in support for popular analytics services, with more coming soon:
+
+### Official Providers
+
+| Provider | Type | Documentation |
+|----------|------|---------------|
+| **PostHog** | Product Analytics | [docs/providers/posthog.md](./docs/providers/posthog.md) |
+| **Bento** | Email Marketing & Events | [docs/providers/bento.md](./docs/providers/bento.md) |
+| **Pirsch** | Privacy-Focused Web Analytics | [docs/providers/pirsch.md](./docs/providers/pirsch.md) |
+
+### Community & Custom Providers
+
+Want to use a different analytics service? Check out our guide:
+
+**[Creating Custom Providers →](./docs/providers/custom-providers.md)**
+
+You can easily create providers for:
+- Google Analytics
+- Mixpanel
+- Amplitude
+- Segment
+- Customer.io
+- Loops
+- Any analytics service with a JavaScript SDK
+
+**[View all provider documentation →](./docs/providers/)**
+
 ## Installation
 
 ```bash
@@ -51,8 +81,16 @@ pnpm install @stacksee/analytics
 
 # For PostHog support
 pnpm install posthog-js posthog-node
+
+# For Bento support (server-side only)
+pnpm install @bentonow/bento-node-sdk
+
+# For Pirsch support
+pnpm install pirsch-sdk
 ```
 
+> **See also:** [Provider Documentation](./docs/providers/) for detailed setup guides for each provider.
+
 ## Quick Start
 
 ### 1. Define Your Events
@@ -705,32 +743,21 @@ export const appEvents = {
 
 ### Adding Custom Providers
 
-Implement the `AnalyticsProvider` interface to add support for other analytics services:
+Want to integrate with a different analytics service? See our comprehensive guide:
+
+**[Creating Custom Providers →](./docs/providers/custom-providers.md)**
+
+Quick example:
 
 ```typescript
 import { BaseAnalyticsProvider, BaseEvent, EventContext } from '@stacksee/analytics';
 
 export class GoogleAnalyticsProvider extends BaseAnalyticsProvider {
   name = 'GoogleAnalytics';
-  private measurementId: string;
-
-  constructor(config: { measurementId: string; debug?: boolean; enabled?: boolean }) {
-    super({ debug: config.debug, enabled: config.enabled });
-    this.measurementId = config.measurementId;
-  }
-
-  async initialize(): Promise<void> {
-    // Initialize GA
-  }
-
-  track(event: BaseEvent, context?: EventContext): void {
-    // Send event to GA
-  }
-
-  identify(userId: string, traits?: Record<string, unknown>): void {
-    // Set user properties in GA
-  }
 
+  async initialize(): Promise<void> { /* Initialize GA */ }
+  track(event: BaseEvent, context?: EventContext): void { /* Track event */ }
+  identify(userId: string, traits?: Record<string, unknown>): void { /* Identify user */ }
   // ... implement other required methods
 }
 ```
@@ -738,9 +765,9 @@ export class GoogleAnalyticsProvider extends BaseAnalyticsProvider {
 Then use it as a plugin in your configuration:
 
 ```typescript
-const analytics = await createClientAnalytics<typeof AppEvents>({
+const analytics = createClientAnalytics<typeof AppEvents>({
   providers: [
-    new PostHogClientProvider({ apiKey: 'xxx' }),
+    new PostHogClientProvider({ token: 'xxx' }),
     new GoogleAnalyticsProvider({ measurementId: 'xxx' })
   ]
 });