@14four/analytics 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,73 @@
+/** Options for server-side (API key) mode. */
+type ServerOptions = {
+    /** Server-side ingest API key (format: sk_live_…). */
+    apiKey: string;
+    /** Base URL of the ingest API, e.g. "https://api.example.com". Defaults to "" (same-origin). */
+    baseUrl?: string;
+};
+/** Options for browser (public tracking) mode. */
+type BrowserOptions = {
+    /** Public application ID. */
+    appId: string;
+    /** Base URL of the ingest API, e.g. "https://api.example.com". Defaults to "" (same-origin). */
+    baseUrl?: string;
+};
+type AnalyticsOptions = ServerOptions | BrowserOptions;
+/**
+ * Payload for server-side event tracking.
+ * `user_id` is required and used directly as the visitor identifier (no hashing).
+ * Any additional top-level fields become individual Parquet columns.
+ */
+type ServerTrackOptions = {
+    user_id: string;
+    url?: string;
+    app_id?: string;
+    [key: string]: unknown;
+};
+/**
+ * Payload for browser (public) event tracking.
+ * `url`, `referrer`, `screen_width`, and `language` are auto-collected from the
+ * browser environment when omitted. UTM params are parsed from the current URL.
+ */
+type WebTrackOptions = {
+    url?: string;
+    referrer?: string;
+    screen_width?: number;
+    language?: string;
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+    /** Custom properties. Max 20 keys; keys ≤50 chars; values ≤500 chars. */
+    props?: Record<string, string>;
+};
+declare class AnalyticsError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+declare class Analytics {
+    private readonly baseUrl;
+    private readonly mode;
+    private readonly apiKey?;
+    private readonly appId?;
+    constructor(options: AnalyticsOptions);
+    /**
+     * Track an event.
+     *
+     * **Server mode** — requires `{ user_id }`. Any extra fields become Parquet columns.
+     * ```ts
+     * await analytics.track('signup', { user_id: 'u_123', plan: 'pro' })
+     * ```
+     *
+     * **Browser mode** — auto-collects url/referrer/screen/language/utm from the browser.
+     * ```ts
+     * analytics.track('page_view').catch(() => {})
+     * analytics.track('cta_click', { props: { button: 'hero' } })
+     * ```
+     */
+    track(eventName: string, options?: ServerTrackOptions | WebTrackOptions): Promise<void>;
+    private _post;
+}
+
+export { Analytics, AnalyticsError, type AnalyticsOptions, type BrowserOptions, type ServerOptions, type ServerTrackOptions, type WebTrackOptions, Analytics as default };

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+/** Options for server-side (API key) mode. */
+type ServerOptions = {
+    /** Server-side ingest API key (format: sk_live_…). */
+    apiKey: string;
+    /** Base URL of the ingest API, e.g. "https://api.example.com". Defaults to "" (same-origin). */
+    baseUrl?: string;
+};
+/** Options for browser (public tracking) mode. */
+type BrowserOptions = {
+    /** Public application ID. */
+    appId: string;
+    /** Base URL of the ingest API, e.g. "https://api.example.com". Defaults to "" (same-origin). */
+    baseUrl?: string;
+};
+type AnalyticsOptions = ServerOptions | BrowserOptions;
+/**
+ * Payload for server-side event tracking.
+ * `user_id` is required and used directly as the visitor identifier (no hashing).
+ * Any additional top-level fields become individual Parquet columns.
+ */
+type ServerTrackOptions = {
+    user_id: string;
+    url?: string;
+    app_id?: string;
+    [key: string]: unknown;
+};
+/**
+ * Payload for browser (public) event tracking.
+ * `url`, `referrer`, `screen_width`, and `language` are auto-collected from the
+ * browser environment when omitted. UTM params are parsed from the current URL.
+ */
+type WebTrackOptions = {
+    url?: string;
+    referrer?: string;
+    screen_width?: number;
+    language?: string;
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+    /** Custom properties. Max 20 keys; keys ≤50 chars; values ≤500 chars. */
+    props?: Record<string, string>;
+};
+declare class AnalyticsError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+declare class Analytics {
+    private readonly baseUrl;
+    private readonly mode;
+    private readonly apiKey?;
+    private readonly appId?;
+    constructor(options: AnalyticsOptions);
+    /**
+     * Track an event.
+     *
+     * **Server mode** — requires `{ user_id }`. Any extra fields become Parquet columns.
+     * ```ts
+     * await analytics.track('signup', { user_id: 'u_123', plan: 'pro' })
+     * ```
+     *
+     * **Browser mode** — auto-collects url/referrer/screen/language/utm from the browser.
+     * ```ts
+     * analytics.track('page_view').catch(() => {})
+     * analytics.track('cta_click', { props: { button: 'hero' } })
+     * ```
+     */
+    track(eventName: string, options?: ServerTrackOptions | WebTrackOptions): Promise<void>;
+    private _post;
+}
+
+export { Analytics, AnalyticsError, type AnalyticsOptions, type BrowserOptions, type ServerOptions, type ServerTrackOptions, type WebTrackOptions, Analytics as default };

