@hellyeah/x-ray 0.1.0-beta.5

package/dist/server/index.cjs

@@ -0,0 +1,519 @@
+var import_node_module = require("node:module");
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toCommonJS = (from) => {
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
+  __moduleCache.set(from, entry);
+  return entry;
+};
+var __moduleCache;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/server/index.ts
+var exports_server = {};
+__export(exports_server, {
+  cv: () => cv,
+  createXRay: () => createXRay,
+  XRay: () => XRay
+});
+module.exports = __toCommonJS(exports_server);
+
+// src/constants.ts
+var cv = {
+  purchase: "cv_purchase",
+  subscribe: "cv_subscribe",
+  startTrial: "cv_start_trial",
+  leadSubmit: "cv_lead_submit",
+  registrationComplete: "cv_registration_complete",
+  bookAppointment: "cv_book_appointment",
+  contact: "cv_contact",
+  submitApplication: "cv_submit_application",
+  addToCart: "cv_add_to_cart",
+  beginCheckout: "cv_begin_checkout",
+  addPaymentInfo: "cv_add_payment_info",
+  viewContent: "cv_view_content",
+  search: "cv_search"
+};
+// src/server/types.ts
+var isUnrefable = (value) => typeof value === "object" && value !== null && ("unref" in value);
+
+// src/server/index.ts
+var DEFAULTS = {
+  flushAt: 20,
+  flushInterval: 1e4,
+  maxQueueSize: 1000,
+  requestTimeout: 1e4,
+  retryDelay: 3000
+};
+var PROPERTY_LIMITS = {
+  maxProperties: 20,
+  maxKeyLength: 100,
+  maxStringValueLength: 500
+};
+var FLAT_TYPES = new Set(["string", "number", "boolean"]);
+var RETRY_ATTEMPTS = 3;
+var REVENUE_WARNING_THRESHOLD = 1e4;
+var CURRENCY_PATTERN = /^[A-Z]{3}$/;
+var TRAILING_SLASH = /\/$/;
+var SERVERLESS_ENV_KEYS = [
+  "VERCEL",
+  "AWS_LAMBDA_FUNCTION_NAME",
+  "NETLIFY",
+  "CLOUDFLARE_WORKER"
+];
+var DATA_KEYS = ["currency", "tag", "url", "hostname"];
+var ATTRIBUTION_KEYS = [
+  "utm_source",
+  "utm_medium",
+  "utm_campaign",
+  "utm_content",
+  "utm_term",
+  "gclid",
+  "fbclid",
+  "msclkid",
+  "ttclid",
+  "li_fat_id",
+  "twclid"
+];
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var WELL_KNOWN_CONTEXT_SYMBOLS = [
+  Symbol.for("@vercel/request-context"),
+  Symbol.for("@next/request-context")
+];
+var discoverWaitUntil = () => {
+  const g = globalThis;
+  for (const sym of WELL_KNOWN_CONTEXT_SYMBOLS) {
+    const waitUntil = g[sym]?.get?.()?.waitUntil;
+    if (waitUntil)
+      return waitUntil;
+  }
+  return null;
+};
+
+class XRay {
+  queue = [];
+  timer = null;
+  defaultDistinctId;
+  logFn;
+  flushing = false;
+  fetchFn;
+  shutdownCalled = false;
+  cfg;
+  constructor(websiteId, options) {
+    const resolvedWebsiteId = websiteId ?? process.env.XRAY_WEBSITE_ID ?? "";
+    const resolvedHost = options?.host ?? process.env.XRAY_HOST ?? "https://xray-staging.hellyeahai.com";
+    if (!resolvedWebsiteId) {
+      console.warn("[x-ray] websiteId is missing. Pass it to the constructor or set XRAY_WEBSITE_ID env var.");
+    }
+    this.cfg = {
+      websiteId: resolvedWebsiteId,
+      host: resolvedHost.replace(TRAILING_SLASH, ""),
+      flushAt: options?.flushAt ?? DEFAULTS.flushAt,
+      flushInterval: options?.flushInterval ?? DEFAULTS.flushInterval,
+      maxQueueSize: options?.maxQueueSize ?? DEFAULTS.maxQueueSize,
+      requestTimeout: options?.requestTimeout ?? DEFAULTS.requestTimeout,
+      disabled: options?.disabled ?? false,
+      retryDelay: options?.retryDelay ?? DEFAULTS.retryDelay,
+      context: options?.context ?? {},
+      waitUntil: options?.waitUntil ?? null
+    };
+    this.fetchFn = options?.fetch ?? globalThis.fetch;
+    this.logFn = options?.logger ?? null;
+    if (!this.cfg.disabled) {
+      this.timer = setInterval(() => {
+        const p = this.flush().catch(() => {});
+        const wU = this.resolveWaitUntil();
+        if (wU)
+          wU(p);
+      }, this.cfg.flushInterval);
+      if (isUnrefable(this.timer)) {
+        this.timer.unref();
+      }
+      if (!(this.cfg.waitUntil || discoverWaitUntil())) {
+        const isServerless = SERVERLESS_ENV_KEYS.some((k) => typeof process !== "undefined" && (k in process.env));
+        if (isServerless) {
+          this.log({
+            action: "serverless_detect",
+            outcome: "warning",
+            message: "Serverless environment detected without waitUntil — batched track() events may be lost. Pass waitUntil in options or use trackImmediate()."
+          });
+        }
+      }
+    }
+  }
+  track(event, data) {
+    try {
+      if (this.cfg.disabled) {
+        return;
+      }
+      const distinctId = data?.distinctId ?? this.defaultDistinctId;
+      if (!(event && distinctId)) {
+        this.log({
+          action: "track",
+          outcome: "drop",
+          message: "missing event name or distinctId",
+          event: event || undefined
+        });
+        return;
+      }
+      const item = this.buildItem(event, distinctId, data);
+      this.enqueue(item);
+      this.log({
+        action: "track",
+        outcome: "success",
+        message: "queued",
+        event
+      });
+    } catch (err) {
+      this.log({
+        action: "track",
+        outcome: "error",
+        message: "track error",
+        error: err
+      });
+    }
+  }
+  async trackImmediate(event, data) {
+    try {
+      if (this.cfg.disabled) {
+        return;
+      }
+      const distinctId = data?.distinctId ?? this.defaultDistinctId;
+      if (!(event && distinctId)) {
+        this.log({
+          action: "track_immediate",
+          outcome: "drop",
+          message: "missing event name or distinctId",
+          event: event || undefined
+        });
+        return;
+      }
+      const item = this.buildItem(event, distinctId, data);
+      await this.sendBatch([item]);
+      this.log({
+        action: "track_immediate",
+        outcome: "success",
+        message: "sent immediate",
+        event
+      });
+    } catch (err) {
+      this.log({
+        action: "track_immediate",
+        outcome: "error",
+        message: "trackImmediate error",
+        error: err
+      });
+    }
+  }
+  identify(params) {
+    try {
+      this.defaultDistinctId = params.distinctId;
+      this.log({
+        action: "identify",
+        outcome: "success",
+        message: "identified"
+      });
+    } catch (err) {
+      this.log({
+        action: "identify",
+        outcome: "error",
+        message: "identify error",
+        error: err
+      });
+    }
+  }
+  async flush() {
+    try {
+      if (this.cfg.disabled)
+        return;
+      if (this.flushing || this.queue.length === 0)
+        return;
+      this.flushing = true;
+      while (this.queue.length > 0) {
+        const items = this.queue.splice(0, this.cfg.flushAt);
+        try {
+          await this.sendBatch(items);
+          this.log({
+            action: "flush",
+            outcome: "success",
+            message: "flushed",
+            count: items.length
+          });
+        } catch (err) {
+          this.queue.unshift(...items);
+          this.log({
+            action: "flush",
+            outcome: "error",
+            message: "re-queued events after send failure",
+            count: items.length,
+            error: err
+          });
+          break;
+        }
+      }
+      this.flushing = false;
+    } catch (err) {
+      this.flushing = false;
+      this.log({
+        action: "flush",
+        outcome: "error",
+        message: "flush error",
+        error: err
+      });
+    }
+  }
+  async shutdown(timeoutMs = 5000) {
+    try {
+      if (this.shutdownCalled) {
+        return;
+      }
+      this.shutdownCalled = true;
+      if (this.timer) {
+        clearInterval(this.timer);
+        this.timer = null;
+      }
+      await Promise.race([this.flush(), sleep(timeoutMs)]);
+      this.log({
+        action: "shutdown",
+        outcome: "success",
+        message: "shutdown complete"
+      });
+    } catch (err) {
+      this.log({
+        action: "shutdown",
+        outcome: "error",
+        message: "shutdown error",
+        error: err
+      });
+    }
+  }
+  debug(enabled) {
+    if (enabled) {
+      this.logFn = (entry) => console.log("[x-ray]", JSON.stringify(entry));
+    } else {
+      this.logFn = null;
+    }
+  }
+  enqueue(item) {
+    if (this.queue.length >= this.cfg.maxQueueSize) {
+      this.queue.shift();
+      this.log({
+        action: "enqueue",
+        outcome: "overflow",
+        message: "queue full, dropped oldest event",
+        count: this.queue.length
+      });
+    }
+    this.queue.push(item);
+    if (this.queue.length >= this.cfg.flushAt) {
+      const trigger = () => {
+        const p = this.flush().catch(() => {});
+        const wU = this.resolveWaitUntil();
+        if (wU)
+          wU(p);
+      };
+      queueMicrotask(trigger);
+    }
+  }
+  async sendBatch(items) {
+    const payload = items.map((item) => ({
+      type: "event",
+      payload: item
+    }));
+    for (let attempt = 0;attempt < RETRY_ATTEMPTS; attempt++) {
+      const controller = new AbortController;
+      const timeout = setTimeout(() => controller.abort(), this.cfg.requestTimeout);
+      if (isUnrefable(timeout))
+        timeout.unref();
+      try {
+        const res = await this.fetchFn(`${this.cfg.host}/api/batch`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "X-HY-Source": "server-sdk"
+          },
+          body: JSON.stringify(payload),
+          signal: controller.signal
+        });
+        clearTimeout(timeout);
+        if (res.ok) {
+          return;
+        }
+        if (res.status >= 500) {
+          this.log({
+            action: "send_batch",
+            outcome: "retry",
+            message: "server error, retrying",
+            statusCode: res.status,
+            attempt: attempt + 1,
+            maxAttempts: RETRY_ATTEMPTS
+          });
+          if (attempt < RETRY_ATTEMPTS - 1) {
+            await sleep(this.cfg.retryDelay);
+            continue;
+          }
+          this.log({
+            action: "send_batch",
+            outcome: "drop",
+            message: "dropping batch after retries exhausted",
+            statusCode: res.status,
+            attempt: attempt + 1,
+            maxAttempts: RETRY_ATTEMPTS
+          });
+          return;
+        }
+        this.log({
+          action: "send_batch",
+          outcome: "drop",
+          message: "client error, dropping batch",
+          statusCode: res.status
+        });
+        return;
+      } catch (err) {
+        clearTimeout(timeout);
+        if (attempt < RETRY_ATTEMPTS - 1 && !controller.signal.aborted) {
+          this.log({
+            action: "send_batch",
+            outcome: "retry",
+            message: "network error, retrying",
+            attempt: attempt + 1,
+            maxAttempts: RETRY_ATTEMPTS,
+            error: err
+          });
+          await sleep(this.cfg.retryDelay);
+          continue;
+        }
+        this.log({
+          action: "send_batch",
+          outcome: "drop",
+          message: "dropping batch",
+          error: err
+        });
+        return;
+      }
+    }
+  }
+  buildItem(event, distinctId, data) {
+    const item = {
+      website: this.cfg.websiteId,
+      name: event,
+      id: distinctId,
+      hy_event_id: crypto.randomUUID()
+    };
+    if (data) {
+      if (data.revenue !== undefined) {
+        item.revenue = String(data.revenue);
+        if (data.revenue > REVENUE_WARNING_THRESHOLD) {
+          this.log({
+            action: "track",
+            outcome: "warning",
+            message: `Revenue value ${data.revenue} looks unusually high — X-Ray expects dollars (e.g., 49.99), not cents. Divide by 100 if your payment provider returns cents.`,
+            event
+          });
+        }
+      }
+      if (data.currency !== undefined && !CURRENCY_PATTERN.test(data.currency)) {
+        this.log({
+          action: "track",
+          outcome: "warning",
+          message: `Currency "${data.currency}" does not match ISO 4217 format (expected 3 uppercase letters, e.g., "USD").`,
+          event
+        });
+      }
+      for (const key of DATA_KEYS) {
+        if (data[key] !== undefined)
+          item[key] = data[key];
+      }
+      if (data.metadata) {
+        const { data: sanitized, warnings } = this.sanitizeProperties(data.metadata);
+        if (sanitized)
+          item.data = sanitized;
+        for (const w of warnings) {
+          this.log({ action: "track", outcome: "drop", message: w, event });
+        }
+      }
+    }
+    for (const key of ATTRIBUTION_KEYS) {
+      const value = this.cfg.context[key];
+      if (value !== undefined)
+        item[key] = value;
+    }
+    return item;
+  }
+  sanitizeProperties(properties) {
+    const warnings = [];
+    const result = {};
+    let count = 0;
+    for (const [rawKey, rawValue] of Object.entries(properties)) {
+      if (count >= PROPERTY_LIMITS.maxProperties) {
+        warnings.push(`Exceeded ${PROPERTY_LIMITS.maxProperties} properties, remaining dropped`);
+        break;
+      }
+      const needsTruncation = rawKey.length > PROPERTY_LIMITS.maxKeyLength;
+      const key = needsTruncation ? rawKey.slice(0, PROPERTY_LIMITS.maxKeyLength) : rawKey;
+      if (needsTruncation) {
+        warnings.push(`Property key "${key}…" truncated to ${PROPERTY_LIMITS.maxKeyLength} chars`);
+      }
+      const value = rawValue ?? null;
+      if (value !== null && !FLAT_TYPES.has(typeof value)) {
+        warnings.push(`Property "${key}" has non-flat value (${typeof value}), dropped`);
+        continue;
+      }
+      if (typeof value === "string" && value.length > PROPERTY_LIMITS.maxStringValueLength) {
+        result[key] = value.slice(0, PROPERTY_LIMITS.maxStringValueLength);
+        warnings.push(`Property "${key}" value truncated to ${PROPERTY_LIMITS.maxStringValueLength} chars`);
+      } else
+        result[key] = value;
+      count++;
+    }
+    return {
+      data: count > 0 ? result : undefined,
+      warnings
+    };
+  }
+  resolveWaitUntil() {
+    return this.cfg.waitUntil ?? discoverWaitUntil();
+  }
+  log(entry) {
+    if (this.logFn)
+      this.logFn(entry);
+  }
+}
+var GLOBAL_KEY = Symbol.for("hellyeah.xray.instance");
+var createXRay = (websiteId, options) => {
+  const g = globalThis;
+  const existing = g[GLOBAL_KEY];
+  if (existing)
+    return existing;
+  const instance = new XRay(websiteId, options);
+  g[GLOBAL_KEY] = instance;
+  return instance;
+};