@tell-rs/node 0.2.0

package/dist/index.cjs

@@ -0,0 +1,829 @@
+"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, {
+  ClosedError: () => ClosedError,
+  ConfigurationError: () => ConfigurationError,
+  Events: () => Events,
+  NetworkError: () => NetworkError,
+  SENSITIVE_PARAMS: () => SENSITIVE_PARAMS,
+  SerializationError: () => SerializationError,
+  Tell: () => Tell,
+  TellError: () => TellError,
+  ValidationError: () => ValidationError,
+  development: () => development,
+  production: () => production,
+  redact: () => redact,
+  redactLog: () => redactLog
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/config.ts
+var import_node_os = require("os");
+var DEFAULTS = {
+  endpoint: "https://collect.tell.app",
+  batchSize: 100,
+  flushInterval: 1e4,
+  maxRetries: 3,
+  closeTimeout: 5e3,
+  networkTimeout: 3e4,
+  logLevel: "info",
+  source: (0, import_node_os.hostname)(),
+  disabled: false,
+  maxQueueSize: 1e3,
+  gzip: false
+};
+function resolveConfig(config) {
+  return { ...DEFAULTS, ...config };
+}
+function development(apiKey, overrides) {
+  return {
+    endpoint: "http://localhost:8080",
+    batchSize: 10,
+    flushInterval: 2e3,
+    logLevel: "debug",
+    ...overrides,
+    apiKey
+  };
+}
+function production(apiKey, overrides) {
+  return {
+    logLevel: "error",
+    ...overrides,
+    apiKey
+  };
+}
+
+// ../core/src/constants.ts
+var Events = {
+  // User Lifecycle
+  UserSignedUp: "User Signed Up",
+  UserSignedIn: "User Signed In",
+  UserSignedOut: "User Signed Out",
+  UserInvited: "User Invited",
+  UserOnboarded: "User Onboarded",
+  AuthenticationFailed: "Authentication Failed",
+  PasswordReset: "Password Reset",
+  TwoFactorEnabled: "Two Factor Enabled",
+  TwoFactorDisabled: "Two Factor Disabled",
+  // Revenue & Billing
+  OrderCompleted: "Order Completed",
+  OrderRefunded: "Order Refunded",
+  OrderCanceled: "Order Canceled",
+  PaymentFailed: "Payment Failed",
+  PaymentMethodAdded: "Payment Method Added",
+  PaymentMethodUpdated: "Payment Method Updated",
+  PaymentMethodRemoved: "Payment Method Removed",
+  // Subscription
+  SubscriptionStarted: "Subscription Started",
+  SubscriptionRenewed: "Subscription Renewed",
+  SubscriptionPaused: "Subscription Paused",
+  SubscriptionResumed: "Subscription Resumed",
+  SubscriptionChanged: "Subscription Changed",
+  SubscriptionCanceled: "Subscription Canceled",
+  // Trial
+  TrialStarted: "Trial Started",
+  TrialEndingSoon: "Trial Ending Soon",
+  TrialEnded: "Trial Ended",
+  TrialConverted: "Trial Converted",
+  // Shopping
+  CartViewed: "Cart Viewed",
+  CartUpdated: "Cart Updated",
+  CartAbandoned: "Cart Abandoned",
+  CheckoutStarted: "Checkout Started",
+  CheckoutCompleted: "Checkout Completed",
+  // Engagement
+  PageViewed: "Page Viewed",
+  FeatureUsed: "Feature Used",
+  SearchPerformed: "Search Performed",
+  FileUploaded: "File Uploaded",
+  NotificationSent: "Notification Sent",
+  NotificationClicked: "Notification Clicked",
+  // Communication
+  EmailSent: "Email Sent",
+  EmailOpened: "Email Opened",
+  EmailClicked: "Email Clicked",
+  EmailBounced: "Email Bounced",
+  EmailUnsubscribed: "Email Unsubscribed",
+  SupportTicketCreated: "Support Ticket Created",
+  SupportTicketResolved: "Support Ticket Resolved"
+};
+
+// ../core/src/errors.ts
+var TellError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TellError";
+  }
+};
+var ConfigurationError = class extends TellError {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigurationError";
+  }
+};
+var ValidationError = class extends TellError {
+  field;
+  constructor(field, message) {
+    super(`${field}: ${message}`);
+    this.name = "ValidationError";
+    this.field = field;
+  }
+};
+var NetworkError = class extends TellError {
+  statusCode;
+  constructor(message, statusCode) {
+    super(message);
+    this.name = "NetworkError";
+    this.statusCode = statusCode;
+  }
+};
+var ClosedError = class extends TellError {
+  constructor() {
+    super("Client is closed");
+    this.name = "ClosedError";
+  }
+};
+var SerializationError = class extends TellError {
+  constructor(message) {
+    super(message);
+    this.name = "SerializationError";
+  }
+};
+
+// ../core/src/validation.ts
+var HEX_RE = /^[0-9a-fA-F]{32}$/;
+var MAX_EVENT_NAME = 256;
+var MAX_LOG_MESSAGE = 65536;
+function validateApiKey(key) {
+  if (!key) {
+    throw new ConfigurationError("apiKey is required");
+  }
+  if (!HEX_RE.test(key)) {
+    throw new ConfigurationError(
+      "apiKey must be exactly 32 hex characters"
+    );
+  }
+}
+function validateEventName(name) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new ValidationError("eventName", "must be a non-empty string");
+  }
+  if (name.length > MAX_EVENT_NAME) {
+    throw new ValidationError(
+      "eventName",
+      `must be at most ${MAX_EVENT_NAME} characters, got ${name.length}`
+    );
+  }
+}
+function validateLogMessage(message) {
+  if (typeof message !== "string" || message.length === 0) {
+    throw new ValidationError("message", "must be a non-empty string");
+  }
+  if (message.length > MAX_LOG_MESSAGE) {
+    throw new ValidationError(
+      "message",
+      `must be at most ${MAX_LOG_MESSAGE} characters, got ${message.length}`
+    );
+  }
+}
+function validateUserId(id) {
+  if (typeof id !== "string" || id.length === 0) {
+    throw new ValidationError("userId", "must be a non-empty string");
+  }
+}
+
+// ../core/src/batcher.ts
+var Batcher = class {
+  queue = [];
+  timer = null;
+  closed = false;
+  flushing = null;
+  config;
+  constructor(config) {
+    this.config = config;
+    this.timer = setInterval(() => {
+      if (this.queue.length > 0) {
+        this.flush().catch(() => {
+        });
+      }
+    }, config.interval);
+    if (this.timer && typeof this.timer.unref === "function") {
+      this.timer.unref();
+    }
+  }
+  add(item) {
+    if (this.closed) return;
+    if (this.queue.length >= this.config.maxQueueSize) {
+      this.queue.shift();
+      if (this.config.onOverflow) {
+        this.config.onOverflow();
+      }
+    }
+    this.queue.push(item);
+    if (this.queue.length >= this.config.size) {
+      this.flush().catch(() => {
+      });
+    }
+  }
+  async flush() {
+    if (this.flushing) {
+      return this.flushing;
+    }
+    this.flushing = this.doFlush();
+    try {
+      await this.flushing;
+    } finally {
+      this.flushing = null;
+    }
+  }
+  async close() {
+    this.closed = true;
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    await this.flush();
+  }
+  get pending() {
+    return this.queue.length;
+  }
+  drain() {
+    const items = this.queue;
+    this.queue = [];
+    return items;
+  }
+  halveBatchSize() {
+    this.config.size = Math.max(1, Math.floor(this.config.size / 2));
+  }
+  async doFlush() {
+    while (this.queue.length > 0) {
+      const batch = this.queue.slice(0, this.config.size);
+      try {
+        await this.config.send(batch);
+        this.queue.splice(0, batch.length);
+      } catch {
+        return;
+      }
+    }
+  }
+};
+
+// ../core/src/before-send.ts
+function runBeforeSend(item, fns) {
+  const pipeline = Array.isArray(fns) ? fns : [fns];
+  let current = item;
+  for (const fn of pipeline) {
+    if (current === null) return null;
+    current = fn(current);
+  }
+  return current;
+}
+
+// ../core/src/redact.ts
+var SENSITIVE_PARAMS = [
+  "token",
+  "api_key",
+  "key",
+  "secret",
+  "password",
+  "access_token",
+  "refresh_token",
+  "authorization"
+];
+function stripUrlParams(url, params) {
+  try {
+    const u = new URL(url);
+    for (const p of params) u.searchParams.delete(p);
+    return u.toString();
+  } catch {
+    return url;
+  }
+}
+function stripParamsInProperties(props, params) {
+  if (!props) return props;
+  const out = {};
+  for (const [k, v] of Object.entries(props)) {
+    if (typeof v === "string" && v.startsWith("http")) {
+      out[k] = stripUrlParams(v, params);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+function redactKeysInProperties(props, keys) {
+  if (!props) return props;
+  const out = {};
+  for (const [k, v] of Object.entries(props)) {
+    out[k] = keys.includes(k) ? "[REDACTED]" : v;
+  }
+  return out;
+}
+function redact(options) {
+  const { stripParams, redactKeys, dropRoutes } = options;
+  return (event) => {
+    if (dropRoutes && dropRoutes.length > 0 && event.context?.url) {
+      try {
+        const pathname = new URL(String(event.context.url)).pathname;
+        for (const prefix of dropRoutes) {
+          if (pathname.startsWith(prefix)) return null;
+        }
+      } catch {
+      }
+    }
+    let ctx = event.context;
+    let props = event.properties;
+    let traits = event.traits;
+    if (stripParams && stripParams.length > 0) {
+      if (ctx?.url && typeof ctx.url === "string") {
+        ctx = { ...ctx, url: stripUrlParams(ctx.url, stripParams) };
+      }
+      props = stripParamsInProperties(props, stripParams);
+      traits = stripParamsInProperties(traits, stripParams);
+    }
+    if (redactKeys && redactKeys.length > 0) {
+      props = redactKeysInProperties(props, redactKeys);
+      traits = redactKeysInProperties(traits, redactKeys);
+    }
+    if (ctx !== event.context || props !== event.properties || traits !== event.traits) {
+      return { ...event, context: ctx, properties: props, traits };
+    }
+    return event;
+  };
+}
+function redactLog(options) {
+  const { redactKeys } = options;
+  return (log) => {
+    if (redactKeys && redactKeys.length > 0 && log.data) {
+      const data = redactKeysInProperties(log.data, redactKeys);
+      if (data !== log.data) {
+        return { ...log, data };
+      }
+    }
+    return log;
+  };
+}
+
+// src/transport.ts
+var import_node_zlib = require("zlib");
+var HttpTransport = class {
+  endpoint;
+  apiKey;
+  maxRetries;
+  networkTimeout;
+  gzip;
+  onError;
+  onPayloadTooLarge;
+  constructor(config) {
+    this.endpoint = config.endpoint;
+    this.apiKey = config.apiKey;
+    this.maxRetries = config.maxRetries;
+    this.networkTimeout = config.networkTimeout;
+    this.gzip = config.gzip;
+    this.onError = config.onError;
+    this.onPayloadTooLarge = config.onPayloadTooLarge;
+  }
+  async sendEvents(events) {
+    if (events.length === 0) return;
+    const body = events.map((e) => JSON.stringify(e)).join("\n");
+    await this.send("/v1/events", body);
+  }
+  async sendLogs(logs) {
+    if (logs.length === 0) return;
+    const body = logs.map((l) => JSON.stringify(l)).join("\n");
+    await this.send("/v1/logs", body);
+  }
+  async send(path, body) {
+    const url = `${this.endpoint}${path}`;
+    const headers = {
+      "Content-Type": "application/x-ndjson",
+      Authorization: `Bearer ${this.apiKey}`
+    };
+    let payload = body;
+    if (this.gzip) {
+      payload = (0, import_node_zlib.gzipSync)(body);
+      headers["Content-Encoding"] = "gzip";
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      if (attempt > 0) {
+        await this.backoff(attempt);
+      }
+      try {
+        const response = await globalThis.fetch(url, {
+          method: "POST",
+          headers,
+          body: payload,
+          signal: AbortSignal.timeout(this.networkTimeout)
+        });
+        if (response.status === 202) {
+          return;
+        }
+        if (response.status === 207) {
+          if (this.onError) {
+            const data = await response.json().catch(() => null);
+            this.onError(
+              new NetworkError(
+                `Partial success: ${data?.rejected ?? "unknown"} items rejected`,
+                207
+              )
+            );
+          }
+          return;
+        }
+        if (response.status === 413) {
+          if (this.onPayloadTooLarge) {
+            this.onPayloadTooLarge();
+          }
+          throw new NetworkError("Payload too large", 413);
+        }
+        if (response.status === 401) {
+          throw new NetworkError("Invalid API key", 401);
+        }
+        if (response.status >= 400 && response.status < 500) {
+          throw new NetworkError(
+            `HTTP ${response.status}: ${response.statusText}`,
+            response.status
+          );
+        }
+        lastError = new NetworkError(
+          `HTTP ${response.status}: ${response.statusText}`,
+          response.status
+        );
+      } catch (err) {
+        if (err instanceof NetworkError && err.statusCode === 413) {
+          throw err;
+        }
+        if (err instanceof NetworkError && err.statusCode && err.statusCode < 500) {
+          if (this.onError) this.onError(err);
+          return;
+        }
+        lastError = err instanceof Error ? err : new NetworkError(String(err));
+      }
+    }
+    if (lastError && this.onError) {
+      this.onError(lastError);
+    }
+  }
+  backoff(attempt) {
+    const base = 1e3 * Math.pow(1.5, attempt - 1);
+    const jitter = base * 0.2 * Math.random();
+    const delay = Math.min(base + jitter, 3e4);
+    return new Promise((resolve) => setTimeout(resolve, delay));
+  }
+};
+
+// src/index.ts
+var LOG_LEVELS = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3
+};
+function uuid() {
+  return crypto.randomUUID();
+}
+var Tell = class {
+  transport;
+  eventBatcher;
+  logBatcher;
+  deviceId;
+  sessionId;
+  onError;
+  source;
+  closeTimeout;
+  sdkLogLevel;
+  beforeSend;
+  beforeSendLog;
+  superProperties = {};
+  closed = false;
+  _disabled;
+  constructor(config) {
+    validateApiKey(config.apiKey);
+    const resolved = resolveConfig(config);
+    this.onError = resolved.onError;
+    this.source = resolved.source;
+    this.closeTimeout = resolved.closeTimeout;
+    this.sdkLogLevel = LOG_LEVELS[resolved.logLevel] ?? 2;
+    this._disabled = resolved.disabled;
+    this.beforeSend = resolved.beforeSend;
+    this.beforeSendLog = resolved.beforeSendLog;
+    this.deviceId = uuid();
+    this.sessionId = uuid();
+    this.transport = new HttpTransport({
+      endpoint: resolved.endpoint,
+      apiKey: resolved.apiKey,
+      maxRetries: resolved.maxRetries,
+      networkTimeout: resolved.networkTimeout,
+      gzip: resolved.gzip,
+      onError: this.onError,
+      onPayloadTooLarge: () => {
+        this.eventBatcher.halveBatchSize();
+        this.logBatcher.halveBatchSize();
+        this.sdkDebug("413 received, halved batch size");
+      }
+    });
+    this.eventBatcher = new Batcher({
+      size: resolved.batchSize,
+      interval: resolved.flushInterval,
+      maxQueueSize: resolved.maxQueueSize,
+      send: (items) => this.transport.sendEvents(items),
+      onOverflow: () => {
+        this.sdkDebug("event queue overflow, dropping oldest item");
+      }
+    });
+    this.logBatcher = new Batcher({
+      size: resolved.batchSize,
+      interval: resolved.flushInterval,
+      maxQueueSize: resolved.maxQueueSize,
+      send: (items) => this.transport.sendLogs(items),
+      onOverflow: () => {
+        this.sdkDebug("log queue overflow, dropping oldest item");
+      }
+    });
+    this.sdkDebug(`initialized (endpoint=${resolved.endpoint}, batch=${resolved.batchSize}, flush=${resolved.flushInterval}ms)`);
+  }
+  // --- Super Properties ---
+  register(properties) {
+    Object.assign(this.superProperties, properties);
+  }
+  unregister(key) {
+    delete this.superProperties[key];
+  }
+  // --- Disabled ---
+  disable() {
+    this._disabled = true;
+  }
+  enable() {
+    this._disabled = false;
+  }
+  // --- Events ---
+  track(userId, eventName, properties) {
+    if (this._disabled) return;
+    if (this.closed) {
+      this.reportError(new ClosedError());
+      return;
+    }
+    try {
+      validateUserId(userId);
+      validateEventName(eventName);
+    } catch (err) {
+      this.reportError(err);
+      return;
+    }
+    let event = {
+      type: "track",
+      event: eventName,
+      device_id: this.deviceId,
+      session_id: this.sessionId,
+      user_id: userId,
+      timestamp: Date.now(),
+      properties: { ...this.superProperties, ...properties }
+    };
+    if (this.beforeSend) {
+      event = runBeforeSend(event, this.beforeSend);
+      if (event === null) return;
+    }
+    this.eventBatcher.add(event);
+  }
+  identify(userId, traits) {
+    if (this._disabled) return;
+    if (this.closed) {
+      this.reportError(new ClosedError());
+      return;
+    }
+    try {
+      validateUserId(userId);
+    } catch (err) {
+      this.reportError(err);
+      return;
+    }
+    let event = {
+      type: "identify",
+      device_id: this.deviceId,
+      session_id: this.sessionId,
+      user_id: userId,
+      timestamp: Date.now(),
+      traits
+    };
+    if (this.beforeSend) {
+      event = runBeforeSend(event, this.beforeSend);
+      if (event === null) return;
+    }
+    this.eventBatcher.add(event);
+  }
+  group(userId, groupId, properties) {
+    if (this._disabled) return;
+    if (this.closed) {
+      this.reportError(new ClosedError());
+      return;
+    }
+    try {
+      validateUserId(userId);
+      if (!groupId) throw new ValidationError("groupId", "is required");
+    } catch (err) {
+      this.reportError(err);
+      return;
+    }
+    let event = {
+      type: "group",
+      device_id: this.deviceId,
+      session_id: this.sessionId,
+      user_id: userId,
+      group_id: groupId,
+      timestamp: Date.now(),
+      properties: { ...this.superProperties, ...properties }
+    };
+    if (this.beforeSend) {
+      event = runBeforeSend(event, this.beforeSend);
+      if (event === null) return;
+    }
+    this.eventBatcher.add(event);
+  }
+  revenue(userId, amount, currency, orderId, properties) {
+    if (this._disabled) return;
+    if (this.closed) {
+      this.reportError(new ClosedError());
+      return;
+    }
+    try {
+      validateUserId(userId);
+      if (amount <= 0) throw new ValidationError("amount", "must be positive");
+      if (!currency) throw new ValidationError("currency", "is required");
+      if (!orderId) throw new ValidationError("orderId", "is required");
+    } catch (err) {
+      this.reportError(err);
+      return;
+    }
+    let event = {
+      type: "track",
+      event: "Order Completed",
+      device_id: this.deviceId,
+      session_id: this.sessionId,
+      user_id: userId,
+      timestamp: Date.now(),
+      properties: {
+        ...this.superProperties,
+        ...properties,
+        order_id: orderId,
+        amount,
+        currency
+      }
+    };
+    if (this.beforeSend) {
+      event = runBeforeSend(event, this.beforeSend);
+      if (event === null) return;
+    }
+    this.eventBatcher.add(event);
+  }
+  alias(previousId, userId) {
+    if (this._disabled) return;
+    if (this.closed) {
+      this.reportError(new ClosedError());
+      return;
+    }
+    try {
+      if (!previousId) throw new ValidationError("previousId", "is required");
+      validateUserId(userId);
+    } catch (err) {
+      this.reportError(err);
+      return;
+    }
+    let event = {
+      type: "alias",
+      device_id: this.deviceId,
+      session_id: this.sessionId,
+      user_id: userId,
+      timestamp: Date.now(),
+      properties: { previous_id: previousId }
+    };
+    if (this.beforeSend) {
+      event = runBeforeSend(event, this.beforeSend);
+      if (event === null) return;
+    }
+    this.eventBatcher.add(event);
+  }
+  resetSession() {
+    this.sessionId = uuid();
+  }
+  // --- Logging ---
+  log(level, message, service, data) {
+    if (this._disabled) return;
+    if (this.closed) {
+      this.reportError(new ClosedError());
+      return;
+    }
+    try {
+      validateLogMessage(message);
+    } catch (err) {
+      this.reportError(err);
+      return;
+    }
+    let logEntry = {
+      level,
+      message,
+      source: this.source,
+      service: service ?? "app",
+      session_id: this.sessionId,
+      timestamp: Date.now(),
+      data
+    };
+    if (this.beforeSendLog) {
+      logEntry = runBeforeSend(logEntry, this.beforeSendLog);
+      if (logEntry === null) return;
+    }
+    this.logBatcher.add(logEntry);
+  }
+  logEmergency(message, service, data) {
+    this.log("emergency", message, service, data);
+  }
+  logAlert(message, service, data) {
+    this.log("alert", message, service, data);
+  }
+  logCritical(message, service, data) {
+    this.log("critical", message, service, data);
+  }
+  logError(message, service, data) {
+    this.log("error", message, service, data);
+  }
+  logWarning(message, service, data) {
+    this.log("warning", message, service, data);
+  }
+  logNotice(message, service, data) {
+    this.log("notice", message, service, data);
+  }
+  logInfo(message, service, data) {
+    this.log("info", message, service, data);
+  }
+  logDebug(message, service, data) {
+    this.log("debug", message, service, data);
+  }
+  logTrace(message, service, data) {
+    this.log("trace", message, service, data);
+  }
+  // --- Lifecycle ---
+  async flush() {
+    await Promise.all([this.eventBatcher.flush(), this.logBatcher.flush()]);
+  }
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.sdkDebug("closing...");
+    const work = Promise.all([this.eventBatcher.close(), this.logBatcher.close()]);
+    const timeout = new Promise(
+      (_, reject) => setTimeout(() => reject(new Error("close timed out")), this.closeTimeout)
+    );
+    try {
+      await Promise.race([work, timeout]);
+    } catch (err) {
+      this.reportError(err);
+    }
+  }
+  // --- Internal ---
+  reportError(err) {
+    if (this.onError && err instanceof Error) {
+      this.onError(err);
+    }
+  }
+  sdkDebug(msg) {
+    if (this.sdkLogLevel >= LOG_LEVELS.debug) {
+      console.debug(`[Tell] ${msg}`);
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ClosedError,
+  ConfigurationError,
+  Events,
+  NetworkError,
+  SENSITIVE_PARAMS,
+  SerializationError,
+  Tell,
+  TellError,
+  ValidationError,
+  development,
+  production,
+  redact,
+  redactLog
+});
+//# sourceMappingURL=index.cjs.map