sdk-garden-js 0.1.0 → 0.1.1

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,11 +55,11 @@ 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 |
 
 ## What gets sent
@@ -67,39 +71,45 @@ Each event carries your SDK's name and version, an event type, a random session
 - **`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`.
+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)*.
-
-## Silent Failure Guarantee
-
-All network errors are swallowed silently. SDK Garden will never throw or reject in your caller's context.
+> **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)*.
 
-Pass `disabled: true` in test environments to suppress all network calls.
+## Sending and shutting down
 
-## Known Limitations
+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:
 
-### Async fire-and-forget calls (wrapper form only)
+- **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.
 
-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.
+Two methods let you control this yourself. Both return promises that never reject:
 
-**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
@@ -36,7 +48,8 @@ interface SdkGardenConfig {
     startedAt?: number;
 }
 /**
- * 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 +57,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 +72,25 @@ 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;
+    /**
+     * 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,8 +106,11 @@ 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;
 

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
@@ -36,7 +48,8 @@ interface SdkGardenConfig {
     startedAt?: number;
 }
 /**
- * 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 +57,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 +72,25 @@ 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;
+    /**
+     * 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,8 +106,11 @@ 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;