package/dist/index.js

@@ -0,0 +1,146 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Analytics: () => Analytics,
+  AnalyticsError: () => AnalyticsError,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var AnalyticsError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "AnalyticsError";
+  }
+};
+function isBrowser() {
+  return typeof window !== "undefined" && typeof document !== "undefined";
+}
+function isServerOptions(opts) {
+  return "apiKey" in opts;
+}
+function extractUtm(search) {
+  const p = new URLSearchParams(search);
+  const result = {};
+  const keys = [
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+    "utm_term",
+    "utm_content"
+  ];
+  for (const key of keys) {
+    const val = p.get(key);
+    if (val) result[key] = val;
+  }
+  return result;
+}
+var Analytics = class {
+  constructor(options) {
+    this.baseUrl = options.baseUrl?.replace(/\/$/, "") ?? "";
+    if (isServerOptions(options)) {
+      this.mode = "server";
+      this.apiKey = options.apiKey;
+    } else {
+      this.mode = "browser";
+      this.appId = options.appId;
+    }
+  }
+  /**
+   * Track an event.
+   *
+   * **Server mode** — requires `{ user_id }`. Any extra fields become Parquet columns.
+   * ```ts
+   * await analytics.track('signup', { user_id: 'u_123', plan: 'pro' })
+   * ```
+   *
+   * **Browser mode** — auto-collects url/referrer/screen/language/utm from the browser.
+   * ```ts
+   * analytics.track('page_view').catch(() => {})
+   * analytics.track('cta_click', { props: { button: 'hero' } })
+   * ```
+   */
+  async track(eventName, options) {
+    const endpoint = `${this.baseUrl}/api/ingest/event`;
+    if (this.mode === "server") {
+      const { user_id, url, app_id, ...customProps } = options ?? {};
+      const body = {
+        event_name: eventName,
+        user_id,
+        ...customProps
+      };
+      if (url !== void 0) body.url = url;
+      if (app_id !== void 0) body.app_id = app_id;
+      await this._post(endpoint, body, {
+        Authorization: `Bearer ${this.apiKey}`
+      });
+    } else {
+      const opts = options ?? {};
+      const autoUrl = isBrowser() ? window.location.href : void 0;
+      const autoReferrer = isBrowser() ? document.referrer : void 0;
+      const autoScreenWidth = isBrowser() ? window.screen.width : void 0;
+      const autoLanguage = isBrowser() ? navigator.language : void 0;
+      const autoUtm = isBrowser() ? extractUtm(window.location.search) : {};
+      const body = {
+        app_id: this.appId,
+        event_name: eventName,
+        url: opts.url ?? autoUrl,
+        ...opts.referrer !== void 0 ? { referrer: opts.referrer } : autoReferrer ? { referrer: autoReferrer } : {},
+        ...opts.screen_width !== void 0 ? { screen_width: opts.screen_width } : autoScreenWidth !== void 0 ? { screen_width: autoScreenWidth } : {},
+        ...opts.language !== void 0 ? { language: opts.language } : autoLanguage ? { language: autoLanguage } : {},
+        ...autoUtm,
+        ...opts.utm_source !== void 0 && { utm_source: opts.utm_source },
+        ...opts.utm_medium !== void 0 && { utm_medium: opts.utm_medium },
+        ...opts.utm_campaign !== void 0 && { utm_campaign: opts.utm_campaign },
+        ...opts.utm_term !== void 0 && { utm_term: opts.utm_term },
+        ...opts.utm_content !== void 0 && { utm_content: opts.utm_content },
+        ...opts.props !== void 0 && { props: opts.props }
+      };
+      await this._post(endpoint, body, {});
+    }
+  }
+  async _post(url, body, headers) {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...headers
+      },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      let message = res.statusText;
+      try {
+        const data = await res.json();
+        message = data.error ?? data.message ?? message;
+      } catch {
+      }
+      throw new AnalyticsError(res.status, message);
+    }
+  }
+};
+var index_default = Analytics;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Analytics,
+  AnalyticsError
+});

