sdk-garden-js 0.1.1 → 0.2.0

package/README.md

@@ -61,14 +61,35 @@ Requires Node.js 18+ (for the global `fetch`) or any modern browser.
 | `batchSize` | `number` | `10` | Maximum events per request, from 1 to 100; a full batch is sent right away |
 | `flushInterval` | `number` | `5000` | Milliseconds between sends of whatever is queued, at least 100 |
 | `startedAt` | `number` | module load time | `Date.now()` when your SDK began initializing; reported as `time_to_init_ms` for the dashboard's init timing |
+| `methods` | `string[]` | `[]` | Public methods of your SDK that are not wrapped with `trackMethod()`, so the dashboard's API Surface panel can show them when nobody calls them |
+| `customer` | `{ id: string; name?: string }` | _(none)_ | The app or customer account this session runs for (see [Customers](#customers)) |
+
+### API surface
+
+Every name passed to `trackMethod()` is declared as part of your SDK's API surface, once per session (in the `sdk_initialized` event, or in one `api_surface` event for methods wrapped after `init()`). The dashboard lists those methods next to the ones people call, so the methods nobody uses show up with zero calls. Add methods you don't wrap with the `methods` option. Up to 500 names are declared.
+
+### Customers
+
+Tell SDK Garden which of your customers a session belongs to, and the dashboard's Customers page shows who is on an old version, who still calls a deprecated method and who hits errors, so you know who to contact.
+
+```typescript
+// When your SDK knows which account it runs for, for example after resolving its API key:
+SdkGarden.setCustomer({ id: account.id, name: account.displayName });
+
+// Or at init, if you already know it:
+SdkGarden.init({ apiKey: 'sgk_...', sdkName: 'my-sdk', sdkVersion: '1.0.0', customer: { id: 'acct_123' } });
+```
+
+Use an ID from your own system, such as an account, project or app ID, and optionally a display name. Nothing is attributed unless you call this. Don't pass email addresses or other personal data: an ID that contains an email address is ignored, and so is a name that contains one. IDs are cut to 128 characters and names to 200. `setCustomer(null)` stops attributing; the customer lasts until the next `init()` or `shutdown()`.
 
 ## What gets sent
 
 Each event carries your SDK's name and version, an event type, a random session ID created when `init()` runs, and a timestamp. Depending on the event:
 
-- **`sdk_initialized`**: runtime (`node` + Node version, or `browser` + screen/viewport size, pixel ratio, timezone and language) and `time_to_init_ms`.
+- **`sdk_initialized`**: runtime (`node` + Node version, or `browser` + screen/viewport size, pixel ratio, timezone and language), `time_to_init_ms`, and the names of your SDK's methods (see [API surface](#api-surface)).
 - **`method_called` / `method_success`**: method name, duration, sync/async, and the *number* of arguments.
 - **`sdk_error`**: error type and message (email addresses are redacted) plus the method and duration.
+- **If you set a customer**, every event carries its ID and name (see [Customers](#customers)).
 - **In browsers**, every event also carries the page's origin (for example `https://shop.example.com`), never the full URL, path, query string or referrer.
 
 Never sent: argument or return values, request or response bodies, cookies or stack traces. Error messages go out as they are apart from email addresses, so anything your SDK puts in an error message, such as a hostname, a URL or an ID, goes with it. Nothing is sent when `disabled: true`.

package/dist/index.d.mts

@@ -46,6 +46,27 @@ interface SdkGardenConfig {
      * Default: when sdk-garden-js was first loaded.
      */
     startedAt?: number;
+    /**
+     * Names of your SDK's public methods that are not wrapped with
+     * trackMethod(). Sent once per session with every name passed to
+     * trackMethod(), so the dashboard can list the methods nobody calls.
+     */
+    methods?: string[];
+    /**
+     * The app or customer account this session runs for, so the dashboard can
+     * show which customers are on old versions, call deprecated methods or hit
+     * errors. Use an ID from your own system (an account or project ID), never
+     * an email address or other personal data. Can also be set later with
+     * setCustomer(). Default: none.
+     */
+    customer?: SdkGardenCustomer;
+}
+/** The app or customer account a session is attributed to (see setCustomer()). */
+interface SdkGardenCustomer {
+    /** An opaque ID from your system, up to 128 characters, e.g. "acct_123". */
+    id: string;
+    /** A display name for the dashboard, up to 200 characters, e.g. "Acme Corp". */
+    name?: string;
 }
 /**
  * Class method decorator returned by SdkGarden.trackMethod(name), for Stage 3
@@ -74,6 +95,11 @@ interface SdkGardenObject {
     /** Wrapper form — pass an existing function, receive the instrumented version. */
     trackMethod<T extends (...args: any[]) => any>(methodName: string, fn: T): T;
     trackError(error: Error, context?: Record<string, unknown>): void;
+    /**
+     * Attribute this session's events from now on to a customer, or pass null
+     * to stop. No-op before init().
+     */
+    setCustomer(customer: SdkGardenCustomer | null): void;
     /**
      * Send every queued event now. Resolves once they (and any requests already
      * in flight) have finished, or after `timeoutMs` (default 2000), whichever
@@ -114,4 +140,4 @@ interface SdkGardenObject {
  */
 declare const SdkGarden: SdkGardenObject;
 
-export { type SdkGardenConfig, type SdkMethodDecorator, SdkGarden as default };
+export { type SdkGardenConfig, type SdkGardenCustomer, type SdkMethodDecorator, SdkGarden as default };

package/dist/index.d.ts

@@ -46,6 +46,27 @@ interface SdkGardenConfig {
      * Default: when sdk-garden-js was first loaded.
      */
     startedAt?: number;
+    /**
+     * Names of your SDK's public methods that are not wrapped with
+     * trackMethod(). Sent once per session with every name passed to
+     * trackMethod(), so the dashboard can list the methods nobody calls.
+     */
+    methods?: string[];
+    /**
+     * The app or customer account this session runs for, so the dashboard can
+     * show which customers are on old versions, call deprecated methods or hit
+     * errors. Use an ID from your own system (an account or project ID), never
+     * an email address or other personal data. Can also be set later with
+     * setCustomer(). Default: none.
+     */
+    customer?: SdkGardenCustomer;
+}
+/** The app or customer account a session is attributed to (see setCustomer()). */
+interface SdkGardenCustomer {
+    /** An opaque ID from your system, up to 128 characters, e.g. "acct_123". */
+    id: string;
+    /** A display name for the dashboard, up to 200 characters, e.g. "Acme Corp". */
+    name?: string;
 }
 /**
  * Class method decorator returned by SdkGarden.trackMethod(name), for Stage 3
@@ -74,6 +95,11 @@ interface SdkGardenObject {
     /** Wrapper form — pass an existing function, receive the instrumented version. */
     trackMethod<T extends (...args: any[]) => any>(methodName: string, fn: T): T;
     trackError(error: Error, context?: Record<string, unknown>): void;
+    /**
+     * Attribute this session's events from now on to a customer, or pass null
+     * to stop. No-op before init().
+     */
+    setCustomer(customer: SdkGardenCustomer | null): void;
     /**
      * Send every queued event now. Resolves once they (and any requests already
      * in flight) have finished, or after `timeoutMs` (default 2000), whichever
@@ -114,4 +140,4 @@ interface SdkGardenObject {
  */
 declare const SdkGarden: SdkGardenObject;
 
-export { type SdkGardenConfig, type SdkMethodDecorator, SdkGarden as default };
+export { type SdkGardenConfig, type SdkGardenCustomer, type SdkMethodDecorator, SdkGarden as default };

package/dist/index.js

@@ -26,6 +26,7 @@ module.exports = __toCommonJS(index_exports);
 var _config = null;
 var _queue = [];
 var _sessionId = "";
+var _customer = null;
 var _flushTimer = null;
 var _exiting = false;
 var _exitDrains = 0;
@@ -37,6 +38,9 @@ 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;
@@ -46,6 +50,8 @@ 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;
@@ -55,6 +61,9 @@ 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)));
@@ -115,6 +124,29 @@ function _getMetadata() {
   return meta;
 }
 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++) {
@@ -208,6 +240,7 @@ function _enqueue(event) {
     _log("Queue full; dropped event", event.event);
     return;
   }
+  if (_customer) event.customer = _customer;
   let json;
   try {
     json = JSON.stringify(event);
@@ -305,6 +338,37 @@ function _createWrapper(methodName, fn) {
   });
   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) => {
@@ -586,6 +650,7 @@ function _teardown() {
   _config = null;
   _queue = [];
   _sessionId = "";
+  _customer = null;
   _endExit();
 }
 function _start(config) {
@@ -607,6 +672,12 @@ function _start(config) {
   _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",
@@ -615,7 +686,8 @@ function _start(config) {
     timestamp: Date.now(),
     properties: {
       environment: _getEnvironment(),
-      time_to_init_ms: Math.max(0, Date.now() - initStartedAt)
+      time_to_init_ms: Math.max(0, Date.now() - initStartedAt),
+      ...apiSurface.length > 0 ? { api_surface: apiSurface } : {}
     },
     meta: _getMetadata()
   });
@@ -678,6 +750,7 @@ var SdkGarden = {
    * ```
    */
   trackMethod(methodName, fn) {
+    _safely(() => _register(methodName));
     if (fn !== void 0) {
       return _createWrapper(methodName, fn);
     }
@@ -712,6 +785,25 @@ var SdkGarden = {
       })
     );
   },
+  /**
+   * 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);
+    });
+  },
   /**
    * Send every queued event now and wait for the requests to finish.
    * Useful at the end of a serverless handler or a test.
@@ -746,12 +838,14 @@ var SdkGarden = {
   /**
    * Reset all internal state.
    * FOR UNIT TESTS ONLY — not documented in README.
-   * Clears queue, config, session ID, flush timer, listeners and the record
-   * of requests in flight, without sending or cancelling anything.
+   * Clears queue, config, session ID, flush timer, listeners, registered
+   * method names and the record of requests in flight, without sending or cancelling anything.
    */
   _reset() {
     _teardown();
     _pending.clear();
+    _registered.clear();
+    _undeclared = [];
   }
 };
 var index_default = SdkGarden;

package/dist/index.mjs

@@ -2,6 +2,7 @@
 var _config = null;
 var _queue = [];
 var _sessionId = "";
+var _customer = null;
 var _flushTimer = null;
 var _exiting = false;
 var _exitDrains = 0;
@@ -13,6 +14,9 @@ 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;
@@ -22,6 +26,8 @@ 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;
@@ -31,6 +37,9 @@ 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)));
@@ -91,6 +100,29 @@ function _getMetadata() {
   return meta;
 }
 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++) {
@@ -184,6 +216,7 @@ function _enqueue(event) {
     _log("Queue full; dropped event", event.event);
     return;
   }
+  if (_customer) event.customer = _customer;
   let json;
   try {
     json = JSON.stringify(event);
@@ -281,6 +314,37 @@ function _createWrapper(methodName, fn) {
   });
   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) => {
@@ -562,6 +626,7 @@ function _teardown() {
   _config = null;
   _queue = [];
   _sessionId = "";
+  _customer = null;
   _endExit();
 }
 function _start(config) {
@@ -583,6 +648,12 @@ function _start(config) {
   _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",
@@ -591,7 +662,8 @@ function _start(config) {
     timestamp: Date.now(),
     properties: {
       environment: _getEnvironment(),
-      time_to_init_ms: Math.max(0, Date.now() - initStartedAt)
+      time_to_init_ms: Math.max(0, Date.now() - initStartedAt),
+      ...apiSurface.length > 0 ? { api_surface: apiSurface } : {}
     },
     meta: _getMetadata()
   });
@@ -654,6 +726,7 @@ var SdkGarden = {
    * ```
    */
   trackMethod(methodName, fn) {
+    _safely(() => _register(methodName));
     if (fn !== void 0) {
       return _createWrapper(methodName, fn);
     }
@@ -688,6 +761,25 @@ var SdkGarden = {
       })
     );
   },
+  /**
+   * 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);
+    });
+  },
   /**
    * Send every queued event now and wait for the requests to finish.
    * Useful at the end of a serverless handler or a test.
@@ -722,12 +814,14 @@ var SdkGarden = {
   /**
    * Reset all internal state.
    * FOR UNIT TESTS ONLY — not documented in README.
-   * Clears queue, config, session ID, flush timer, listeners and the record
-   * of requests in flight, without sending or cancelling anything.
+   * Clears queue, config, session ID, flush timer, listeners, registered
+   * method names and the record of requests in flight, without sending or cancelling anything.
    */
   _reset() {
     _teardown();
     _pending.clear();
+    _registered.clear();
+    _undeclared = [];
   }
 };
 var index_default = SdkGarden;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdk-garden-js",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Lightweight SDK observability client for JavaScript/TypeScript \u2014 zero runtime dependencies",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",