sdk-garden-js 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# sdk-garden-js
+*Lightweight SDK observability client for JavaScript and TypeScript*
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## Install
+
+```bash
+npm install sdk-garden-js
+```
+
+## Quick Start
+
+**ESM (TypeScript / modern bundlers):**
+
+```typescript
+import SdkGarden from 'sdk-garden-js';
+
+SdkGarden.init({
+  apiKey: 'YOUR_API_KEY',
+  sdkName: 'my-sdk',
+  sdkVersion: '1.0.0',
+});
+
+// Decorator form — annotate class methods directly:
+class PaymentsSDK {
+  @SdkGarden.trackMethod('processPayment')
+  processPayment(amount: number, currency: string): Receipt {
+    // your implementation
+  }
+}
+
+// Wrapper form — wrap standalone functions:
+export const trackedProcess = SdkGarden.trackMethod('processPayment', processPayment);
+```
+
+**CommonJS (Node.js / require):**
+
+```javascript
+const SdkGarden = require('sdk-garden-js');
+
+SdkGarden.init({
+  apiKey: 'YOUR_API_KEY',
+  sdkName: 'my-sdk',
+  sdkVersion: '1.0.0',
+});
+```
+
+## Configuration
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `apiKey` | `string` | _(required)_ | Your SDK Garden API key (starts with `sgk_`) |
+| `sdkName` | `string` | _(required)_ | The name of your SDK (e.g. `"my-payments-sdk"`) |
+| `sdkVersion` | `string` | _(required)_ | The version of your SDK (e.g. `"1.2.3"`) |
+| `endpoint` | `string` | `"https://ingest.sdkgarden.dev/track"` | Override the ingest endpoint |
+| `debug` | `boolean` | `false` | Enable debug logging to console |
+| `disabled` | `boolean` | `false` | When `true`, all methods become no-ops |
+| `batchSize` | `number` | `10` | Maximum events per flush batch |
+| `flushInterval` | `number` | `5000` | Flush interval in milliseconds |
+| `startedAt` | `number` | module load time | `Date.now()` when your SDK began initializing; reported as `time_to_init_ms` for the dashboard's init timing |
+
+## 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`.
+- **`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.
+- **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, stack traces, or user identifiers. Nothing is sent when `disabled: true`.
+
+### Telling your users
+
+Copy this into your SDK's README or privacy docs so your users know what's collected (edit the names to match):
+
+> **Telemetry.** This SDK reports anonymous usage data to its maintainers through [SDK Garden](https://github.com/tjb/SDKGarden): the SDK version, runtime version, which SDK methods are called, how long they take, and error types. It never sends your data, request contents or personal information. To opt out, set `YOUR_SDK_TELEMETRY_DISABLED=1` *(wire this environment variable to `disabled: true` in your SDK)*.
+
+## Silent Failure Guarantee
+
+All network errors are swallowed silently. SDK Garden will never throw or reject in your caller's context.
+
+Pass `disabled: true` in test environments to suppress all network calls.
+
+## Known Limitations
+
+### Async fire-and-forget calls (wrapper form only)
+
+When using the **wrapper form**, `trackMethod` records `method_success` only when the caller `await`s or chains `.then()` on the returned promise. If the promise is discarded, `method_called` fires but `method_success` is never enqueued.
+
+**Affected pattern:**
+```typescript
+// method_called fires, but method_success is NEVER recorded:
+SdkGarden.trackMethod('notify', notify)(...args); // promise discarded
+```
+
+**Not affected:**
+```typescript
+// Both events recorded correctly:
+await SdkGarden.trackMethod('notify', notify)(...args);
+```
+
+The **decorator form** does not have this limitation — class method decorators always capture the returned promise correctly regardless of how the caller uses it. Synchronous functions are not affected in either form.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,92 @@
+/**
+ * sdk-garden-js — Lightweight SDK observability client for JavaScript and TypeScript.
+ *
+ * Drop-in singleton for SDK publishers to instrument their own SDKs with
+ * initialization, method call, and error telemetry.
+ *
+ * Security:
+ *  - API key is never logged raw (see _sanitizeConfig).
+ *  - Error messages are PII-scrubbed (email addresses redacted) before enqueueing.
+ *  - All network errors in _flush() are swallowed silently — never propagated to callers.
+ */
+/** Configuration for SdkGarden.init(). */
+interface SdkGardenConfig {
+    /** Your SDK Garden API key (starts with sgk_). */
+    apiKey: string;
+    /** The name of your SDK (e.g. "my-payments-sdk"). */
+    sdkName: string;
+    /** The version of your SDK (e.g. "1.2.3"). */
+    sdkVersion: string;
+    /** Override the default ingest endpoint. Default: https://ingest.sdkgarden.dev/track */
+    endpoint?: string;
+    /** Enable debug logging to console. Default: false */
+    debug?: boolean;
+    /** When true, all methods become no-ops — no events, no network calls. Default: false */
+    disabled?: boolean;
+    /** Maximum events per flush batch. Default: 10 */
+    batchSize?: number;
+    /** Flush interval in milliseconds. Default: 5000 */
+    flushInterval?: number;
+    /**
+     * When your SDK started initializing, as a `Date.now()` timestamp. Used for
+     * the dashboard's init-timing panel (`time_to_init_ms` = init() time minus
+     * this). Capture it at the top of your SDK's constructor or setup function.
+     * Default: when sdk-garden-js was first loaded.
+     */
+    startedAt?: number;
+}
+/**
+ * Stage 3 class method decorator returned by SdkGarden.trackMethod(name).
+ *
+ * @example
+ * class MySDK {
+ *   \@SdkGarden.trackMethod('processPayment')
+ *   processPayment(amount: number): Receipt { ... }
+ * }
+ */
+type SdkMethodDecorator = <This, Args extends unknown[], Return>(fn: (this: This, ...args: Args) => Return, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>) => (this: This, ...args: Args) => Return;
+/**
+ * Fire-and-forget flush to the ingest endpoint.
+ * Ported from sdk/sdk-garden.js lines 232–270, simplified per plan:
+ *   - No retry on 429 (v1)
+ *   - No re-queue on failure (events are discarded)
+ *   - Silent failure: catch() swallows all errors
+ *
+ * NOTE: _flush() is also exposed on the SdkGarden object for test access.
+ */
+declare function _flush(): void;
+/**
+ * Typed interface for the SdkGarden singleton.
+ * Declared separately so that trackMethod can have proper overload signatures —
+ * TypeScript does not support method overloads inside object literals.
+ */
+interface SdkGardenObject {
+    init(config: SdkGardenConfig): void;
+    track(eventName: string, properties?: Record<string, unknown>): void;
+    /** Decorator form — use as @SdkGarden.trackMethod('name') on a class method. */
+    trackMethod(methodName: string): SdkMethodDecorator;
+    /** Wrapper form — pass an existing function, receive the instrumented version. */
+    trackMethod<T extends (...args: unknown[]) => unknown>(methodName: string, fn: T): T;
+    trackError(error: Error, context?: Record<string, unknown>): void;
+    _flush: typeof _flush;
+    _reset(): void;
+}
+/**
+ * SdkGarden — singleton SDK observability client.
+ *
+ * @example
+ * import SdkGarden from 'sdk-garden-js';
+ * SdkGarden.init({ apiKey: 'sgk_...', sdkName: 'my-sdk', sdkVersion: '1.0.0' });
+ *
+ * // Decorator form (class methods):
+ * class MySDK {
+ *   \@SdkGarden.trackMethod('processPayment')
+ *   processPayment(amount: number): Receipt { ... }
+ * }
+ *
+ * // Wrapper form (standalone functions):
+ * const tracked = SdkGarden.trackMethod('processPayment', processPayment);
+ */
+declare const SdkGarden: SdkGardenObject;
+
+export { type SdkGardenConfig, type SdkMethodDecorator, SdkGarden as default };

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+/**
+ * sdk-garden-js — Lightweight SDK observability client for JavaScript and TypeScript.
+ *
+ * Drop-in singleton for SDK publishers to instrument their own SDKs with
+ * initialization, method call, and error telemetry.
+ *
+ * Security:
+ *  - API key is never logged raw (see _sanitizeConfig).
+ *  - Error messages are PII-scrubbed (email addresses redacted) before enqueueing.
+ *  - All network errors in _flush() are swallowed silently — never propagated to callers.
+ */
+/** Configuration for SdkGarden.init(). */
+interface SdkGardenConfig {
+    /** Your SDK Garden API key (starts with sgk_). */
+    apiKey: string;
+    /** The name of your SDK (e.g. "my-payments-sdk"). */
+    sdkName: string;
+    /** The version of your SDK (e.g. "1.2.3"). */
+    sdkVersion: string;
+    /** Override the default ingest endpoint. Default: https://ingest.sdkgarden.dev/track */
+    endpoint?: string;
+    /** Enable debug logging to console. Default: false */
+    debug?: boolean;
+    /** When true, all methods become no-ops — no events, no network calls. Default: false */
+    disabled?: boolean;
+    /** Maximum events per flush batch. Default: 10 */
+    batchSize?: number;
+    /** Flush interval in milliseconds. Default: 5000 */
+    flushInterval?: number;
+    /**
+     * When your SDK started initializing, as a `Date.now()` timestamp. Used for
+     * the dashboard's init-timing panel (`time_to_init_ms` = init() time minus
+     * this). Capture it at the top of your SDK's constructor or setup function.
+     * Default: when sdk-garden-js was first loaded.
+     */
+    startedAt?: number;
+}
+/**
+ * Stage 3 class method decorator returned by SdkGarden.trackMethod(name).
+ *
+ * @example
+ * class MySDK {
+ *   \@SdkGarden.trackMethod('processPayment')
+ *   processPayment(amount: number): Receipt { ... }
+ * }
+ */
+type SdkMethodDecorator = <This, Args extends unknown[], Return>(fn: (this: This, ...args: Args) => Return, context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>) => (this: This, ...args: Args) => Return;
+/**
+ * Fire-and-forget flush to the ingest endpoint.
+ * Ported from sdk/sdk-garden.js lines 232–270, simplified per plan:
+ *   - No retry on 429 (v1)
+ *   - No re-queue on failure (events are discarded)
+ *   - Silent failure: catch() swallows all errors
+ *
+ * NOTE: _flush() is also exposed on the SdkGarden object for test access.
+ */
+declare function _flush(): void;
+/**
+ * Typed interface for the SdkGarden singleton.
+ * Declared separately so that trackMethod can have proper overload signatures —
+ * TypeScript does not support method overloads inside object literals.
+ */
+interface SdkGardenObject {
+    init(config: SdkGardenConfig): void;
+    track(eventName: string, properties?: Record<string, unknown>): void;
+    /** Decorator form — use as @SdkGarden.trackMethod('name') on a class method. */
+    trackMethod(methodName: string): SdkMethodDecorator;
+    /** Wrapper form — pass an existing function, receive the instrumented version. */
+    trackMethod<T extends (...args: unknown[]) => unknown>(methodName: string, fn: T): T;
+    trackError(error: Error, context?: Record<string, unknown>): void;
+    _flush: typeof _flush;
+    _reset(): void;
+}
+/**
+ * SdkGarden — singleton SDK observability client.
+ *
+ * @example
+ * import SdkGarden from 'sdk-garden-js';
+ * SdkGarden.init({ apiKey: 'sgk_...', sdkName: 'my-sdk', sdkVersion: '1.0.0' });
+ *
+ * // Decorator form (class methods):
+ * class MySDK {
+ *   \@SdkGarden.trackMethod('processPayment')
+ *   processPayment(amount: number): Receipt { ... }
+ * }
+ *
+ * // Wrapper form (standalone functions):
+ * const tracked = SdkGarden.trackMethod('processPayment', processPayment);
+ */
+declare const SdkGarden: SdkGardenObject;
+
+export { type SdkGardenConfig, type SdkMethodDecorator, SdkGarden as default };

package/dist/index.js

@@ -0,0 +1,294 @@
+"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, {
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var _config = null;
+var _queue = [];
+var _sessionId = "";
+var _flushTimer = null;
+var _unloadHandler = null;
+var DEFAULT_ENDPOINT = "https://ingest.sdkgarden.dev/track";
+var MODULE_LOADED_AT = Date.now();
+function _mergeDefaults(config) {
+  var _a, _b, _c, _d, _e;
+  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
+  };
+}
+function _generateSessionId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
+function _getEnvironment() {
+  var _a, _b, _c, _d;
+  if (typeof window === "undefined") {
+    const nodeVersion = typeof process !== "undefined" ? (_a = process.versions) == null ? void 0 : _a.node : void 0;
+    return nodeVersion ? { runtime: "node", runtime_version: nodeVersion } : { runtime: "node" };
+  }
+  const w = window;
+  return {
+    runtime: "browser",
+    screen_width: (_b = w.screen) == null ? void 0 : _b.width,
+    screen_height: (_c = w.screen) == null ? void 0 : _c.height,
+    viewport_width: w.innerWidth,
+    viewport_height: w.innerHeight,
+    color_depth: (_d = w.screen) == null ? void 0 : _d.colorDepth,
+    pixel_ratio: w.devicePixelRatio,
+    timezone: typeof Intl !== "undefined" ? Intl.DateTimeFormat().resolvedOptions().timeZone : void 0,
+    language: typeof navigator !== "undefined" ? navigator.language : void 0
+  };
+}
+function _getMetadata() {
+  var _a;
+  const meta = {};
+  if (typeof window !== "undefined") {
+    const origin = (_a = window.location) == null ? void 0 : _a.origin;
+    if (origin && origin !== "null") {
+      meta["url"] = origin;
+    }
+  }
+  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]"
+  );
+}
+function _sanitizeConfig(config) {
+  const sanitized = { ...config };
+  const sensitiveKeys = ["apiKey", "api_key", "secret", "password", "token"];
+  for (const key of Object.keys(sanitized)) {
+    if (sensitiveKeys.some((sk) => key.toLowerCase().includes(sk))) {
+      sanitized[key] = "***REDACTED***";
+    }
+  }
+  return sanitized;
+}
+function _log(...args) {
+  if (_config == null ? void 0 : _config.debug) {
+    console.log("[SDK Garden]", ...args);
+  }
+}
+function _enqueue(event) {
+  _queue.push(event);
+  _log("Event tracked", event.event);
+  if (_config && _queue.length >= _config.batchSize) {
+    _flush();
+  }
+}
+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;
+    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;
+    }
+    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;
+      });
+    }
+    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
+    });
+    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(() => {
+  });
+}
+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.
+   */
+  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);
+    }
+  },
+  /**
+   * Track a custom event.
+   * 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()
+    });
+  },
+  /**
+   * Instrument a method with call, success, and error telemetry.
+   *
+   * **Two-argument form** — wraps a standalone function:
+   * ```ts
+   * function processPayment(amount: number): Receipt { ... }
+   * export const trackedProcessPayment = SdkGarden.trackMethod('processPayment', processPayment);
+   * ```
+   *
+   * **One-argument form** — Stage 3 class method decorator:
+   * ```ts
+   * class MySDK {
+   *   \@SdkGarden.trackMethod('processPayment')
+   *   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) {
+    if (fn !== void 0) {
+      if (!_config || _config.disabled) return fn;
+      return _createWrapper(methodName, fn);
+    }
+    return function(target, _context) {
+      return _createWrapper(methodName, target);
+    };
+  },
+  /**
+   * Track an error event.
+   * Applies PII scrubbing to error.message before enqueueing.
+   * 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()
+    });
+  },
+  /**
+   * Manually trigger a flush of queued events.
+   * Useful in beforeunload handlers or at process exit.
+   */
+  _flush,
+  /**
+   * Reset all internal state.
+   * FOR UNIT TESTS ONLY — not documented in README.
+   * Clears queue, config, session ID, and flush timer.
+   */
+  _reset() {
+    if (_flushTimer !== null) {
+      clearInterval(_flushTimer);
+      _flushTimer = null;
+    }
+    if (typeof window !== "undefined" && _unloadHandler) {
+      window.removeEventListener("beforeunload", _unloadHandler);
+      _unloadHandler = null;
+    }
+    _config = null;
+    _queue = [];
+    _sessionId = "";
+  }
+};
+var index_default = SdkGarden;

