@stimpact/sdk 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# Stimpact SDK
+
+The TypeScript SDK sends runtime errors and heartbeats to the Stimpact agent platform.
+
+Server runtimes should use a private project `apiKey`.
+
+Browser runtimes should use either:
+
+- a short-lived token flow via `browserKey`
+- a custom `browserTokenEndpoint`
+- a custom `tokenProvider`
+
+## Install
+
+```sh
+npm install @stimpact/sdk
+```
+
+## Server usage
+
+```ts
+import { StimpactClient } from "@stimpact/sdk";
+
+const stimpact = new StimpactClient({
+  baseUrl: "https://your-stimpact-api.example.com",
+  projectId: "billing-prod",
+  apiKey: "stimp_live_...",
+  service: "billing-api",
+  environment: "production",
+});
+
+try {
+  await doWork();
+} catch (error) {
+  await stimpact.captureError({
+    error,
+    request: {
+      method: "POST",
+      url: "/api/charge",
+    },
+  });
+}
+```
+
+## Browser usage
+
+```ts
+import { StimpactClient } from "@stimpact/sdk";
+
+const stimpact = new StimpactClient({
+  baseUrl: "https://your-stimpact-api.example.com",
+  projectId: "billing-prod",
+  browserKey: "stimp_browser_...",
+  service: "billing-web",
+  environment: "production",
+});
+
+stimpact.startHeartbeat();
+stimpact.registerBrowserAutoCapture();
+```
+
+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.
+
+## Browser autocapture
+
+```ts
+const subscription = stimpact.registerBrowserAutoCapture();
+
+// Later, if needed:
+subscription.dispose();
+```
+
+## Wrapped async flows
+
+```ts
+await stimpact.wrapAsync(async () => {
+  await saveInvoice();
+});
+```
+
+## Data minimization defaults
+
+By default the SDK:
+
+- sends the normalized error message and stacktrace
+- does not forward request or response context unless you explicitly opt in
+- redacts common sensitive headers such as `authorization`, `cookie`, `set-cookie`, and `x-api-key`
+- omits request and response bodies unless `includeBodies` is enabled
+
+To opt in to richer HTTP context:
+
+```ts
+const stimpact = new StimpactClient({
+  baseUrl: "https://your-stimpact-api.example.com",
+  projectId: "billing-prod",
+  apiKey: "stimp_live_...",
+  service: "billing-api",
+  captureRequestContext: true,
+  captureResponseContext: true,
+  includeBodies: false,
+});
+```

package/dist/client.d.ts

