sdk-garden-js 0.1.0 → 0.2.0

package/README.md

@@ -32,6 +32,8 @@ class PaymentsSDK {
 export const trackedProcess = SdkGarden.trackMethod('processPayment', processPayment);
 ```
 
+Both forms can run before `init()`, for example at module level: calls pass straight through until `init()` runs and are recorded from then on.
+
 **CommonJS (Node.js / require):**
 
 ```javascript
@@ -44,6 +46,8 @@ SdkGarden.init({
 });
 ```
 
+Requires Node.js 18+ (for the global `fetch`) or any modern browser.
+
 ## Configuration
 
 | Parameter | Type | Default | Description |
@@ -51,55 +55,82 @@ SdkGarden.init({
 | `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 |
+| `endpoint` | `string` | `"https://ingest.sdkgarden.com/track"` | Override the ingest endpoint (for self-hosted SDK Garden, `https://<your-host>/track`) |
 | `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 |
+| `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, stack traces, or user identifiers. Nothing is sent when `disabled: true`.
+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`.
 
 ### 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)*.
+> **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 the type and message of the errors they raise (with email addresses removed). It never sends arguments, return values or request contents. To opt out, set `YOUR_SDK_TELEMETRY_DISABLED=1` *(wire this environment variable to `disabled: true` in your SDK)*.
 
-## Silent Failure Guarantee
+## Sending and shutting down
 
-All network errors are swallowed silently. SDK Garden will never throw or reject in your caller's context.
+Routine sends go out one request at a time: every `flushInterval` milliseconds, or as soon as `batchSize` events are queued. At most 1,000 events wait to be sent; if the endpoint cannot keep up, newer events are dropped. Events are also sent:
 
-Pass `disabled: true` in test environments to suppress all network calls.
+- **When a Node.js process runs out of work.** The client never keeps a process alive on its own. When your program finishes, the events still queued are sent before it exits, including any your own `beforeExit` handler tracks. In Node.js a request times out after 2 seconds, so an endpoint that does not answer delays exit by about 2 seconds (about 4 if a request was already running) but never keeps the process running. Only a DNS server that never answers can hold it longer, up to the system's DNS timeout.
+- **When a page is hidden or unloaded**, in browsers, using `keepalive` so the request can outlive the page.
 
-## Known Limitations
+Two methods let you control this yourself. Both return promises that never reject:
 
-### 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
-```
+// Send everything queued now and wait for it (at most 2 s by default), e.g. at the end of a serverless handler.
+await SdkGarden.flush();
 
-**Not affected:**
-```typescript
-// Both events recorded correctly:
-await SdkGarden.trackMethod('notify', notify)(...args);
+// Send everything queued, then stop the client: no timer, no listeners, and tracking calls do nothing
+// until init() runs again. Requests still running after 2 s (by default) are abandoned.
+await SdkGarden.shutdown();
 ```
 
-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.
+The automatic send does not run when the process ends through `process.exit()` or a signal such as Ctrl-C. If your SDK has a `close()` method or your users' code exits explicitly, `await SdkGarden.shutdown()` first.
+
+Serverless functions and edge workers can be frozen as soon as a handler returns, so `await SdkGarden.flush()` before returning (in Cloudflare Workers, pass it to `ctx.waitUntil()`).
+
+If a `beforeExit` handler of yours starts more work, such as the next job in a queue, `await SdkGarden.flush()` at the end of each job. While a process exits, the client sends only three times from `beforeExit`, so that a handler that tracks or flushes every time cannot keep the process alive; a `flush()` anywhere else always sends.
+
+## Silent Failure Guarantee
+
+All network errors are swallowed silently. SDK Garden will never throw or reject in your caller's context (not even `init()`), and `trackMethod` never changes what your function returns or throws. Wrapped functions always return exactly what the original returned. A native promise, also one from another realm such as a `vm` context, is watched until it settles (so a rejection nothing else handles is no longer reported as unhandled); Promise subclasses, such as an API client's response promise, and other thenables, such as lazy query builders, are never touched.
+
+`sdk-garden-js` is one client per process: if two SDKs in the same app share an installed copy, the last `init()` wins for both. Bundle it into your SDK's build to give your SDK its own copy.
+
+Pass `disabled: true` in test environments to suppress all network calls.
 
 ## License
 

package/dist/index.d.mts

@@ -7,7 +7,19 @@
  * 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.
+ *  - All network errors are swallowed silently — never propagated to callers.
+ *
+ * Lifecycle:
+ *  - Routine sends go out one request at a time and at most MAX_QUEUE_SIZE
+ *    events wait, so a burst of events cannot flood the host's network or the
+ *    endpoint. flush() and the sends at exit or page hide send up to
+ *    MAX_DRAIN_REQUESTS requests at once; shutdown() sends everything queued.
+ *  - Timers are unref'd, so the client never keeps a Node process alive.
+ *  - Queued events are sent when a Node process runs out of work (beforeExit)
+ *    and when a page is hidden or unloaded (visibilitychange / pagehide).
+ *    While a Node process exits, sending is limited so that it still ends,
+ *    until the process shows that it carried on instead (see _checkExit).
+ *  - No method throws into the host, and flush() and shutdown() never reject.
  */
 /** Configuration for SdkGarden.init(). */
 interface SdkGardenConfig {
@@ -17,15 +29,15 @@ interface SdkGardenConfig {
     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 */
+    /** Override the default ingest endpoint. Default: https://ingest.sdkgarden.com/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 */
+    /** Maximum events per request, from 1 to 100; a full batch is sent right away. Default: 10 */
     batchSize?: number;
-    /** Flush interval in milliseconds. Default: 5000 */
+    /** Milliseconds between sends of whatever is queued, at least 100. Default: 5000 */
     flushInterval?: number;
     /**
      * When your SDK started initializing, as a `Date.now()` timestamp. Used for
@@ -34,9 +46,31 @@ 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;
 }
 /**
- * Stage 3 class method decorator returned by SdkGarden.trackMethod(name).
+ * Class method decorator returned by SdkGarden.trackMethod(name), for Stage 3
+ * decorators and for TypeScript's experimentalDecorators.
  *
  * @example
  * class MySDK {
@@ -44,17 +78,10 @@ interface SdkGardenConfig {
  *   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;
+interface 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;
+    <T>(target: object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>): TypedPropertyDescriptor<T>;
+}
 /**
  * Typed interface for the SdkGarden singleton.
  * Declared separately so that trackMethod can have proper overload signatures —
@@ -66,9 +93,30 @@ interface SdkGardenObject {
     /** 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;
+    trackMethod<T extends (...args: any[]) => any>(methodName: string, fn: T): T;
     trackError(error: Error, context?: Record<string, unknown>): void;
-    _flush: typeof _flush;
+    /**
+     * 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
+     * comes first. Never rejects.
+     */
+    flush(timeoutMs?: number): Promise<void>;
+    /**
+     * Send every queued event, then stop: no timer, no listeners, and tracking
+     * calls become no-ops until init() is called again. Resolves once the last
+     * requests finish; requests still running after `timeoutMs` (default 2000)
+     * are aborted so a Node process can exit. `0` stops at once without
+     * sending. Never rejects.
+     */
+    shutdown(timeoutMs?: number): Promise<void>;
+    /** @deprecated Use flush(), which returns a promise. Kept so 0.1.0 code keeps working. */
+    _flush(): void;
+    /** @internal For unit tests: drop all state without sending anything. */
     _reset(): void;
 }
 /**
@@ -84,9 +132,12 @@ interface SdkGardenObject {
  *   processPayment(amount: number): Receipt { ... }
  * }
  *
- * // Wrapper form (standalone functions):
- * const tracked = SdkGarden.trackMethod('processPayment', processPayment);
+ * // Wrapper form (standalone functions), safe to run before init():
+ * export const tracked = SdkGarden.trackMethod('processPayment', processPayment);
+ *
+ * // Before your SDK's host process exits (for example in your close()):
+ * await SdkGarden.shutdown();
  */
 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

@@ -7,7 +7,19 @@
  * 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.
+ *  - All network errors are swallowed silently — never propagated to callers.
+ *
+ * Lifecycle:
+ *  - Routine sends go out one request at a time and at most MAX_QUEUE_SIZE
+ *    events wait, so a burst of events cannot flood the host's network or the
+ *    endpoint. flush() and the sends at exit or page hide send up to
+ *    MAX_DRAIN_REQUESTS requests at once; shutdown() sends everything queued.
+ *  - Timers are unref'd, so the client never keeps a Node process alive.
+ *  - Queued events are sent when a Node process runs out of work (beforeExit)
+ *    and when a page is hidden or unloaded (visibilitychange / pagehide).
+ *    While a Node process exits, sending is limited so that it still ends,
+ *    until the process shows that it carried on instead (see _checkExit).
+ *  - No method throws into the host, and flush() and shutdown() never reject.
  */
 /** Configuration for SdkGarden.init(). */
 interface SdkGardenConfig {
@@ -17,15 +29,15 @@ interface SdkGardenConfig {
     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 */
+    /** Override the default ingest endpoint. Default: https://ingest.sdkgarden.com/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 */
+    /** Maximum events per request, from 1 to 100; a full batch is sent right away. Default: 10 */
     batchSize?: number;
-    /** Flush interval in milliseconds. Default: 5000 */
+    /** Milliseconds between sends of whatever is queued, at least 100. Default: 5000 */
     flushInterval?: number;
     /**
      * When your SDK started initializing, as a `Date.now()` timestamp. Used for
@@ -34,9 +46,31 @@ 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;
 }
 /**
- * Stage 3 class method decorator returned by SdkGarden.trackMethod(name).
+ * Class method decorator returned by SdkGarden.trackMethod(name), for Stage 3
+ * decorators and for TypeScript's experimentalDecorators.
  *
  * @example
  * class MySDK {
@@ -44,17 +78,10 @@ interface SdkGardenConfig {
  *   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;
+interface 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;
+    <T>(target: object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>): TypedPropertyDescriptor<T>;
+}
 /**
  * Typed interface for the SdkGarden singleton.
  * Declared separately so that trackMethod can have proper overload signatures —
@@ -66,9 +93,30 @@ interface SdkGardenObject {
     /** 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;
+    trackMethod<T extends (...args: any[]) => any>(methodName: string, fn: T): T;
     trackError(error: Error, context?: Record<string, unknown>): void;
-    _flush: typeof _flush;
+    /**
+     * 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
+     * comes first. Never rejects.
+     */
+    flush(timeoutMs?: number): Promise<void>;
+    /**
+     * Send every queued event, then stop: no timer, no listeners, and tracking
+     * calls become no-ops until init() is called again. Resolves once the last
+     * requests finish; requests still running after `timeoutMs` (default 2000)
+     * are aborted so a Node process can exit. `0` stops at once without
+     * sending. Never rejects.
+     */
+    shutdown(timeoutMs?: number): Promise<void>;
+    /** @deprecated Use flush(), which returns a promise. Kept so 0.1.0 code keeps working. */
+    _flush(): void;
+    /** @internal For unit tests: drop all state without sending anything. */
     _reset(): void;
 }
 /**
@@ -84,9 +132,12 @@ interface SdkGardenObject {
  *   processPayment(amount: number): Receipt { ... }
  * }
  *
- * // Wrapper form (standalone functions):
- * const tracked = SdkGarden.trackMethod('processPayment', processPayment);
+ * // Wrapper form (standalone functions), safe to run before init():
+ * export const tracked = SdkGarden.trackMethod('processPayment', processPayment);
+ *
+ * // Before your SDK's host process exits (for example in your close()):
+ * await SdkGarden.shutdown();
  */
 declare const SdkGarden: SdkGardenObject;
 
-export { type SdkGardenConfig, type SdkMethodDecorator, SdkGarden as default };
+export { type SdkGardenConfig, type SdkGardenCustomer, type SdkMethodDecorator, SdkGarden as default };