package/dist/index.mjs

@@ -0,0 +1,120 @@
+// src/index.ts
+var AnalyticsError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "AnalyticsError";
+  }
+};
+function isBrowser() {
+  return typeof window !== "undefined" && typeof document !== "undefined";
+}
+function isServerOptions(opts) {
+  return "apiKey" in opts;
+}
+function extractUtm(search) {
+  const p = new URLSearchParams(search);
+  const result = {};
+  const keys = [
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+    "utm_term",
+    "utm_content"
+  ];
+  for (const key of keys) {
+    const val = p.get(key);
+    if (val) result[key] = val;
+  }
+  return result;
+}
+var Analytics = class {
+  constructor(options) {
+    this.baseUrl = options.baseUrl?.replace(/\/$/, "") ?? "";
+    if (isServerOptions(options)) {
+      this.mode = "server";
+      this.apiKey = options.apiKey;
+    } else {
+      this.mode = "browser";
+      this.appId = options.appId;
+    }
+  }
+  /**
+   * Track an event.
+   *
+   * **Server mode** — requires `{ user_id }`. Any extra fields become Parquet columns.
+   * ```ts
+   * await analytics.track('signup', { user_id: 'u_123', plan: 'pro' })
+   * ```
+   *
+   * **Browser mode** — auto-collects url/referrer/screen/language/utm from the browser.
+   * ```ts
+   * analytics.track('page_view').catch(() => {})
+   * analytics.track('cta_click', { props: { button: 'hero' } })
+   * ```
+   */
+  async track(eventName, options) {
+    const endpoint = `${this.baseUrl}/api/ingest/event`;
+    if (this.mode === "server") {
+      const { user_id, url, app_id, ...customProps } = options ?? {};
+      const body = {
+        event_name: eventName,
+        user_id,
+        ...customProps
+      };
+      if (url !== void 0) body.url = url;
+      if (app_id !== void 0) body.app_id = app_id;
+      await this._post(endpoint, body, {
+        Authorization: `Bearer ${this.apiKey}`
+      });
+    } else {
+      const opts = options ?? {};
+      const autoUrl = isBrowser() ? window.location.href : void 0;
+      const autoReferrer = isBrowser() ? document.referrer : void 0;
+      const autoScreenWidth = isBrowser() ? window.screen.width : void 0;
+      const autoLanguage = isBrowser() ? navigator.language : void 0;
+      const autoUtm = isBrowser() ? extractUtm(window.location.search) : {};
+      const body = {
+        app_id: this.appId,
+        event_name: eventName,
+        url: opts.url ?? autoUrl,
+        ...opts.referrer !== void 0 ? { referrer: opts.referrer } : autoReferrer ? { referrer: autoReferrer } : {},
+        ...opts.screen_width !== void 0 ? { screen_width: opts.screen_width } : autoScreenWidth !== void 0 ? { screen_width: autoScreenWidth } : {},
+        ...opts.language !== void 0 ? { language: opts.language } : autoLanguage ? { language: autoLanguage } : {},
+        ...autoUtm,
+        ...opts.utm_source !== void 0 && { utm_source: opts.utm_source },
+        ...opts.utm_medium !== void 0 && { utm_medium: opts.utm_medium },
+        ...opts.utm_campaign !== void 0 && { utm_campaign: opts.utm_campaign },
+        ...opts.utm_term !== void 0 && { utm_term: opts.utm_term },
+        ...opts.utm_content !== void 0 && { utm_content: opts.utm_content },
+        ...opts.props !== void 0 && { props: opts.props }
+      };
+      await this._post(endpoint, body, {});
+    }
+  }
+  async _post(url, body, headers) {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...headers
+      },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      let message = res.statusText;
+      try {
+        const data = await res.json();
+        message = data.error ?? data.message ?? message;
+      } catch {
+      }
+      throw new AnalyticsError(res.status, message);
+    }
+  }
+};
+var index_default = Analytics;
+export {
+  Analytics,
+  AnalyticsError,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@14four/analytics",
+  "version": "0.1.1",
+  "description": "14four Analytics SDK — works in Node.js and browser",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepare": "tsup",
+    "release": "npm run build && npm publish --access public"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}