@stimpact/sdk 0.1.0 → 0.2.0

package/README.md

@@ -10,12 +10,29 @@ Browser runtimes should use either:
 - a custom `browserTokenEndpoint`
 - a custom `tokenProvider`
 
+## Capture contract
+
+Stimpact treats error capture as two complementary layers:
+
+- auto-capture for uncaught failures that escape to the runtime
+- handled-error capture for failures your app catches intentionally
+
+In practice that means:
+
+- browser runtimes should enable `registerBrowserAutoCapture()` for `window` errors and unhandled promise rejections
+- Node and other server runtimes should enable `registerProcessAutoCapture()` for uncaught exceptions and unhandled rejections
+- handled errors inside `catch` blocks, request wrappers, mutation handlers, and framework callbacks should use `captureHandledError()`, `wrap()`, or `wrapAsync()`
+- the SDK suppresses duplicate reporting for the same error object when a handled capture later reaches an auto-capture hook
+- SDK transport failures are never recursively auto-captured as application errors
+
 ## Install
 
 ```sh
 npm install @stimpact/sdk
 ```
 
+For package release validation and the prepublish checklist, see `PUBLISH_VALIDATION.md`.
+
 ## Server usage
 
 ```ts
@@ -29,10 +46,12 @@ const stimpact = new StimpactClient({
   environment: "production",
 });
 
+stimpact.registerProcessAutoCapture();
+
 try {
   await doWork();
 } catch (error) {
-  await stimpact.captureError({
+  await stimpact.captureHandledError({
     error,
     request: {
       method: "POST",
@@ -53,14 +72,51 @@ const stimpact = new StimpactClient({
   browserKey: "stimp_browser_...",
   service: "billing-web",
   environment: "production",
+  browserTokenFailureCooldownMs: 60_000,
 });
 
-stimpact.startHeartbeat();
+stimpact.startHeartbeat({
+  intervalMs: 300_000,
+  jitterRatio: 0.1,
+  skipWhenOffline: true,
+});
 stimpact.registerBrowserAutoCapture();
 ```
 
+When you use `browserKey`, configure at least one deployed app origin for that specific key during onboarding. Stimpact keeps CORS broadly compatible across active browser-key origins so browser preflights can succeed, but the actual security boundary is the browser key's `allowed_origins` check during token exchange plus the ingest token's origin binding.
+
+If you later revoke the key or remove an origin from its allowlist, new token exchanges from that origin fail and ingest re-checks the live browser-key record for defense in depth.
+
+The SDK also applies a cooldown after non-retryable browser token failures such as invalid, revoked, or origin-blocked browser keys so it does not hammer `/telemetry/browser-token` on every subsequent error event.
+
 For the strongest separation, use `browserTokenEndpoint` or `tokenProvider` so your app backend can mint short-lived ingest tokens without exposing any long-lived server credential to the browser.
 
+## Heartbeats and live status
+
+Use heartbeats as a lightweight "recently alive" signal, not a per-request health check.
+
+- `sendHeartbeat()` sends one manual heartbeat immediately.
+- `ping()` is an alias for `sendHeartbeat()` when you want a more explicit manual check-in call from UI code later.
+- `startHeartbeat()` schedules periodic heartbeats with jitter and optional browser-aware pause behavior.
+
+```ts
+const heartbeat = stimpact.startHeartbeat({
+  intervalMs: 5 * 60_000,
+  jitterRatio: 0.1,
+  skipWhenOffline: true,
+  pauseWhenHidden: false,
+});
+
+await stimpact.ping();
+
+// Manual dashboard-triggered check-in later:
+await heartbeat.triggerNow({ commitSha: window.__APP_COMMIT_SHA__ });
+```
+
+For frontend apps, heartbeat freshness means "a real browser session for this app has checked in recently." It does not guarantee the site is globally up for every visitor when no browser session is active.
+
+For server runtimes, heartbeats are a stronger liveness signal because they can run inside the long-lived process itself.
+
 ## Browser autocapture
 
 ```ts
@@ -70,6 +126,37 @@ const subscription = stimpact.registerBrowserAutoCapture();
 subscription.dispose();
 ```
 
