sdk-garden-js 0.1.0 → 0.2.0

package/dist/index.js

@@ -26,26 +26,70 @@ module.exports = __toCommonJS(index_exports);
 var _config = null;
 var _queue = [];
 var _sessionId = "";
+var _customer = null;
 var _flushTimer = null;
-var _unloadHandler = null;
-var DEFAULT_ENDPOINT = "https://ingest.sdkgarden.dev/track";
+var _exiting = false;
+var _exitDrains = 0;
+var _exitStartedAt = 0;
+var _exitActiveAt = 0;
+var _exitSendFailed = false;
+var _exitTurn = false;
+var _exitTurnCount = 0;
+var _exitProbe = null;
+var _exitProbeDueAt = Infinity;
+var _pending = /* @__PURE__ */ new Set();
+var _registered = /* @__PURE__ */ new Set();
+var _undeclared = [];
+var _declareScheduled = false;
+var DEFAULT_ENDPOINT = "https://ingest.sdkgarden.com/track";
+var MAX_BATCH_SIZE = 100;
+var MAX_QUEUE_SIZE = 1e3;
+var MAX_DRAIN_REQUESTS = 10;
+var MAX_EVENT_BYTES = 64 * 1024;
+var MAX_REQUEST_BYTES = 512 * 1024;
+var MAX_ERROR_MESSAGE_BYTES = 1e3;
+var MAX_EMAIL_LENGTH = 254;
+var MAX_EVENT_NAME_LENGTH = 100;
+var MAX_CUSTOMER_ID_LENGTH = 128;
+var MAX_CUSTOMER_NAME_LENGTH = 200;
+var MAX_EXIT_DRAINS = 3;
+var NEXT_BATCH_DELAY_MS = 10;
+var EXIT_PROBE_MS = 100;
+var EXIT_FROZEN_MS = 250;
+var EXIT_QUIET_MS = 1e3;
+var KEEPALIVE_BUDGET_BYTES = 32 * 1024;
+var WAIT_TIMEOUT_MS = 2e3;
+var MAX_TIMER_MS = 2147483647;
 var MODULE_LOADED_AT = Date.now();
+var MAX_SURFACE_METHODS = 500;
+var MAX_METHOD_NAME_LENGTH = 255;
+var MAX_SURFACE_CHARS = 32 * 1024;
+function _clamp(value, min, max, fallback) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.min(max, Math.max(min, Math.floor(value)));
+}
 function _mergeDefaults(config) {
-  var _a, _b, _c, _d, _e;
+  var _a, _b;
   return {
     apiKey: config.apiKey,
     sdkName: config.sdkName,
     sdkVersion: config.sdkVersion,
-    endpoint: (_a = config.endpoint) != null ? _a : DEFAULT_ENDPOINT,
-    debug: (_b = config.debug) != null ? _b : false,
-    disabled: (_c = config.disabled) != null ? _c : false,
-    batchSize: (_d = config.batchSize) != null ? _d : 10,
-    flushInterval: (_e = config.flushInterval) != null ? _e : 5e3
+    // An empty endpoint would POST to the host page's own URL.
+    endpoint: typeof config.endpoint === "string" && config.endpoint !== "" ? config.endpoint : DEFAULT_ENDPOINT,
+    debug: (_a = config.debug) != null ? _a : false,
+    disabled: (_b = config.disabled) != null ? _b : false,
+    // A batch size below 1 would never empty the queue; above 100 the endpoint rejects it.
+    batchSize: _clamp(config.batchSize, 1, MAX_BATCH_SIZE, 10),
+    // A tiny interval would send constantly; one too large for a timer would fire every 1 ms.
+    flushInterval: _clamp(config.flushInterval, 100, MAX_TIMER_MS, 5e3)
   };
 }
 function _generateSessionId() {
-  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
-    return crypto.randomUUID();
+  try {
+    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+      return crypto.randomUUID();
+    }
+  } catch (e) {
   }
   return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
 }
@@ -79,11 +123,67 @@ function _getMetadata() {
   }
   return meta;
 }