package/dist/index.mjs

@@ -0,0 +1,273 @@
+// src/index.ts
+var _config = null;
+var _queue = [];
+var _sessionId = "";
+var _flushTimer = null;
+var _unloadHandler = null;
+var DEFAULT_ENDPOINT = "https://ingest.sdkgarden.dev/track";
+var MODULE_LOADED_AT = Date.now();
+function _mergeDefaults(config) {
+  var _a, _b, _c, _d, _e;
+  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
+  };
+}
+function _generateSessionId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
+function _getEnvironment() {
+  var _a, _b, _c, _d;
+  if (typeof window === "undefined") {
+    const nodeVersion = typeof process !== "undefined" ? (_a = process.versions) == null ? void 0 : _a.node : void 0;
+    return nodeVersion ? { runtime: "node", runtime_version: nodeVersion } : { runtime: "node" };
+  }
+  const w = window;
+  return {
+    runtime: "browser",
+    screen_width: (_b = w.screen) == null ? void 0 : _b.width,
+    screen_height: (_c = w.screen) == null ? void 0 : _c.height,
+    viewport_width: w.innerWidth,
+    viewport_height: w.innerHeight,
+    color_depth: (_d = w.screen) == null ? void 0 : _d.colorDepth,
+    pixel_ratio: w.devicePixelRatio,
+    timezone: typeof Intl !== "undefined" ? Intl.DateTimeFormat().resolvedOptions().timeZone : void 0,
+    language: typeof navigator !== "undefined" ? navigator.language : void 0
+  };
+}
+function _getMetadata() {
+  var _a;
+  const meta = {};
+  if (typeof window !== "undefined") {
+    const origin = (_a = window.location) == null ? void 0 : _a.origin;
+    if (origin && origin !== "null") {
+      meta["url"] = origin;
+    }
+  }
+  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]"
+  );
+}
+function _sanitizeConfig(config) {
+  const sanitized = { ...config };
+  const sensitiveKeys = ["apiKey", "api_key", "secret", "password", "token"];
+  for (const key of Object.keys(sanitized)) {
+    if (sensitiveKeys.some((sk) => key.toLowerCase().includes(sk))) {
+      sanitized[key] = "***REDACTED***";
+    }
+  }
+  return sanitized;
+}
+function _log(...args) {
+  if (_config == null ? void 0 : _config.debug) {
+    console.log("[SDK Garden]", ...args);
+  }
+}
+function _enqueue(event) {
+  _queue.push(event);
+  _log("Event tracked", event.event);
+  if (_config && _queue.length >= _config.batchSize) {
+    _flush();
+  }
+}
+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;
+    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;
+    }
+    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;
+      });
+    }
+    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
+    });
+    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(() => {
+  });
+}
+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.
+   */
+  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);
+    }
+  },
+  /**
+   * Track a custom event.
+   * 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()
+    });
+  },
+  /**
+   * Instrument a method with call, success, and error telemetry.
+   *
+   * **Two-argument form** — wraps a standalone function:
+   * ```ts
+   * function processPayment(amount: number): Receipt { ... }
+   * export const trackedProcessPayment = SdkGarden.trackMethod('processPayment', processPayment);
+   * ```
+   *
+   * **One-argument form** — Stage 3 class method decorator:
+   * ```ts
+   * class MySDK {
+   *   \@SdkGarden.trackMethod('processPayment')
+   *   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) {
+    if (fn !== void 0) {
+      if (!_config || _config.disabled) return fn;
+      return _createWrapper(methodName, fn);
+    }
+    return function(target, _context) {
+      return _createWrapper(methodName, target);
+    };
+  },
+  /**
+   * Track an error event.
+   * Applies PII scrubbing to error.message before enqueueing.
+   * 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()
+    });
+  },
+  /**
+   * Manually trigger a flush of queued events.
+   * Useful in beforeunload handlers or at process exit.
+   */
+  _flush,
+  /**
+   * Reset all internal state.
+   * FOR UNIT TESTS ONLY — not documented in README.
+   * Clears queue, config, session ID, and flush timer.
+   */
+  _reset() {
+    if (_flushTimer !== null) {
+      clearInterval(_flushTimer);
+      _flushTimer = null;
+    }
+    if (typeof window !== "undefined" && _unloadHandler) {
+      window.removeEventListener("beforeunload", _unloadHandler);
+      _unloadHandler = null;
+    }
+    _config = null;
+    _queue = [];
+    _sessionId = "";
+  }
+};
+var index_default = SdkGarden;
+export {
+  index_default as default
+};

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "sdk-garden-js",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Lightweight SDK observability client for JavaScript/TypeScript \u2014 zero runtime dependencies",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": true,
+  "license": "MIT",
+  "homepage": "https://sdkgarden.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tjb/SDKGarden.git",
+    "directory": "sdk/sdk-garden-js"
+  },
+  "bugs": {
+    "url": "https://github.com/tjb/SDKGarden/issues"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "jest",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "jest": "^29.7.0",
+    "jest-environment-node": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.2"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "testMatch": [
+      "**/__tests__/**/*.test.ts"
+    ]
+  }
+}