+The SDK ignores its own transport errors during browser auto-capture so a failed telemetry request does not recursively report itself as another browser error.
+
+## Handled errors and framework integrations
+
+Use handled-error capture anywhere your app intentionally catches and renders the failure instead of letting it escape globally.
+
+```ts
+try {
+  await saveInvoice();
+} catch (error) {
+  await stimpact.captureHandledError({
+    error,
+    request: {
+      method: "POST",
+      url: "/api/invoices",
+    },
+  });
+  throw error;
+}
+```
+
+For synchronous code:
+
+```ts
+stimpact.wrap(() => {
+  performDangerousSynchronousWork();
+});
+```
+
+For async flows:
+
 ## Wrapped async flows
 
 ```ts
@@ -78,6 +165,29 @@ await stimpact.wrapAsync(async () => {
 });
 ```
 
+For framework-driven apps, instrument the shared boundary first instead of every component:
+
+- request wrappers such as `fetch` helpers or API clients
+- React Query / TanStack Query mutation and query defaults
+- framework error boundaries, loaders, and action handlers
+
+For example, a React Query mutation can capture the handled failure once in the shared `onError` path or request wrapper, then let the UI keep rendering the toast or retry state:
+
+```ts
+onError: async (error) => {
+  await stimpact.captureHandledError({
+    error,
+    request: {
+      method: "POST",
+      url: "/requests",
+    },
+  });
+  toast({ title: "Request failed" });
+}
+```
+
+Avoid capturing the same failure in both a shared request wrapper and a component-level `onError` unless they are intentionally distinct telemetry events.
+
 ## Data minimization defaults
 
 By default the SDK:

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { BrowserAutoCaptureOptions, BrowserCaptureSubscription, CaptureErrorInput, HeartbeatInput, HeartbeatSubscription, StimpactClientOptions } from "./types.js";
+import type { BrowserAutoCaptureOptions, BrowserCaptureSubscription, CaptureErrorInput, ErrorCaptureContext, HeartbeatInput, HeartbeatScheduleOptions, HeartbeatSubscription, ProcessAutoCaptureOptions, ProcessCaptureSubscription, StimpactClientOptions } from "./types.js";
 export declare class StimpactRequestError extends Error {
     status: number | null;
     retryable: boolean;
@@ -14,14 +14,24 @@ export declare class StimpactClient {
     private cachedBrowserToken;
     private cachedBrowserTokenExpiresAtMs;
     private browserTokenPromise;
+    private browserTokenFailure;
+    private browserTokenFailureBlockedUntilMs;
+    private readonly inFlightErrors;
+    private readonly reportedErrors;
     constructor(options: StimpactClientOptions);
     captureError(input: CaptureErrorInput): Promise<void>;
+    captureHandledError(input: CaptureErrorInput): Promise<void>;
     sendHeartbeat(input?: HeartbeatInput): Promise<void>;
-    startHeartbeat(options?: HeartbeatInput & {
-        intervalMs?: number;
-    }): HeartbeatSubscription;
-    wrapAsync<T>(operation: () => Promise<T>, context?: Omit<CaptureErrorInput, "error">): Promise<T>;
+    ping(input?: HeartbeatInput): Promise<void>;
+    wrap<T>(operation: () => T, context?: ErrorCaptureContext): T;
+    wrapAsync<T>(operation: () => Promise<T>, context?: ErrorCaptureContext): Promise<T>;
+    registerProcessAutoCapture(options?: ProcessAutoCaptureOptions): ProcessCaptureSubscription;
+    private captureWithState;
+    startHeartbeat(options?: HeartbeatScheduleOptions): HeartbeatSubscription;
     registerBrowserAutoCapture(options?: BrowserAutoCaptureOptions): BrowserCaptureSubscription;
+    private shouldIgnoreAutoCapturedError;
+    private captureSyncFailure;
+    private attachCaptureFailure;
     private sendTelemetry;
     private sendHeartbeatPayload;
     private sendTelemetryOnce;
@@ -30,4 +40,5 @@ export declare class StimpactClient {
     private getBrowserToken;
     private fetchBrowserToken;
     private performJsonRequest;
+    private rememberBrowserTokenFailure;
 }

package/dist/client.js

@@ -6,6 +6,8 @@ const DEFAULT_REDACTED_HEADERS = new Set([
     "x-api-key",
     "x-stimpact-project-key",
 ]);
+const CAPTURE_IN_FLIGHT = Symbol("stimpact.captureInFlight");
+const CAPTURE_REPORTED = Symbol("stimpact.captureReported");
 export class StimpactRequestError extends Error {
     status;
     retryable;
@@ -23,6 +25,10 @@ export class StimpactClient {
     cachedBrowserToken = null;
     cachedBrowserTokenExpiresAtMs = 0;
     browserTokenPromise = null;
+    browserTokenFailure = null;
+    browserTokenFailureBlockedUntilMs = 0;
+    inFlightErrors = new WeakSet();
+    reportedErrors = new WeakSet();
     constructor(options) {
         if (!options.apiKey && !options.browserKey && !options.browserTokenEndpoint && !options.tokenProvider) {
             throw new Error("StimpactClient requires apiKey, browserKey, browserTokenEndpoint, or tokenProvider.");
@@ -36,6 +42,7 @@ export class StimpactClient {
             timeoutMs: options.timeoutMs ?? 5_000,
             retryAttempts: options.retryAttempts ?? 2,
             retryDelayMs: options.retryDelayMs ?? 250,
+            browserTokenFailureCooldownMs: options.browserTokenFailureCooldownMs ?? 60_000,
             captureRequestContext: options.captureRequestContext ?? false,
             captureResponseContext: options.captureResponseContext ?? false,
             includeBodies: options.includeBodies ?? false,
@@ -44,23 +51,10 @@ export class StimpactClient {
         };
     }
     async captureError(input) {
-        const normalized = normalizeError(input.error, this.options.maxValueLength);
-        const payload = {
-            project_id: this.options.projectId,
-            environment: input.environment ?? this.options.environment ?? "production",
-            service: input.service ?? this.options.service,
-            error_message: normalized.message,
-            stacktrace: normalized.stacktrace,
-            request: this.options.captureRequestContext
-                ? sanitizeRequestContext(input.request, this.options)
-                : undefined,
-            response: this.options.captureResponseContext
-                ? sanitizeResponseContext(input.response, this.options)
-                : undefined,
-            commit_sha: input.commitSha ?? null,
-            timestamp: normalizeTimestamp(input.timestamp),
-        };
-        await this.sendTelemetry(payload);
+        await this.captureWithState(input);
+    }
+    async captureHandledError(input) {
+        await this.captureWithState(input);
     }
     async sendHeartbeat(input = {}) {
         const payload = {
@@ -72,22 +66,17 @@ export class StimpactClient {
         };
         await this.sendHeartbeatPayload(payload);
     }
-    startHeartbeat(options = {}) {
-        const intervalMs = options.intervalMs ?? 300_000;
-        let intervalId = null;
-        void this.sendHeartbeat(options);
-        if (typeof setInterval !== "undefined") {
-            intervalId = setInterval(() => {
-                void this.sendHeartbeat(options);
-            }, intervalMs);
+    async ping(input = {}) {
+        await this.sendHeartbeat(input);
+    }
+    wrap(operation, context) {
+        try {
+            return operation();
+        }
+        catch (error) {
+            this.captureSyncFailure(error, context);
+            throw error;
         }
-        return {
-            dispose: () => {
-                if (intervalId !== null && typeof clearInterval !== "undefined") {
-                    clearInterval(intervalId);
-                }
-            },
-        };
     }
     async wrapAsync(operation, context) {
         try {
@@ -95,21 +84,214 @@ export class StimpactClient {
         }
         catch (error) {
             try {
-                await this.captureError({
+                await this.captureHandledError({
                     ...context,
                     error,
                 });
             }
             catch (captureFailure) {
-                if (error instanceof Error) {
-                    Object.defineProperty(error, "captureFailure", {
-                        value: captureFailure,
-                        configurable: true,
-                    });
+                this.attachCaptureFailure(error, captureFailure);
+            }
+            throw error;
+        }
+    }
+    registerProcessAutoCapture(options = {}) {
+        const processTarget = options.processTarget ?? resolveProcessTarget();
+        if (!processTarget) {
+            return { dispose: () => undefined };
+        }
+        const captureUncaughtExceptions = options.captureUncaughtExceptions ?? true;
+        const captureUnhandledRejections = options.captureUnhandledRejections ?? true;
+        const uncaughtExceptionListener = (error) => {
+            if (this.shouldIgnoreAutoCapturedError(error)) {
+                return;
+            }
+            void this.captureError({
+                error: toError(error),
+                service: this.options.service,
+            }).catch(() => undefined);
+        };
+        const unhandledRejectionListener = (reason) => {
+            if (this.shouldIgnoreAutoCapturedError(reason)) {
+                return;
+            }
+            void this.captureError({
+                error: toError(reason),
+                service: this.options.service,
+            }).catch(() => undefined);
+        };
+        if (captureUncaughtExceptions) {
+            addProcessListener(processTarget, "uncaughtException", uncaughtExceptionListener);
+        }
+        if (captureUnhandledRejections) {
+            addProcessListener(processTarget, "unhandledRejection", unhandledRejectionListener);
+        }
+        return {
+            dispose: () => {
+                if (captureUncaughtExceptions) {
+                    removeProcessListener(processTarget, "uncaughtException", uncaughtExceptionListener);
                 }
+                if (captureUnhandledRejections) {
+                    removeProcessListener(processTarget, "unhandledRejection", unhandledRejectionListener);
+                }
+            },
+        };
+    }
+    async captureWithState(input) {
+        const trackedError = asTrackableObject(input.error);
+        if (trackedError && (this.inFlightErrors.has(trackedError) || this.reportedErrors.has(trackedError))) {
+            return;
+        }
+        if (trackedError) {
+            this.inFlightErrors.add(trackedError);
+            markCaptureState(trackedError, CAPTURE_IN_FLIGHT);
+        }
+        const normalized = normalizeError(input.error, this.options.maxValueLength);
+        const payload = {
+            project_id: this.options.projectId,
+            environment: input.environment ?? this.options.environment ?? "production",
+            service: input.service ?? this.options.service,
+            error_message: normalized.message,
+            stacktrace: normalized.stacktrace,
+            request: this.options.captureRequestContext
+                ? sanitizeRequestContext(input.request, this.options)
+                : undefined,
+            response: this.options.captureResponseContext
+                ? sanitizeResponseContext(input.response, this.options)
+                : undefined,
+            commit_sha: input.commitSha ?? null,
+            timestamp: normalizeTimestamp(input.timestamp),
+        };
+        try {
+            await this.sendTelemetry(payload);
+            if (trackedError) {
+                this.reportedErrors.add(trackedError);
+                markCaptureState(trackedError, CAPTURE_REPORTED);
+            }
+        }
+        catch (error) {
+            if (trackedError) {
+                clearCaptureState(trackedError, CAPTURE_REPORTED);
             }
             throw error;
         }
+        finally {
+            if (trackedError) {
+                this.inFlightErrors.delete(trackedError);
+                clearCaptureState(trackedError, CAPTURE_IN_FLIGHT);
+            }
+        }
+    }
+    startHeartbeat(options = {}) {
+        const intervalMs = options.intervalMs ?? 300_000;
+        const jitterRatio = clampNumber(options.jitterRatio ?? 0.1, 0, 0.5);
+        const immediate = options.immediate ?? true;
+        const pauseWhenHidden = options.pauseWhenHidden ?? false;
+        const skipWhenOffline = options.skipWhenOffline ?? true;
+        let timeoutId = null;
+        let disposed = false;
+        let paused = false;
+        const clearScheduledHeartbeat = () => {
+            if (timeoutId !== null && typeof clearTimeout !== "undefined") {
+                clearTimeout(timeoutId);
+            }
+            timeoutId = null;
+        };
+        const isDocumentHidden = () => typeof document !== "undefined" && document.visibilityState === "hidden";
+        const isNavigatorOffline = () => typeof navigator !== "undefined" &&
+            "onLine" in navigator &&
+            navigator.onLine === false;
+        const shouldSkipHeartbeat = () => (pauseWhenHidden && isDocumentHidden()) || (skipWhenOffline && isNavigatorOffline());
+        const scheduleNextHeartbeat = () => {
+            if (disposed || paused || typeof setTimeout === "undefined") {
+                return;
+            }
+            clearScheduledHeartbeat();
+            const jitterWindowMs = Math.round(intervalMs * jitterRatio);
+            const delayMs = jitterWindowMs > 0 ? intervalMs - jitterWindowMs + Math.round(Math.random() * jitterWindowMs * 2) : intervalMs;
+            timeoutId = setTimeout(() => {
+                void triggerHeartbeat().catch(() => undefined);
+            }, delayMs);
+        };
+        const triggerHeartbeat = async (input = options) => {
+            if (disposed) {
+                return;
+            }
+            if (shouldSkipHeartbeat()) {
+                scheduleNextHeartbeat();
+                return;
+            }
+            try {
+                await this.sendHeartbeat(input);
+            }
+            finally {
+                scheduleNextHeartbeat();
+            }
+        };
+        const resume = () => {
+            if (disposed) {
+                return;
+            }
+            paused = false;
+            scheduleNextHeartbeat();
+        };
+        const pause = () => {
+            paused = true;
+            clearScheduledHeartbeat();
+        };
+        const handleVisibilityChange = () => {
+            if (!pauseWhenHidden || disposed) {
+                return;
+            }
+            if (isDocumentHidden()) {
+                pause();
+                return;
+            }
+            resume();
+        };
+        const handleOnline = () => {
+            if (!skipWhenOffline || disposed) {
+                return;
+            }
+            resume();
+            void triggerHeartbeat().catch(() => undefined);
+        };
+        const handleOffline = () => {
+            if (!skipWhenOffline || disposed) {
+                return;
+            }
+            pause();
+        };
+        if (pauseWhenHidden && typeof document !== "undefined") {
+            document.addEventListener("visibilitychange", handleVisibilityChange);
+        }
+        if (skipWhenOffline && typeof window !== "undefined") {
+            window.addEventListener("online", handleOnline);
+            window.addEventListener("offline", handleOffline);
+        }
+        if (immediate) {
+            void triggerHeartbeat().catch(() => undefined);
+        }
+        else {
+            scheduleNextHeartbeat();
+        }
+        return {
+            dispose: () => {
+                disposed = true;
+                clearScheduledHeartbeat();
+                if (pauseWhenHidden && typeof document !== "undefined") {
+                    document.removeEventListener("visibilitychange", handleVisibilityChange);
+                }
+                if (skipWhenOffline && typeof window !== "undefined") {
+                    window.removeEventListener("online", handleOnline);
+                    window.removeEventListener("offline", handleOffline);
+                }
+            },
+            pause,
+            resume,
+            triggerNow: (input = options) => triggerHeartbeat(input),
+            isRunning: () => !disposed && !paused,
+        };
     }
     registerBrowserAutoCapture(options = {}) {
         if (typeof window === "undefined") {
@@ -118,16 +300,22 @@ export class StimpactClient {
         const captureWindowErrors = options.captureWindowErrors ?? true;
         const captureUnhandledRejections = options.captureUnhandledRejections ?? true;
         const errorListener = (event) => {
+            if (this.shouldIgnoreAutoCapturedError(event.error)) {
+                return;
+            }
             void this.captureError({
                 error: event.error ?? event.message,
                 service: this.options.service,
-            });
+            }).catch(() => undefined);
         };
         const rejectionListener = (event) => {
+            if (this.shouldIgnoreAutoCapturedError(event.reason)) {
+                return;
+            }
             void this.captureError({
                 error: event.reason ?? "Unhandled promise rejection",
                 service: this.options.service,
-            });
+            }).catch(() => undefined);
         };
         if (captureWindowErrors) {
             window.addEventListener("error", errorListener);
@@ -146,6 +334,35 @@ export class StimpactClient {
             },
         };
     }
+    shouldIgnoreAutoCapturedError(error) {
+        if (error instanceof StimpactRequestError) {
+            return true;
+        }
+        const trackedError = asTrackableObject(error);
+        if (!trackedError) {
+            return false;
+        }
+        return (this.inFlightErrors.has(trackedError) ||
+            this.reportedErrors.has(trackedError) ||
+            hasCaptureState(trackedError, CAPTURE_IN_FLIGHT) ||
+            hasCaptureState(trackedError, CAPTURE_REPORTED));
+    }
+    captureSyncFailure(error, context) {
+        void this.captureHandledError({
+            ...context,
+            error,
+        }).catch((captureFailure) => {
+            this.attachCaptureFailure(error, captureFailure);
+        });
+    }
+    attachCaptureFailure(error, captureFailure) {
+        if (error instanceof Error) {
+            Object.defineProperty(error, "captureFailure", {
+                value: captureFailure,
+                configurable: true,
+            });
+        }
+    }
     async sendTelemetry(payload) {
         let lastError;
         for (let attempt = 0; attempt <= this.options.retryAttempts; attempt += 1) {
@@ -248,6 +465,10 @@ export class StimpactClient {
             Date.now() + refreshThresholdMs < this.cachedBrowserTokenExpiresAtMs) {
             return this.cachedBrowserToken;
         }
+        if (this.browserTokenFailure &&
+            Date.now() < this.browserTokenFailureBlockedUntilMs) {
+            throw this.browserTokenFailure;
+        }
         if (this.browserTokenPromise) {
             return this.browserTokenPromise;
         }
@@ -265,16 +486,26 @@ export class StimpactClient {
             service: payload.service,
             environment: payload.environment,
         };
-        const response = await this.performJsonRequest(endpoint, body);
-        const parsed = (await safeReadResponseJson(response));
-        const token = typeof parsed?.token === "string" ? parsed.token : null;
-        if (!token) {
-            throw new StimpactRequestError("Browser token request succeeded without a token payload.");
+        try {
+            const response = await this.performJsonRequest(endpoint, body);
+            const parsed = (await safeReadResponseJson(response));
+            const token = typeof parsed?.token === "string" ? parsed.token : null;
+            if (!token) {
+                throw new StimpactRequestError("Browser token request succeeded without a token payload.");
+            }
+            const expiresAtMs = resolveTokenExpiryMs(parsed);
+            this.cachedBrowserToken = token;
+            this.cachedBrowserTokenExpiresAtMs = expiresAtMs;
+            this.browserTokenFailure = null;
+            this.browserTokenFailureBlockedUntilMs = 0;
+            return token;
+        }
+        catch (error) {
+            if (error instanceof StimpactRequestError) {
+                this.rememberBrowserTokenFailure(error);
+            }
+            throw error;
         }
-        const expiresAtMs = resolveTokenExpiryMs(parsed);
-        this.cachedBrowserToken = token;
-        this.cachedBrowserTokenExpiresAtMs = expiresAtMs;
-        return token;
     }
     async performJsonRequest(url, payload) {
         const fetchImpl = this.options.fetchImpl ?? fetch;
@@ -316,6 +547,16 @@ export class StimpactClient {
             }
         }
     }
+    rememberBrowserTokenFailure(error) {
+        if (error.retryable) {
+            return;
+        }
+        this.cachedBrowserToken = null;
+        this.cachedBrowserTokenExpiresAtMs = 0;
+        this.browserTokenFailure = error;
+        this.browserTokenFailureBlockedUntilMs =
+            Date.now() + this.options.browserTokenFailureCooldownMs;
+    }
 }
 function normalizeTimestamp(value) {
     if (!value) {
@@ -323,6 +564,52 @@ function normalizeTimestamp(value) {
     }
     return value instanceof Date ? value.toISOString() : value;
 }
+function asTrackableObject(value) {
+    if ((typeof value === "object" && value !== null) || typeof value === "function") {
+        return value;
+    }
+    return null;
+}
+function hasCaptureState(target, symbol) {
+    return Boolean(target[symbol]);
+}
+function markCaptureState(target, symbol) {
+    Object.defineProperty(target, symbol, {
+        value: true,
+        configurable: true,
+    });
+}
+function clearCaptureState(target, symbol) {
+    delete target[symbol];
+}
+function toError(error) {
+    if (error instanceof Error) {
+        return error;
+    }
+    return new Error(typeof error === "string" ? error : safeSerialize(error));
+}
+function resolveProcessTarget() {
+    const candidate = globalThis.process;
+    return candidate ?? null;
+}
+function addProcessListener(target, event, listener) {
+    if (typeof target.on === "function") {
+        target.on(event, listener);
+        return;
+    }
+    if (typeof target.addListener === "function") {
+        target.addListener(event, listener);
+    }
+}
+function removeProcessListener(target, event, listener) {
+    if (typeof target.off === "function") {
+        target.off(event, listener);
+        return;
+    }
+    if (typeof target.removeListener === "function") {
+        target.removeListener(event, listener);
+    }
+}
 function normalizeError(error, maxValueLength) {
     if (error instanceof Error) {
         return {
@@ -485,3 +772,9 @@ function delay(ms) {
         setTimeout(resolve, ms);
     });
 }
+function clampNumber(value, min, max) {
+    if (!Number.isFinite(value)) {
+        return min;
+    }
+    return Math.min(max, Math.max(min, value));
+}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { StimpactClient, StimpactRequestError } from "./client.js";
-export type { BrowserAutoCaptureOptions, BrowserCaptureSubscription, CaptureErrorInput, HeartbeatInput, HeartbeatSubscription, HttpRequestContext, HttpResponseContext, StimpactClientOptions, StimpactEnvironment, } from "./types.js";
+export type { BrowserAutoCaptureOptions, BrowserCaptureSubscription, CaptureErrorInput, ErrorCaptureContext, HeartbeatInput, HeartbeatScheduleOptions, HeartbeatSubscription, HttpRequestContext, ProcessAutoCaptureOptions, ProcessCaptureSubscription, ProcessListenerTarget, HttpResponseContext, StimpactClientOptions, StimpactEnvironment, } from "./types.js";

package/dist/types.d.ts

@@ -20,12 +20,20 @@ export type CaptureErrorInput = {
     service?: string;
     timestamp?: string | Date;
 };
+export type ErrorCaptureContext = Omit<CaptureErrorInput, "error">;
 export type HeartbeatInput = {
     commitSha?: string | null;
     environment?: StimpactEnvironment;
     service?: string;
     timestamp?: string | Date;
 };
+export type HeartbeatScheduleOptions = HeartbeatInput & {
+    intervalMs?: number;
+    immediate?: boolean;
+    jitterRatio?: number;
+    pauseWhenHidden?: boolean;
+    skipWhenOffline?: boolean;
+};
 export type StimpactClientOptions = {
     baseUrl: string;
     projectId: string;
@@ -40,6 +48,7 @@ export type StimpactClientOptions = {
     timeoutMs?: number;
     retryAttempts?: number;
     retryDelayMs?: number;
+    browserTokenFailureCooldownMs?: number;
     captureRequestContext?: boolean;
     captureResponseContext?: boolean;
     includeBodies?: boolean;
@@ -53,6 +62,24 @@ export type BrowserAutoCaptureOptions = {
 export type BrowserCaptureSubscription = {
     dispose: () => void;
 };
+export type ProcessListenerTarget = {
+    on?: (event: string, listener: (...args: unknown[]) => void) => void;
+    off?: (event: string, listener: (...args: unknown[]) => void) => void;
+    addListener?: (event: string, listener: (...args: unknown[]) => void) => void;
+    removeListener?: (event: string, listener: (...args: unknown[]) => void) => void;
+};
+export type ProcessAutoCaptureOptions = {
+    captureUncaughtExceptions?: boolean;
+    captureUnhandledRejections?: boolean;
+    processTarget?: ProcessListenerTarget | null;
+};
+export type ProcessCaptureSubscription = {
+    dispose: () => void;
+};
 export type HeartbeatSubscription = {
     dispose: () => void;
+    pause: () => void;
+    resume: () => void;
+    triggerNow: (input?: HeartbeatInput) => Promise<void>;
+    isRunning: () => boolean;
 };

package/package.json

@@ -1,15 +1,38 @@
 {
   "name": "@stimpact/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
   "files": [
     "dist"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test tests/**/*.test.mjs"
+    "test:unit": "npm run build && node --test tests/client.test.mjs",
+    "test:consumer": "npm run build && node --test tests/package-consumer.test.mjs",
+    "test": "npm run test:unit && npm run test:consumer",
+    "pack:dry-run": "npm pack --dry-run",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stimpactai/stimpact-ai.git",
+    "directory": "sdk"
+  },
+  "homepage": "https://github.com/stimpactai/stimpact-ai/tree/main/sdk",
+  "engines": {
+    "node": ">=18"
   },
   "devDependencies": {
     "typescript": "^5.9.3"