-function _scrubPII(str) {
-  if (typeof str !== "string") return str;
-  return str.replace(
-    /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
-    "[REDACTED]"
+var EMAIL_PATTERN = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/;
+function _customerField(value, maxLength) {
+  if (typeof value !== "string") return "";
+  return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "").trim().slice(0, maxLength).trim();
+}
+function _cleanCustomer(customer) {
+  if (customer === null || typeof customer !== "object") return null;
+  const c = customer;
+  const id = _customerField(c["id"], MAX_CUSTOMER_ID_LENGTH);
+  if (id === "") {
+    _log("Ignored a customer without an id");
+    return null;
+  }
+  if (EMAIL_PATTERN.test(id)) {
+    _log("Ignored a customer id that contains an email address");
+    return null;
+  }
+  const name = _customerField(c["name"], MAX_CUSTOMER_NAME_LENGTH);
+  if (name !== "" && EMAIL_PATTERN.test(name)) {
+    _log("Left out a customer name that contains an email address");
+    return { id };
+  }
+  return name !== "" ? { id, name } : { id };
+}
+function _truncateUtf8(str, maxBytes) {
+  let bytes = 0;
+  for (let i = 0; i < str.length; i++) {
+    const code = str.charCodeAt(i);
+    let size = code < 128 ? 1 : code < 2048 ? 2 : 3;
+    if (code >= 55296 && code <= 56319 && i + 1 < str.length) {
+      const next = str.charCodeAt(i + 1);
+      if (next >= 56320 && next <= 57343) size = 4;
+    }
+    if (bytes + size > maxBytes) return str.slice(0, i);
+    bytes += size;
+    if (size === 4) i++;
+  }
+  return str;
+}
+function _errorMessage(error) {
+  const message = error == null ? void 0 : error.message;
+  if (typeof message !== "string") return message;
+  const searched = message.slice(0, MAX_ERROR_MESSAGE_BYTES + MAX_EMAIL_LENGTH);
+  const pattern = new RegExp(EMAIL_PATTERN.source, "g");
+  let scrubbed = "";
+  let end = 0;
+  let match = pattern.exec(searched);
+  while (match && match.index < MAX_ERROR_MESSAGE_BYTES) {
+    scrubbed += searched.slice(end, match.index) + "[REDACTED]";
+    end = match.index + match[0].length;
+    match = pattern.exec(searched);
+  }
+  if (end < MAX_ERROR_MESSAGE_BYTES) scrubbed += searched.slice(end, MAX_ERROR_MESSAGE_BYTES);
+  return _truncateUtf8(scrubbed.replace(/\u0000/g, "\uFFFD"), MAX_ERROR_MESSAGE_BYTES);
+}
+var JSON_ESCAPE = /\\(?:u(0000|d[89ab][0-9a-f]{2}(?:\\ud[c-f][0-9a-f]{2})?|d[c-f][0-9a-f]{2})|[\s\S])/g;
+function _sanitizeJson(json) {
+  if (json.indexOf("\\u") === -1) return json;
+  return json.replace(
+    JSON_ESCAPE,
+    (escape, code) => code !== void 0 && code.length === 4 ? "\\ufffd" : escape
   );
 }
 function _sanitizeConfig(config) {
@@ -97,109 +197,520 @@ function _sanitizeConfig(config) {
   return sanitized;
 }
 function _log(...args) {
-  if (_config == null ? void 0 : _config.debug) {
+  if (!(_config == null ? void 0 : _config.debug)) return;
+  try {
     console.log("[SDK Garden]", ...args);
+  } catch (e) {
+  }
+}
+function _now() {
+  return typeof performance !== "undefined" ? performance.now() : Date.now();
+}
+function _unref(timer) {
+  try {
+    if (timer !== null && typeof timer === "object" && typeof timer.unref === "function") {
+      timer.unref();
+      return true;
+    } else if (typeof timer === "number" && typeof Deno !== "undefined" && typeof (Deno == null ? void 0 : Deno.unrefTimer) === "function") {
+      Deno.unrefTimer(timer);
+      return true;
+    }
+  } catch (e) {
+  }
+  return false;
+}
+function _requestTimeoutMs() {
+  return typeof window === "undefined" ? 2e3 : 1e4;
+}
+function _utf8Length(str) {
+  let bytes = str.length;
+  for (let i = 0; i < str.length; i++) {
+    const code = str.charCodeAt(i);
+    if (code > 127) bytes += code > 2047 ? 2 : 1;
   }
+  return bytes;
 }
 function _enqueue(event) {
-  _queue.push(event);
+  _checkExit();
+  if (typeof event.event !== "string" || event.event.length > MAX_EVENT_NAME_LENGTH) {
+    _log("Dropped an event whose name is not a string of at most 100 characters");
+    return;
+  }
+  if (_queue.length >= MAX_QUEUE_SIZE) {
+    _log("Queue full; dropped event", event.event);
+    return;
+  }
+  if (_customer) event.customer = _customer;
+  let json;
+  try {
+    json = JSON.stringify(event);
+  } catch (e) {
+    _log("Dropped an event that cannot be serialized", event.event);
+    return;
+  }
+  if (json.length <= MAX_EVENT_BYTES) json = _sanitizeJson(json);
+  const bytes = _utf8Length(json);
+  if (bytes > MAX_EVENT_BYTES) {
+    _log("Dropped an event larger than 64 KiB", event.event);
+    return;
+  }
+  _queue.push({ json, bytes });
   _log("Event tracked", event.event);
-  if (_config && _queue.length >= _config.batchSize) {
-    _flush();
+  if (_config && _queue.length >= _config.batchSize && !_exiting) {
+    _pump();
+  }
+}
+function _safely(fn) {
+  try {
+    fn();
+  } catch (e) {
+  }
+}
+function _trackSuccess(methodName, startTime, isAsync, argsCount) {
+  _safely(
+    () => SdkGarden.track("method_success", {
+      method: methodName,
+      duration_ms: Math.round(_now() - startTime),
+      is_async: isAsync,
+      args_count: argsCount
+    })
+  );
+}
+function _trackFailure(methodName, error, startTime, isAsync) {
+  _safely(() => {
+    const err = error instanceof Error ? error : new Error(String(error));
+    SdkGarden.trackError(err, {
+      method: methodName,
+      duration_ms: Math.round(_now() - startTime),
+      is_async: isAsync
+    });
+  });
+}
+var NATIVE_PROMISE_PROTOTYPE = Object.getPrototypeOf((async () => {
+})());
+function _watchPromise(value, onFulfilled, onRejected) {
+  try {
+    if (value === null || typeof value !== "object") return false;
+    const proto = Object.getPrototypeOf(value);
+    if (proto === NATIVE_PROMISE_PROTOTYPE || proto === Promise.prototype) {
+      if (value.then !== proto.then || value.constructor !== proto.constructor) return false;
+      value.then(onFulfilled, onRejected);
+      return true;
+    }
+    if (Object.getPrototypeOf(Object.getPrototypeOf(proto)) !== null || value.constructor !== proto.constructor || Object.prototype.toString.call(value) !== "[object Promise]") {
+      return false;
+    }
+    NATIVE_PROMISE_PROTOTYPE.then.call(value, onFulfilled, onRejected);
+    return true;
+  } catch (e) {
+    return false;
   }
 }
 function _createWrapper(methodName, fn) {
-  return function(...args) {
-    if (!_config || _config.disabled) return fn.call(this, ...args);
-    const startTime = typeof performance !== "undefined" ? performance.now() : Date.now();
-    SdkGarden.track("method_called", { method: methodName, args_count: args.length });
-    let result;
+  if (typeof fn !== "function" || typeof Proxy !== "function") return fn;
+  const wrapped = new Proxy(fn, {
+    apply(target, thisArg, args) {
+      if (!_config) return Reflect.apply(target, thisArg, args);
+      const startTime = _now();
+      _safely(() => SdkGarden.track("method_called", { method: methodName, args_count: args.length }));
+      let result;
+      try {
+        result = Reflect.apply(target, thisArg, args);
+      } catch (error) {
+        _trackFailure(methodName, error, startTime, false);
+        throw error;
+      }
+      const watched = _watchPromise(
+        result,
+        () => _trackSuccess(methodName, startTime, true, args.length),
+        (error) => _trackFailure(methodName, error, startTime, true)
+      );
+      if (!watched) _trackSuccess(methodName, startTime, false, args.length);
+      return result;
+    },
+    construct(target, args, newTarget) {
+      return Reflect.construct(target, args, newTarget === wrapped ? target : newTarget);
+    },
+    get(target, key) {
+      if (key === Symbol.hasInstance) return (value) => value instanceof target;
+      return Reflect.get(target, key);
+    }
+  });
+  return wrapped;
+}
+function _isMethodName(name) {
+  return typeof name === "string" && name.trim() !== "" && name.length <= MAX_METHOD_NAME_LENGTH;
+}
+function _surfaceList(names) {
+  const out = /* @__PURE__ */ new Set();
+  let chars = 0;
+  for (const name of names) {
+    if (out.size >= MAX_SURFACE_METHODS) break;
+    if (!_isMethodName(name) || out.has(name)) continue;
+    if (chars + name.length > MAX_SURFACE_CHARS) break;
+    out.add(name);
+    chars += name.length;
+  }
+  return Array.from(out);
+}
+function _register(methodName) {
+  if (!_isMethodName(methodName) || _registered.has(methodName) || _registered.size >= MAX_SURFACE_METHODS) return;
+  _registered.add(methodName);
+  if (!_config) return;
+  _undeclared.push(methodName);
+  if (_declareScheduled) return;
+  _declareScheduled = true;
+  Promise.resolve().then(
+    () => _safely(() => {
+      _declareScheduled = false;
+      const methods = _surfaceList(_undeclared);
+      _undeclared = [];
+      if (methods.length > 0) SdkGarden.track("api_surface", { api_surface: methods });
+    })
+  );
+}
+function _keepaliveBytesInFlight() {
+  let total = 0;
+  _pending.forEach((request) => {
+    total += request.keepaliveBytes;
+  });
+  return total;
+}
+function _takeBatch(events, maxEvents) {
+  let count = 0;
+  let bytes = 0;
+  while (count < events.length && count < maxEvents && (count === 0 || bytes + events[count].bytes <= MAX_REQUEST_BYTES)) {
+    bytes += events[count].bytes + 1;
+    count++;
+  }
+  return events.splice(0, count).map((event) => event.json);
+}
+function _send(config, batch, keepalive) {
+  var _a;
+  if (typeof fetch !== "function") {
+    _log("No global fetch() in this runtime; dropping", batch.length, "events");
+    return;
+  }
+  const body = `{"api_key":${JSON.stringify(String((_a = config.apiKey) != null ? _a : ""))},"events":[${batch.join(",")}]}`;
+  let keepaliveBytes = keepalive ? _utf8Length(body) : 0;
+  if (keepaliveBytes > 0 && _keepaliveBytesInFlight() + keepaliveBytes > KEEPALIVE_BUDGET_BYTES) {
+    keepaliveBytes = 0;
+  }
+  const controller = typeof AbortController === "function" ? new AbortController() : null;
+  let settle = () => {
+  };
+  let delivered = false;
+  const request = {
+    done: new Promise((resolve) => {
+      settle = resolve;
+    }),
+    keepaliveBytes,
+    abort() {
+      try {
+        controller == null ? void 0 : controller.abort();
+      } catch (e) {
+      }
+      settle();
+    }
+  };
+  let timer;
+  try {
+    timer = setTimeout(request.abort, _requestTimeoutMs());
+    _unref(timer);
+  } catch (e) {
+  }
+  _pending.add(request);
+  request.done.then(
+    () => _safely(() => {
+      if (timer !== void 0) clearTimeout(timer);
+      if (!_pending.delete(request)) return;
+      if (_exiting) {
+        _exitActiveAt = _now();
+        if (!delivered) _exitSendFailed = true;
+      } else if (delivered && _config && _queue.length >= _config.batchSize) {
+        _pumpSoon();
+      }
+    })
+  );
+  _log("Sending events", batch.length);
+  try {
+    fetch(config.endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body,
+      keepalive: keepaliveBytes > 0,
+      signal: controller == null ? void 0 : controller.signal
+    }).then(
+      (response) => {
+        let discarded;
+        try {
+          delivered = Boolean(response && response.ok);
+          const stream = response == null ? void 0 : response.body;
+          if (stream && typeof stream.cancel === "function") discarded = stream.cancel();
+        } catch (e) {
+        }
+        Promise.resolve(discarded).then(settle, settle);
+      },
+      () => settle()
+      // Silent failure — locked by CLIENT-01 "fail silently on network errors".
+    );
+  } catch (e) {
+    settle();
+  }
+}
+function _pump() {
+  const config = _config;
+  if (!config || _exiting || _pending.size > 0 || _queue.length === 0) return;
+  _send(config, _takeBatch(_queue, config.batchSize), false);
+}
+function _pumpSoon() {
+  try {
+    _unref(setTimeout(_pump, NEXT_BATCH_DELAY_MS));
+  } catch (e) {
+    _pump();
+  }
+}
+function _drainAll(keepalive, all = false) {
+  const config = _config;
+  if (!config || _queue.length === 0) return;
+  if (_exiting && _exitTurn && !all) {
+    if (_exitDrains >= MAX_EXIT_DRAINS || _exitSendFailed || _now() - _exitStartedAt >= WAIT_TIMEOUT_MS) {
+      return;
+    }
+    _exitDrains++;
+  }
+  const events = _queue;
+  _queue = [];
+  const size = Math.min(
+    MAX_BATCH_SIZE,
+    Math.max(config.batchSize, Math.ceil(events.length / MAX_DRAIN_REQUESTS))
+  );
+  for (let i = 0; (all || i < MAX_DRAIN_REQUESTS) && events.length > 0; i++) {
+    _send(config, _takeBatch(events, size), keepalive);
+  }
+  if (events.length > 0) _queue = events.concat(_queue);
+}
+function _waitForPending(timeoutMs, abortLate) {
+  const requests = Array.from(_pending);
+  const waitMs = timeoutMs > 0 ? Math.min(timeoutMs, _requestTimeoutMs()) : 0;
+  if (requests.length === 0 || waitMs === 0) {
+    if (abortLate) requests.forEach((request) => request.abort());
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    let timer;
     try {
-      result = fn.call(this, ...args);
-    } catch (error) {
-      const duration2 = (typeof performance !== "undefined" ? performance.now() : Date.now()) - startTime;
-      const err = error instanceof Error ? error : new Error(String(error));
-      SdkGarden.trackError(err, { method: methodName, duration_ms: Math.round(duration2), is_async: false });
-      throw error;
+      timer = setTimeout(() => {
+        if (abortLate) requests.forEach((request) => request.abort());
+        resolve();
+      }, waitMs);
+      _unref(timer);
+    } catch (e) {
     }
-    if (result !== null && typeof result === "object" && typeof result.then === "function") {
-      return result.then((value) => {
-        const duration2 = (typeof performance !== "undefined" ? performance.now() : Date.now()) - startTime;
-        SdkGarden.track("method_success", {
-          method: methodName,
-          duration_ms: Math.round(duration2),
-          is_async: true,
-          args_count: args.length
-        });
-        return value;
-      }).catch((error) => {
-        const duration2 = (typeof performance !== "undefined" ? performance.now() : Date.now()) - startTime;
-        const err = error instanceof Error ? error : new Error(String(error));
-        SdkGarden.trackError(err, { method: methodName, duration_ms: Math.round(duration2), is_async: true });
-        throw error;
-      });
+    Promise.all(requests.map((request) => request.done)).then(() => {
+      if (timer !== void 0) clearTimeout(timer);
+      resolve();
+    });
+  });
+}
+function _onNextLoopTurn(fn) {
+  try {
+    _unref(typeof setImmediate === "function" ? setImmediate(fn) : setTimeout(fn, 0));
+  } catch (e) {
+  }
+}
+function _afterMicrotasks(fn) {
+  Promise.resolve().then(() => {
+    if (typeof process !== "undefined" && typeof (process == null ? void 0 : process.nextTick) === "function") {
+      process.nextTick(() => _safely(fn));
+    } else {
+      _safely(fn);
     }
-    const duration = (typeof performance !== "undefined" ? performance.now() : Date.now()) - startTime;
-    SdkGarden.track("method_success", {
-      method: methodName,
-      duration_ms: Math.round(duration),
-      is_async: false,
-      args_count: args.length
+  });
+}
+function _onBeforeExit() {
+  _safely(() => {
+    _checkExit();
+    if (!_exiting) {
+      _exiting = true;
+      _exitStartedAt = _now();
+    }
+    _exitActiveAt = _now();
+    _beginExitTurn();
+    _watchExit();
+    _keepListenerFirst();
+    const session = _sessionId;
+    _afterMicrotasks(() => {
+      if (_sessionId !== session) return;
+      _drainAll(false);
+      void _waitForPending(WAIT_TIMEOUT_MS, true);
     });
-    return result;
-  };
+  });
 }
-function _flush() {
-  if (!_config || _queue.length === 0) return;
-  const events = _queue.splice(0, _config.batchSize);
-  const payload = JSON.stringify({ api_key: _config.apiKey, events });
-  _log("Flushing events", events.length);
-  fetch(_config.endpoint, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: payload,
-    keepalive: true
-  }).catch(() => {
+function _beginExitTurn() {
+  _exitTurn = true;
+  const turn = ++_exitTurnCount;
+  _onNextLoopTurn(() => {
+    if (turn === _exitTurnCount) _exitTurn = false;
   });
 }
+function _keepListenerFirst() {
+  try {
+    const proc = typeof process !== "undefined" ? process : void 0;
+    if (!proc || typeof proc.listeners !== "function" || typeof proc.prependListener !== "function" || typeof proc.removeListener !== "function" || proc.listeners("beforeExit")[0] === _onBeforeExit) {
+      return;
+    }
+    proc.removeListener("beforeExit", _onBeforeExit);
+    proc.prependListener("beforeExit", _onBeforeExit);
+  } catch (e) {
+  }
+}
+function _watchExit() {
+  if (_exitProbe !== null) clearTimeout(_exitProbe);
+  _exitProbe = null;
+  _exitProbeDueAt = Infinity;
+  try {
+    const timer = setTimeout(_onExitProbe, EXIT_PROBE_MS);
+    if (!_unref(timer)) {
+      clearTimeout(timer);
+      return;
+    }
+    _exitProbe = timer;
+    _exitProbeDueAt = _now() + EXIT_PROBE_MS;
+  } catch (e) {
+  }
+}
+function _onExitProbe() {
+  _safely(() => {
+    _checkExit();
+    if (_exiting) _watchExit();
+    else _pump();
+  });
+}
+function _checkExit() {
+  if (!_exiting) return;
+  const now = _now();
+  const frozen = now - _exitProbeDueAt >= EXIT_FROZEN_MS;
+  const quiet = _pending.size === 0 && now - _exitActiveAt >= EXIT_QUIET_MS;
+  if (frozen || quiet) _endExit();
+}
+function _endExit() {
+  _exiting = false;
+  _exitDrains = 0;
+  _exitSendFailed = false;
+  _exitTurn = false;
+  if (_exitProbe !== null) clearTimeout(_exitProbe);
+  _exitProbe = null;
+  _exitProbeDueAt = Infinity;
+}
+function _onTick() {
+  _checkExit();
+  if (!_exiting) _pump();
+}
+function _onPageHide() {
+  _drainAll(true);
+}
+function _onVisibilityChange() {
+  if (typeof document !== "undefined" && document.visibilityState === "hidden") {
+    _drainAll(true);
+  }
+}
+function _addLifecycleListeners() {
+  if (typeof process !== "undefined") {
+    if (typeof (process == null ? void 0 : process.prependListener) === "function") {
+      process.prependListener("beforeExit", _onBeforeExit);
+    } else if (typeof (process == null ? void 0 : process.on) === "function") {
+      process.on("beforeExit", _onBeforeExit);
+    }
+  }
+  if (typeof window !== "undefined" && typeof (window == null ? void 0 : window.addEventListener) === "function") {
+    window.addEventListener("pagehide", _onPageHide);
+  }
+  if (typeof document !== "undefined" && typeof (document == null ? void 0 : document.addEventListener) === "function") {
+    document.addEventListener("visibilitychange", _onVisibilityChange);
+  }
+}
+function _removeLifecycleListeners() {
+  if (typeof process !== "undefined" && typeof (process == null ? void 0 : process.removeListener) === "function") {
+    process.removeListener("beforeExit", _onBeforeExit);
+  }
+  if (typeof window !== "undefined" && typeof (window == null ? void 0 : window.removeEventListener) === "function") {
+    window.removeEventListener("pagehide", _onPageHide);
+  }
+  if (typeof document !== "undefined" && typeof (document == null ? void 0 : document.removeEventListener) === "function") {
+    document.removeEventListener("visibilitychange", _onVisibilityChange);
+  }
+}
+function _teardown() {
+  if (_flushTimer !== null) {
+    clearInterval(_flushTimer);
+    _flushTimer = null;
+  }
+  _removeLifecycleListeners();
+  _config = null;
+  _queue = [];
+  _sessionId = "";
+  _customer = null;
+  _endExit();
+}
+function _start(config) {
+  var _a;
+  let carried = [];
+  if (_config && !config.disabled) {
+    const next = _mergeDefaults(config);
+    if (next.apiKey === _config.apiKey && next.endpoint === _config.endpoint) {
+      carried = _queue.slice(0, MAX_QUEUE_SIZE - 1);
+    } else {
+      _drainAll(false, true);
+    }
+  }
+  _teardown();
+  if (config.disabled) {
+    return;
+  }
+  const initStartedAt = (_a = config.startedAt) != null ? _a : MODULE_LOADED_AT;
+  _config = _mergeDefaults(config);
+  _queue = carried;
+  _sessionId = _generateSessionId();
+  _customer = config.customer === void 0 ? null : _cleanCustomer(config.customer);
+  _undeclared = [];
+  const apiSurface = _surfaceList([
+    ...Array.isArray(config.methods) ? config.methods : [],
+    ..._registered
+  ]);
+  _log("Initialised", _sanitizeConfig(_config));
+  _enqueue({
+    event: "sdk_initialized",
+    sdk: { name: _config.sdkName, version: _config.sdkVersion },
+    session_id: _sessionId,
+    timestamp: Date.now(),
+    properties: {
+      environment: _getEnvironment(),
+      time_to_init_ms: Math.max(0, Date.now() - initStartedAt),
+      ...apiSurface.length > 0 ? { api_surface: apiSurface } : {}
+    },
+    meta: _getMetadata()
+  });
+  try {
+    _flushTimer = setInterval(_onTick, _config.flushInterval);
+    _unref(_flushTimer);
+  } catch (e) {
+  }
+  _addLifecycleListeners();
+}
 var SdkGarden = {
   /**
    * Initialize the SDK Garden client.
-   * Must be called once before any tracking methods.
-   * When config.disabled is true, this is a no-op.
+   * Must be called once before any events are recorded. Calling it again
+   * starts a new session. When config.disabled is true, any running client is
+   * stopped (its queued events are dropped) and everything stays a no-op.
+   * Never throws: if the runtime refuses what init needs, the client stays off.
    */
   init(config) {
-    var _a;
-    if (config.disabled) {
-      return;
-    }
-    if (_flushTimer !== null) {
-      clearInterval(_flushTimer);
-      _flushTimer = null;
-    }
-    const initStartedAt = (_a = config.startedAt) != null ? _a : MODULE_LOADED_AT;
-    _config = _mergeDefaults(config);
-    _queue = [];
-    _sessionId = _generateSessionId();
-    _log("Initialised", _sanitizeConfig(_config));
-    _enqueue({
-      event: "sdk_initialized",
-      sdk: { name: _config.sdkName, version: _config.sdkVersion },
-      session_id: _sessionId,
-      timestamp: Date.now(),
-      properties: {
-        environment: _getEnvironment(),
-        time_to_init_ms: Math.max(0, Date.now() - initStartedAt)
-      },
-      meta: _getMetadata()
-    });
-    _flushTimer = setInterval(_flush, _config.flushInterval);
-    if (typeof window !== "undefined") {
-      if (_unloadHandler) {
-        window.removeEventListener("beforeunload", _unloadHandler);
-      }
-      _unloadHandler = () => _flush();
-      window.addEventListener("beforeunload", _unloadHandler);
+    try {
+      _start(config);
+    } catch (e) {
+      _teardown();
     }
   },
   /**
@@ -207,20 +718,24 @@ var SdkGarden = {
    * No-op if SDK has not been initialised or is disabled.
    */
   track(eventName, properties) {
-    if (!_config || _config.disabled) return;
-    _enqueue({
-      event: eventName,
-      sdk: { name: _config.sdkName, version: _config.sdkVersion },
-      session_id: _sessionId,
-      timestamp: Date.now(),
-      properties: properties != null ? properties : {},
-      meta: _getMetadata()
-    });
+    const config = _config;
+    if (!config) return;
+    _safely(
+      () => _enqueue({
+        event: eventName,
+        sdk: { name: config.sdkName, version: config.sdkVersion },
+        session_id: _sessionId,
+        timestamp: Date.now(),
+        properties: properties != null ? properties : {},
+        meta: _getMetadata()
+      })
+    );
   },
   /**
    * Instrument a method with call, success, and error telemetry.
    *
-   * **Two-argument form** — wraps a standalone function:
+   * **Two-argument form** — wraps a standalone function. Safe to call before
+   * init(), for example at module level; calls are recorded once init() runs:
    * ```ts
    * function processPayment(amount: number): Receipt { ... }
    * export const trackedProcessPayment = SdkGarden.trackMethod('processPayment', processPayment);
@@ -233,17 +748,17 @@ var SdkGarden = {
    *   processPayment(amount: number): Receipt { ... }
    * }
    * ```
-   *
-   * **Async limitation (v1):** For async functions in the two-argument form,
-   * `method_success` is recorded only when the caller awaits or chains `.then()`.
-   * Class method decorators do not have this limitation.
    */
   trackMethod(methodName, fn) {
+    _safely(() => _register(methodName));
     if (fn !== void 0) {
-      if (!_config || _config.disabled) return fn;
       return _createWrapper(methodName, fn);
     }
-    return function(target, _context) {
+    return function(target, _context, descriptor) {
+      if (descriptor !== null && typeof descriptor === "object") {
+        if (typeof descriptor.value !== "function") return descriptor;
+        return { ...descriptor, value: _createWrapper(methodName, descriptor.value) };
+      }
       return _createWrapper(methodName, target);
     };
   },
@@ -253,42 +768,85 @@ var SdkGarden = {
    * No-op if SDK is uninitialised or disabled.
    */
   trackError(error, context) {
-    if (!_config || _config.disabled) return;
-    _enqueue({
-      event: "sdk_error",
-      sdk: { name: _config.sdkName, version: _config.sdkVersion },
-      session_id: _sessionId,
-      timestamp: Date.now(),
-      properties: {
-        error_message: _scrubPII(error.message),
-        error_type: error.name,
-        ...context != null ? context : {}
-      },
-      meta: _getMetadata()
+    const config = _config;
+    if (!config) return;
+    _safely(
+      () => _enqueue({
+        event: "sdk_error",
+        sdk: { name: config.sdkName, version: config.sdkVersion },
+        session_id: _sessionId,
+        timestamp: Date.now(),
+        properties: {
+          error_message: _errorMessage(error),
+          error_type: error == null ? void 0 : error.name,
+          ...context != null ? context : {}
+        },
+        meta: _getMetadata()
+      })
+    );
+  },
+  /**
+   * Attribute the session to one of your customers: an app or account, by an
+   * ID from your own system. Every event tracked afterwards carries it, so the
+   * dashboard can show which customers are on old versions, still call
+   * deprecated methods or hit errors. Pass null to stop. Lasts until the next
+   * init() or shutdown(); no-op before init().
+   *
+   * Never pass an email address or other personal data: an ID containing an
+   * email address is ignored.
+   *
+   * @example
+   * SdkGarden.setCustomer({ id: account.id, name: account.displayName });
+   */
+  setCustomer(customer) {
+    if (!_config) return;
+    _safely(() => {
+      _customer = customer === null ? null : _cleanCustomer(customer);
     });
   },
   /**
-   * Manually trigger a flush of queued events.
-   * Useful in beforeunload handlers or at process exit.
+   * Send every queued event now and wait for the requests to finish.
+   * Useful at the end of a serverless handler or a test.
+   */
+  flush(timeoutMs = WAIT_TIMEOUT_MS) {
+    try {
+      _checkExit();
+      _drainAll(false);
+      return _waitForPending(timeoutMs, false);
+    } catch (e) {
+      return Promise.resolve();
+    }
+  },
+  /**
+   * Send every queued event and stop the client. Call it, and await it, from
+   * your SDK's close() or before process.exit(): explicit exits and signals
+   * skip the automatic send that runs when Node exits on its own.
    */
-  _flush,
+  shutdown(timeoutMs = WAIT_TIMEOUT_MS) {
+    try {
+      if (timeoutMs > 0) _drainAll(typeof window !== "undefined", true);
+      _teardown();
+      return _waitForPending(timeoutMs, true);
+    } catch (e) {
+      _safely(_teardown);
+      return Promise.resolve();
+    }
+  },
+  _flush() {
+    void SdkGarden.flush();
+  },
   /**
    * Reset all internal state.
    * FOR UNIT TESTS ONLY — not documented in README.
-   * Clears queue, config, session ID, and flush timer.
+   * Clears queue, config, session ID, flush timer, listeners, registered
+   * method names and the record of requests in flight, without sending or cancelling anything.
    */
   _reset() {
-    if (_flushTimer !== null) {
-      clearInterval(_flushTimer);
-      _flushTimer = null;
-    }
-    if (typeof window !== "undefined" && _unloadHandler) {
-      window.removeEventListener("beforeunload", _unloadHandler);
-      _unloadHandler = null;
-    }
-    _config = null;
-    _queue = [];
-    _sessionId = "";
+    _teardown();
+    _pending.clear();
+    _registered.clear();
+    _undeclared = [];
   }
 };
 var index_default = SdkGarden;
+module.exports = Object.defineProperties(module.exports.default, { default: { value: module.exports.default }, __esModule: { value: true } });