@@ -0,0 +1,33 @@
+import type { BrowserAutoCaptureOptions, BrowserCaptureSubscription, CaptureErrorInput, HeartbeatInput, HeartbeatSubscription, StimpactClientOptions } from "./types.js";
+export declare class StimpactRequestError extends Error {
+    status: number | null;
+    retryable: boolean;
+    responseBody: string | null;
+    constructor(message: string, options?: {
+        status?: number | null;
+        retryable?: boolean;
+        responseBody?: string | null;
+    });
+}
+export declare class StimpactClient {
+    private readonly options;
+    private cachedBrowserToken;
+    private cachedBrowserTokenExpiresAtMs;
+    private browserTokenPromise;
+    constructor(options: StimpactClientOptions);
+    captureError(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>;
+    registerBrowserAutoCapture(options?: BrowserAutoCaptureOptions): BrowserCaptureSubscription;
+    private sendTelemetry;
+    private sendHeartbeatPayload;
+    private sendTelemetryOnce;
+    private sendJson;
+    private buildAuthHeaders;
+    private getBrowserToken;
+    private fetchBrowserToken;
+    private performJsonRequest;
+}

package/dist/client.js

@@ -0,0 +1,487 @@
+const DEFAULT_REDACTED_HEADERS = new Set([
+    "authorization",
+    "cookie",
+    "set-cookie",
+    "proxy-authorization",
+    "x-api-key",
+    "x-stimpact-project-key",
+]);
+export class StimpactRequestError extends Error {
+    status;
+    retryable;
+    responseBody;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = "StimpactRequestError";
+        this.status = options.status ?? null;
+        this.retryable = options.retryable ?? false;
+        this.responseBody = options.responseBody ?? null;
+    }
+}
+export class StimpactClient {
+    options;
+    cachedBrowserToken = null;
+    cachedBrowserTokenExpiresAtMs = 0;
+    browserTokenPromise = null;
+    constructor(options) {
+        if (!options.apiKey && !options.browserKey && !options.browserTokenEndpoint && !options.tokenProvider) {
+            throw new Error("StimpactClient requires apiKey, browserKey, browserTokenEndpoint, or tokenProvider.");
+        }
+        this.options = {
+            ...options,
+            baseUrl: options.baseUrl.replace(/\/$/, ""),
+            environment: options.environment ?? "production",
+            fetchImpl: options.fetchImpl ?? fetch,
+            headers: options.headers ?? {},
+            timeoutMs: options.timeoutMs ?? 5_000,
+            retryAttempts: options.retryAttempts ?? 2,
+            retryDelayMs: options.retryDelayMs ?? 250,
+            captureRequestContext: options.captureRequestContext ?? false,
+            captureResponseContext: options.captureResponseContext ?? false,
+            includeBodies: options.includeBodies ?? false,
+            redactedHeaders: options.redactedHeaders ?? [],
+            maxValueLength: options.maxValueLength ?? 2_048,
+        };
+    }
+    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);
+    }
+    async sendHeartbeat(input = {}) {
+        const payload = {
+            project_id: this.options.projectId,
+            environment: input.environment ?? this.options.environment ?? "production",
+            service: input.service ?? this.options.service,
+            commit_sha: input.commitSha ?? null,
+            timestamp: normalizeTimestamp(input.timestamp),
+        };
+        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);
+        }
+        return {
+            dispose: () => {
+                if (intervalId !== null && typeof clearInterval !== "undefined") {
+                    clearInterval(intervalId);
+                }
+            },
+        };
+    }
+    async wrapAsync(operation, context) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            try {
+                await this.captureError({
+                    ...context,
+                    error,
+                });
+            }
+            catch (captureFailure) {
+                if (error instanceof Error) {
+                    Object.defineProperty(error, "captureFailure", {
+                        value: captureFailure,
+                        configurable: true,
+                    });
+                }
+            }
+            throw error;
+        }
+    }
+    registerBrowserAutoCapture(options = {}) {
+        if (typeof window === "undefined") {
+            return { dispose: () => undefined };
+        }
+        const captureWindowErrors = options.captureWindowErrors ?? true;
+        const captureUnhandledRejections = options.captureUnhandledRejections ?? true;
+        const errorListener = (event) => {
+            void this.captureError({
+                error: event.error ?? event.message,
+                service: this.options.service,
+            });
+        };
+        const rejectionListener = (event) => {
+            void this.captureError({
+                error: event.reason ?? "Unhandled promise rejection",
+                service: this.options.service,
+            });
+        };
+        if (captureWindowErrors) {
+            window.addEventListener("error", errorListener);
+        }
+        if (captureUnhandledRejections) {
+            window.addEventListener("unhandledrejection", rejectionListener);
+        }
+        return {
+            dispose: () => {
+                if (captureWindowErrors) {
+                    window.removeEventListener("error", errorListener);
+                }
+                if (captureUnhandledRejections) {
+                    window.removeEventListener("unhandledrejection", rejectionListener);
+                }
+            },
+        };
+    }
+    async sendTelemetry(payload) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.options.retryAttempts; attempt += 1) {
+            try {
+                await this.sendTelemetryOnce(payload);
+                return;
+            }
+            catch (error) {
+                lastError = error;
+                if (!(error instanceof StimpactRequestError) || !error.retryable || attempt === this.options.retryAttempts) {
+                    throw error;
+                }
+                await delay(this.options.retryDelayMs * (attempt + 1));
+            }
+        }
+        throw lastError instanceof Error
+            ? lastError
+            : new StimpactRequestError("Telemetry delivery failed.");
+    }
+    async sendHeartbeatPayload(payload) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.options.retryAttempts; attempt += 1) {
+            try {
+                await this.sendJson(`${this.options.baseUrl}/telemetry/heartbeat`, payload);
+                return;
+            }
+            catch (error) {
+                lastError = error;
+                if (!(error instanceof StimpactRequestError) || !error.retryable || attempt === this.options.retryAttempts) {
+                    throw error;
+                }
+                await delay(this.options.retryDelayMs * (attempt + 1));
+            }
+        }
+        throw lastError instanceof Error
+            ? lastError
+            : new StimpactRequestError("Telemetry heartbeat delivery failed.");
+    }
+    async sendTelemetryOnce(payload) {
+        await this.sendJson(`${this.options.baseUrl}/telemetry/error`, payload);
+    }
+    async sendJson(url, payload) {
+        const fetchImpl = this.options.fetchImpl ?? fetch;
+        const controller = typeof AbortController === "undefined" ? null : new AbortController();
+        const timeout = controller
+            ? setTimeout(() => controller.abort(), this.options.timeoutMs)
+            : null;
+        try {
+            const authHeaders = await this.buildAuthHeaders(payload);
+            const response = await fetchImpl(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    ...authHeaders,
+                    ...this.options.headers,
+                },
+                body: JSON.stringify(payload),
+                signal: controller?.signal,
+            });
+            if (!response.ok) {
+                const responseBody = await safeReadResponseText(response);
+                throw new StimpactRequestError(`Telemetry delivery failed with status ${response.status}.`, {
+                    status: response.status,
+                    retryable: response.status >= 500 || response.status === 429,
+                    responseBody,
+                });
+            }
+        }
+        catch (error) {
+            if (error instanceof StimpactRequestError) {
+                throw error;
+            }
+            throw new StimpactRequestError("Telemetry delivery failed before the platform acknowledged it.", {
+                retryable: true,
+            });
+        }
+        finally {
+            if (timeout !== null) {
+                clearTimeout(timeout);
+            }
+        }
+    }
+    async buildAuthHeaders(payload) {
+        if (this.options.apiKey) {
+            return {
+                "X-Stimpact-Project-Key": this.options.apiKey,
+            };
+        }
+        const token = await this.getBrowserToken(payload);
+        return {
+            Authorization: `Bearer ${token}`,
+        };
+    }
+    async getBrowserToken(payload) {
+        if (this.options.tokenProvider) {
+            return this.options.tokenProvider();
+        }
+        const refreshThresholdMs = 15_000;
+        if (this.cachedBrowserToken &&
+            Date.now() + refreshThresholdMs < this.cachedBrowserTokenExpiresAtMs) {
+            return this.cachedBrowserToken;
+        }
+        if (this.browserTokenPromise) {
+            return this.browserTokenPromise;
+        }
+        this.browserTokenPromise = this.fetchBrowserToken(payload).finally(() => {
+            this.browserTokenPromise = null;
+        });
+        return this.browserTokenPromise;
+    }
+    async fetchBrowserToken(payload) {
+        const endpoint = this.options.browserTokenEndpoint ??
+            `${this.options.baseUrl}/telemetry/browser-token`;
+        const body = {
+            project_id: this.options.projectId,
+            browser_key: this.options.browserKey,
+            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.");
+        }
+        const expiresAtMs = resolveTokenExpiryMs(parsed);
+        this.cachedBrowserToken = token;
+        this.cachedBrowserTokenExpiresAtMs = expiresAtMs;
+        return token;
+    }
+    async performJsonRequest(url, payload) {
+        const fetchImpl = this.options.fetchImpl ?? fetch;
+        const controller = typeof AbortController === "undefined" ? null : new AbortController();
+        const timeout = controller
+            ? setTimeout(() => controller.abort(), this.options.timeoutMs)
+            : null;
+        try {
+            const response = await fetchImpl(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    ...this.options.headers,
+                },
+                body: JSON.stringify(payload),
+                signal: controller?.signal,
+            });
+            if (!response.ok) {
+                const responseBody = await safeReadResponseText(response);
+                throw new StimpactRequestError(`Request failed with status ${response.status}.`, {
+                    status: response.status,
+                    retryable: response.status >= 500 || response.status === 429,
+                    responseBody,
+                });
+            }
+            return response;
+        }
+        catch (error) {
+            if (error instanceof StimpactRequestError) {
+                throw error;
+            }
+            throw new StimpactRequestError("Request failed before the platform acknowledged it.", {
+                retryable: true,
+            });
+        }
+        finally {
+            if (timeout !== null) {
+                clearTimeout(timeout);
+            }
+        }
+    }
+}
+function normalizeTimestamp(value) {
+    if (!value) {
+        return new Date().toISOString();
+    }
+    return value instanceof Date ? value.toISOString() : value;
+}
+function normalizeError(error, maxValueLength) {
+    if (error instanceof Error) {
+        return {
+            message: clampString(error.message || error.name || "Unknown error", maxValueLength),
+            stacktrace: clampString(error.stack || error.message || error.name, maxValueLength * 4),
+        };
+    }
+    if (typeof error === "string") {
+        return {
+            message: clampString(error, maxValueLength),
+            stacktrace: clampString(error, maxValueLength * 4),
+        };
+    }
+    const sanitized = sanitizeUnknown(error, {
+        includeBodies: false,
+        maxValueLength,
+        redactedHeaders: [],
+    });
+    const serialized = safeSerialize(sanitized);
+    return {
+        message: typeof sanitized === "object" &&
+            sanitized !== null &&
+            "message" in sanitized &&
+            typeof sanitized.message === "string"
+            ? clampString(sanitized.message, maxValueLength)
+            : "Unknown error",
+        stacktrace: clampString(serialized, maxValueLength * 4),
+    };
+}
+async function safeReadResponseText(response) {
+    try {
+        const text = await response.text();
+        return text || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function safeReadResponseJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return null;
+    }
+}
+function sanitizeRequestContext(request, options) {
+    if (!request) {
+        return undefined;
+    }
+    return omitUndefined({
+        method: request.method
+            ? clampString(request.method, 32)
+            : undefined,
+        url: request.url
+            ? clampString(request.url, options.maxValueLength ?? 2_048)
+            : undefined,
+        headers: sanitizeHeaders(request.headers, options.redactedHeaders, options.maxValueLength),
+        body: options.includeBodies
+            ? sanitizeUnknown(request.body, options)
+            : undefined,
+    });
+}
+function sanitizeResponseContext(response, options) {
+    if (!response) {
+        return undefined;
+    }
+    return omitUndefined({
+        status_code: response.status_code,
+        headers: sanitizeHeaders(response.headers, options.redactedHeaders, options.maxValueLength),
+        body: options.includeBodies
+            ? sanitizeUnknown(response.body, options)
+            : undefined,
+    });
+}
+function sanitizeHeaders(headers, redactedHeaders, maxValueLength = 2_048) {
+    if (!headers) {
+        return undefined;
+    }
+    const extraRedactions = new Set((redactedHeaders ?? []).map((value) => value.toLowerCase()));
+    const entries = Object.entries(headers)
+        .slice(0, 40)
+        .map(([key, value]) => {
+        const lowerKey = key.toLowerCase();
+        const shouldRedact = DEFAULT_REDACTED_HEADERS.has(lowerKey) || extraRedactions.has(lowerKey);
+        return [key, shouldRedact ? "[REDACTED]" : clampString(String(value), maxValueLength)];
+    });
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+function sanitizeUnknown(value, options, seen = new WeakSet(), depth = 0) {
+    const maxValueLength = options.maxValueLength ?? 2_048;
+    if (value == null || typeof value === "number" || typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "string") {
+        return clampString(value, maxValueLength);
+    }
+    if (typeof value === "bigint") {
+        return clampString(value.toString(), maxValueLength);
+    }
+    if (typeof value === "function" || typeof value === "symbol") {
+        return clampString(String(value), maxValueLength);
+    }
+    if (depth >= 4) {
+        return "[TRUNCATED]";
+    }
+    if (Array.isArray(value)) {
+        return value
+            .slice(0, 20)
+            .map((item) => sanitizeUnknown(item, options, seen, depth + 1));
+    }
+    if (typeof value === "object") {
+        if (seen.has(value)) {
+            return "[Circular]";
+        }
+        seen.add(value);
+        const output = {};
+        for (const [key, entry] of Object.entries(value).slice(0, 25)) {
+            output[key] = sanitizeUnknown(entry, options, seen, depth + 1);
+        }
+        return output;
+    }
+    return clampString(String(value), maxValueLength);
+}
+function safeSerialize(value) {
+    try {
+        return JSON.stringify(value, null, 2);
+    }
+    catch {
+        return String(value);
+    }
+}
+function clampString(value, maxLength) {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return `${value.slice(0, maxLength)}...[truncated]`;
+}
+function omitUndefined(value) {
+    const entries = Object.entries(value).filter(([, entry]) => entry !== undefined);
+    if (entries.length === 0) {
+        return undefined;
+    }
+    return Object.fromEntries(entries);
+}
+function resolveTokenExpiryMs(response) {
+    if (typeof response?.expires_at === "string") {
+        const parsed = Date.parse(response.expires_at);
+        if (!Number.isNaN(parsed)) {
+            return parsed;
+        }
+    }
+    if (typeof response?.expires_in_seconds === "number" && Number.isFinite(response.expires_in_seconds)) {
+        return Date.now() + Math.max(30, response.expires_in_seconds) * 1_000;
+    }
+    return Date.now() + 60_000;
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1 @@
+export { StimpactClient, StimpactRequestError } from "./client.js";

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+export type StimpactEnvironment = "production" | "staging" | "development" | "test";
+export type StimpactTokenProvider = () => Promise<string>;
+export type HttpRequestContext = {
+    method?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+};
+export type HttpResponseContext = {
+    status_code?: number;
+    headers?: Record<string, string>;
+    body?: unknown;
+};
+export type CaptureErrorInput = {
+    error: unknown;
+    request?: HttpRequestContext;
+    response?: HttpResponseContext;
+    commitSha?: string | null;
+    environment?: StimpactEnvironment;
+    service?: string;
+    timestamp?: string | Date;
+};
+export type HeartbeatInput = {
+    commitSha?: string | null;
+    environment?: StimpactEnvironment;
+    service?: string;
+    timestamp?: string | Date;
+};
+export type StimpactClientOptions = {
+    baseUrl: string;
+    projectId: string;
+    apiKey?: string;
+    browserKey?: string;
+    browserTokenEndpoint?: string;
+    tokenProvider?: StimpactTokenProvider;
+    service: string;
+    environment?: StimpactEnvironment;
+    fetchImpl?: typeof fetch;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    retryAttempts?: number;
+    retryDelayMs?: number;
+    captureRequestContext?: boolean;
+    captureResponseContext?: boolean;
+    includeBodies?: boolean;
+    redactedHeaders?: string[];
+    maxValueLength?: number;
+};
+export type BrowserAutoCaptureOptions = {
+    captureWindowErrors?: boolean;
+    captureUnhandledRejections?: boolean;
+};
+export type BrowserCaptureSubscription = {
+    dispose: () => void;
+};
+export type HeartbeatSubscription = {
+    dispose: () => void;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@stimpact/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test tests/**/*.test.mjs"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}