@retrace-kit/sdk 0.0.0

package/README.md

@@ -0,0 +1,49 @@
+# @bug-catcher/sdk
+
+TypeScript SDK for Bug Catcher, built with [Rslib](https://rslib.rs/) (Rsbuild).
+
+## Install
+
+```bash
+npm install @bug-catcher/sdk
+```
+
+## Usage
+
+### ESM (Node.js / bundlers)
+
+```ts
+import { squared } from '@bug-catcher/sdk';
+```
+
+### CommonJS
+
+```js
+const { squared } = require('@bug-catcher/sdk');
+```
+
+### UMD (browser)
+
+```html
+<script src="https://unpkg.com/@bug-catcher/sdk/dist/umd/index.js"></script>
+<script>
+  BugCatcher.squared(4); // 16
+</script>
+```
+
+## Development
+
+```bash
+npm install
+npm run dev    # watch mode
+npm run build  # production build
+```
+
+Build outputs:
+
+| Format | Path |
+| --- | --- |
+| ESM | `dist/index.js` |
+| CommonJS | `dist/index.cjs` |
+| UMD | `dist/umd/index.js` |
+| Types | `dist/index.d.ts` |

package/dist/capture.d.ts

@@ -0,0 +1,9 @@
+import type { IngestErrorEventPayload } from './types';
+/**
+ * Build a backend-aligned payload from an error, current config defaults, and optional overrides.
+ */
+export declare function buildPayloadFromError(error: unknown, config: {
+    release?: string;
+    environment?: string;
+}, context?: Partial<IngestErrorEventPayload>): IngestErrorEventPayload;
+export declare function captureException(error: unknown, context?: Partial<IngestErrorEventPayload>): void;

package/dist/config.d.ts

@@ -0,0 +1,15 @@
+import type { BugCatcherConfig } from './types';
+type InternalConfig = {
+    apiKey: string;
+    endpoint: string;
+    release?: string;
+    environment?: string;
+    enabled: boolean;
+};
+/**
+ * Initialize SDK configuration and global error handlers.
+ */
+export declare function init(config: BugCatcherConfig): void;
+export declare function getCurrentConfig(): InternalConfig | null;
+export declare function isCaptureEnabled(): boolean;
+export {};

package/dist/globalHandlers.d.ts

@@ -0,0 +1,2 @@
+export declare function unregisterGlobalHandlers(): void;
+export declare function registerGlobalHandlers(): void;

package/dist/index.cjs

@@ -0,0 +1,187 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, getters, values)=>{
+        var define = (defs, kind)=>{
+            for(var key in defs)if (__webpack_require__.o(defs, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+                enumerable: true,
+                [kind]: defs[key]
+            });
+        };
+        define(getters, "get");
+        define(values, "value");
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    captureException: ()=>captureException,
+    init: ()=>init
+});
+function sendErrorEvent(payload, config) {
+    (async ()=>{
+        try {
+            const response = await fetch(config.endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${config.apiKey}`
+                },
+                body: JSON.stringify(payload)
+            });
+            if (!response.ok) console.warn(`[bug-catcher sdk] failed to send error event: HTTP ${response.status}`);
+        } catch (err) {
+            console.error('[bug-catcher sdk] failed to send error event:', err);
+        }
+    })();
+}
+function getBrowserUrl() {
+    try {
+        const href = globalThis.window?.location?.href;
+        if (href) return href;
+    } catch  {}
+}
+function getBrowserUserAgent() {
+    try {
+        const userAgent = globalThis.navigator?.userAgent;
+        if (userAgent) return userAgent;
+    } catch  {}
+}
+function extractMessage(error) {
+    if (error instanceof Error && error.message) return error.message;
+    if ('string' == typeof error && error) return error;
+    if (null != error) try {
+        const value = String(error);
+        if (value) return value;
+    } catch  {}
+    return 'Unknown error';
+}
+function extractStacktrace(error) {
+    if (error instanceof Error && error.stack) return error.stack;
+    return 'No stacktrace available';
+}
+function buildPayloadFromError(error, config, context) {
+    const payload = {
+        timestamp: new Date().toISOString(),
+        message: extractMessage(error),
+        stacktrace: extractStacktrace(error),
+        url: getBrowserUrl(),
+        release: config.release,
+        environment: config.environment,
+        userAgent: getBrowserUserAgent()
+    };
+    if (!context) return payload;
+    return {
+        ...payload,
+        ...context
+    };
+}
+function captureException(error, context) {
+    try {
+        const cfg = getCurrentConfig();
+        if (!cfg?.enabled || !cfg.apiKey) return;
+        const payload = buildPayloadFromError(error, cfg, context);
+        sendErrorEvent(payload, cfg);
+    } catch  {}
+}
+let errorListener = null;
+let rejectionListener = null;
+function getBrowserWindow() {
+    try {
+        const win = globalThis.window;
+        if (win && 'function' == typeof win.addEventListener) return win;
+    } catch  {}
+    return null;
+}
+function unregisterGlobalHandlers() {
+    const win = getBrowserWindow();
+    if (!win) return;
+    if (errorListener) {
+        win.removeEventListener('error', errorListener);
+        errorListener = null;
+    }
+    if (rejectionListener) {
+        win.removeEventListener('unhandledrejection', rejectionListener);
+        rejectionListener = null;
+    }
+}
+function registerGlobalHandlers() {
+    const win = getBrowserWindow();
+    if (!win) return;
+    errorListener = (event)=>{
+        try {
+            const e = event;
+            const target = e.target;
+            if (target && target !== win && !e.error) return;
+            const error = e.error instanceof Error ? e.error : new Error(e.message || 'Unknown error');
+            captureException(error);
+        } catch  {}
+    };
+    rejectionListener = (event)=>{
+        try {
+            const reason = event.reason;
+            captureException(reason);
+        } catch  {}
+    };
+    win.addEventListener('error', errorListener);
+    win.addEventListener('unhandledrejection', rejectionListener);
+}
+let currentConfig = null;
+let warnedAboutMissingApiKey = false;
+function normalizeEndpoint(endpoint) {
+    return endpoint?.trim() ? endpoint : '/api/error-events';
+}
+function init(config) {
+    const endpoint = normalizeEndpoint(config?.endpoint);
+    const rawApiKey = config?.apiKey;
+    const apiKey = 'string' == typeof rawApiKey ? rawApiKey.trim() : '';
+    const enabledFromConfig = config?.enabled !== false;
+    unregisterGlobalHandlers();
+    if (!apiKey) {
+        if (!warnedAboutMissingApiKey) {
+            warnedAboutMissingApiKey = true;
+            console.warn('[bug-catcher sdk] init({ apiKey }) requires a non-blank apiKey; event sending will be disabled.');
+        }
+        currentConfig = {
+            apiKey: '',
+            endpoint,
+            release: config?.release,
+            environment: config?.environment,
+            enabled: false
+        };
+        return;
+    }
+    currentConfig = {
+        apiKey,
+        endpoint,
+        release: config?.release,
+        environment: config?.environment,
+        enabled: enabledFromConfig
+    };
+    if (enabledFromConfig) registerGlobalHandlers();
+}
+function getCurrentConfig() {
+    return currentConfig;
+}
+exports.captureException = __webpack_exports__.captureException;
+exports.init = __webpack_exports__.init;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "captureException",
+    "init"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { init } from './config';
+export { captureException } from './capture';
+export type { BugCatcherConfig, IngestErrorEventPayload } from './types';

package/dist/index.js

@@ -0,0 +1,146 @@
+function sendErrorEvent(payload, config) {
+    (async ()=>{
+        try {
+            const response = await fetch(config.endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${config.apiKey}`
+                },
+                body: JSON.stringify(payload)
+            });
+            if (!response.ok) console.warn(`[bug-catcher sdk] failed to send error event: HTTP ${response.status}`);
+        } catch (err) {
+            console.error('[bug-catcher sdk] failed to send error event:', err);
+        }
+    })();
+}
+function getBrowserUrl() {
+    try {
+        const href = globalThis.window?.location?.href;
+        if (href) return href;
+    } catch  {}
+}
+function getBrowserUserAgent() {
+    try {
+        const userAgent = globalThis.navigator?.userAgent;
+        if (userAgent) return userAgent;
+    } catch  {}
+}
+function extractMessage(error) {
+    if (error instanceof Error && error.message) return error.message;
+    if ('string' == typeof error && error) return error;
+    if (null != error) try {
+        const value = String(error);
+        if (value) return value;
+    } catch  {}
+    return 'Unknown error';
+}
+function extractStacktrace(error) {
+    if (error instanceof Error && error.stack) return error.stack;
+    return 'No stacktrace available';
+}
+function buildPayloadFromError(error, config, context) {
+    const payload = {
+        timestamp: new Date().toISOString(),
+        message: extractMessage(error),
+        stacktrace: extractStacktrace(error),
+        url: getBrowserUrl(),
+        release: config.release,
+        environment: config.environment,
+        userAgent: getBrowserUserAgent()
+    };
+    if (!context) return payload;
+    return {
+        ...payload,
+        ...context
+    };
+}
+function captureException(error, context) {
+    try {
+        const cfg = getCurrentConfig();
+        if (!cfg?.enabled || !cfg.apiKey) return;
+        const payload = buildPayloadFromError(error, cfg, context);
+        sendErrorEvent(payload, cfg);
+    } catch  {}
+}
+let errorListener = null;
+let rejectionListener = null;
+function getBrowserWindow() {
+    try {
+        const win = globalThis.window;
+        if (win && 'function' == typeof win.addEventListener) return win;
+    } catch  {}
+    return null;
+}
+function unregisterGlobalHandlers() {
+    const win = getBrowserWindow();
+    if (!win) return;
+    if (errorListener) {
+        win.removeEventListener('error', errorListener);
+        errorListener = null;
+    }
+    if (rejectionListener) {
+        win.removeEventListener('unhandledrejection', rejectionListener);
+        rejectionListener = null;
+    }
+}
+function registerGlobalHandlers() {
+    const win = getBrowserWindow();
+    if (!win) return;
+    errorListener = (event)=>{
+        try {
+            const e = event;
+            const target = e.target;
+            if (target && target !== win && !e.error) return;
+            const error = e.error instanceof Error ? e.error : new Error(e.message || 'Unknown error');
+            captureException(error);
+        } catch  {}
+    };
+    rejectionListener = (event)=>{
+        try {
+            const reason = event.reason;
+            captureException(reason);
+        } catch  {}
+    };
+    win.addEventListener('error', errorListener);
+    win.addEventListener('unhandledrejection', rejectionListener);
+}
+let currentConfig = null;
+let warnedAboutMissingApiKey = false;
+function normalizeEndpoint(endpoint) {
+    return endpoint?.trim() ? endpoint : '/api/error-events';
+}
+function init(config) {
+    const endpoint = normalizeEndpoint(config?.endpoint);
+    const rawApiKey = config?.apiKey;
+    const apiKey = 'string' == typeof rawApiKey ? rawApiKey.trim() : '';
+    const enabledFromConfig = config?.enabled !== false;
+    unregisterGlobalHandlers();
+    if (!apiKey) {
+        if (!warnedAboutMissingApiKey) {
+            warnedAboutMissingApiKey = true;
+            console.warn('[bug-catcher sdk] init({ apiKey }) requires a non-blank apiKey; event sending will be disabled.');
+        }
+        currentConfig = {
+            apiKey: '',
+            endpoint,
+            release: config?.release,
+            environment: config?.environment,
+            enabled: false
+        };
+        return;
+    }
+    currentConfig = {
+        apiKey,
+        endpoint,
+        release: config?.release,
+        environment: config?.environment,
+        enabled: enabledFromConfig
+    };
+    if (enabledFromConfig) registerGlobalHandlers();
+}
+function getCurrentConfig() {
+    return currentConfig;
+}
+export { captureException, init };

package/dist/transport.d.ts

@@ -0,0 +1,9 @@
+import type { IngestErrorEventPayload } from './types';
+export type SendConfig = {
+    apiKey: string;
+    endpoint: string;
+};
+/**
+ * POST error payload to the configured endpoint. Never throws; logs failures to console.
+ */
+export declare function sendErrorEvent(payload: IngestErrorEventPayload, config: SendConfig): void;

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+export type BugCatcherConfig = {
+    apiKey: string;
+    /**
+     * Endpoint that receives error events.
+     * Defaults to `POST /api/error-events` (relative to the current origin).
+     */
+    endpoint?: string;
+    release?: string;
+    environment?: string;
+    /**
+     * When false, no events will be sent (public API stays callable).
+     */
+    enabled?: boolean;
+};
+export type IngestErrorEventPayload = {
+    /**
+     * ISO-8601 timestamp string. If omitted, the SDK will use "now" in later steps.
+     */
+    timestamp?: string;
+    message: string;
+    stacktrace: string;
+    url?: string;
+    release?: string;
+    environment?: string;
+    userAgent?: string;
+};

package/dist/umd/index.js

@@ -0,0 +1,188 @@
+(function(root, factory) {
+    if ('object' == typeof exports && 'object' == typeof module) module.exports = factory();
+    else if ('function' == typeof define && define.amd) define([], factory);
+    else if ('object' == typeof exports) exports["BugCatcher"] = factory();
+    else root["BugCatcher"] = factory();
+})(globalThis, ()=>(()=>{
+        "use strict";
+        var __webpack_require__ = {};
+        (()=>{
+            __webpack_require__.d = (exports1, getters, values)=>{
+                var define1 = (defs, kind)=>{
+                    for(var key in defs)if (__webpack_require__.o(defs, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+                        enumerable: true,
+                        [kind]: defs[key]
+                    });
+                };
+                define1(getters, "get");
+                define1(values, "value");
+            };
+        })();
+        (()=>{
+            __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+        })();
+        (()=>{
+            __webpack_require__.r = (exports1)=>{
+                if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+                    value: 'Module'
+                });
+                Object.defineProperty(exports1, '__esModule', {
+                    value: true
+                });
+            };
+        })();
+        var __webpack_exports__ = {};
+        __webpack_require__.r(__webpack_exports__);
+        __webpack_require__.d(__webpack_exports__, {
+            captureException: ()=>captureException,
+            init: ()=>init
+        });
+        function sendErrorEvent(payload, config) {
+            (async ()=>{
+                try {
+                    const response = await fetch(config.endpoint, {
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'application/json',
+                            Authorization: `Bearer ${config.apiKey}`
+                        },
+                        body: JSON.stringify(payload)
+                    });
+                    if (!response.ok) console.warn(`[bug-catcher sdk] failed to send error event: HTTP ${response.status}`);
+                } catch (err) {
+                    console.error('[bug-catcher sdk] failed to send error event:', err);
+                }
+            })();
+        }
+        function getBrowserUrl() {
+            try {
+                var _globalThis_window_location, _globalThis_window;
+                const href = null == (_globalThis_window = globalThis.window) ? void 0 : null == (_globalThis_window_location = _globalThis_window.location) ? void 0 : _globalThis_window_location.href;
+                if (href) return href;
+            } catch  {}
+        }
+        function getBrowserUserAgent() {
+            try {
+                var _globalThis_navigator;
+                const userAgent = null == (_globalThis_navigator = globalThis.navigator) ? void 0 : _globalThis_navigator.userAgent;
+                if (userAgent) return userAgent;
+            } catch  {}
+        }
+        function extractMessage(error) {
+            if (error instanceof Error && error.message) return error.message;
+            if ('string' == typeof error && error) return error;
+            if (null != error) try {
+                const value = String(error);
+                if (value) return value;
+            } catch  {}
+            return 'Unknown error';
+        }
+        function extractStacktrace(error) {
+            if (error instanceof Error && error.stack) return error.stack;
+            return 'No stacktrace available';
+        }
+        function buildPayloadFromError(error, config, context) {
+            const payload = {
+                timestamp: new Date().toISOString(),
+                message: extractMessage(error),
+                stacktrace: extractStacktrace(error),
+                url: getBrowserUrl(),
+                release: config.release,
+                environment: config.environment,
+                userAgent: getBrowserUserAgent()
+            };
+            if (!context) return payload;
+            return {
+                ...payload,
+                ...context
+            };
+        }
+        function captureException(error, context) {
+            try {
+                const cfg = getCurrentConfig();
+                if (!(null == cfg ? void 0 : cfg.enabled) || !cfg.apiKey) return;
+                const payload = buildPayloadFromError(error, cfg, context);
+                sendErrorEvent(payload, cfg);
+            } catch  {}
+        }
+        let errorListener = null;
+        let rejectionListener = null;
+        function getBrowserWindow() {
+            try {
+                const win = globalThis.window;
+                if (win && 'function' == typeof win.addEventListener) return win;
+            } catch  {}
+            return null;
+        }
+        function unregisterGlobalHandlers() {
+            const win = getBrowserWindow();
+            if (!win) return;
+            if (errorListener) {
+                win.removeEventListener('error', errorListener);
+                errorListener = null;
+            }
+            if (rejectionListener) {
+                win.removeEventListener('unhandledrejection', rejectionListener);
+                rejectionListener = null;
+            }
+        }
+        function registerGlobalHandlers() {
+            const win = getBrowserWindow();
+            if (!win) return;
+            errorListener = (event)=>{
+                try {
+                    const e = event;
+                    const target = e.target;
+                    if (target && target !== win && !e.error) return;
+                    const error = e.error instanceof Error ? e.error : new Error(e.message || 'Unknown error');
+                    captureException(error);
+                } catch  {}
+            };
+            rejectionListener = (event)=>{
+                try {
+                    const reason = event.reason;
+                    captureException(reason);
+                } catch  {}
+            };
+            win.addEventListener('error', errorListener);
+            win.addEventListener('unhandledrejection', rejectionListener);
+        }
+        let currentConfig = null;
+        let warnedAboutMissingApiKey = false;
+        function normalizeEndpoint(endpoint) {
+            return (null == endpoint ? void 0 : endpoint.trim()) ? endpoint : '/api/error-events';
+        }
+        function init(config) {
+            const endpoint = normalizeEndpoint(null == config ? void 0 : config.endpoint);
+            const rawApiKey = null == config ? void 0 : config.apiKey;
+            const apiKey = 'string' == typeof rawApiKey ? rawApiKey.trim() : '';
+            const enabledFromConfig = (null == config ? void 0 : config.enabled) !== false;
+            unregisterGlobalHandlers();
+            if (!apiKey) {
+                if (!warnedAboutMissingApiKey) {
+                    warnedAboutMissingApiKey = true;
+                    console.warn('[bug-catcher sdk] init({ apiKey }) requires a non-blank apiKey; event sending will be disabled.');
+                }
+                currentConfig = {
+                    apiKey: '',
+                    endpoint,
+                    release: null == config ? void 0 : config.release,
+                    environment: null == config ? void 0 : config.environment,
+                    enabled: false
+                };
+                return;
+            }
+            currentConfig = {
+                apiKey,
+                endpoint,
+                release: null == config ? void 0 : config.release,
+                environment: null == config ? void 0 : config.environment,
+                enabled: enabledFromConfig
+            };
+            if (enabledFromConfig) registerGlobalHandlers();
+        }
+        function getCurrentConfig() {
+            return currentConfig;
+        }
+        return __webpack_exports__;
+    })());

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@retrace-kit/sdk",
+  "version": "0.0.0",
+  "description": "Retrace-kit SDK",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "browser": "./dist/umd/index.js",
+  "unpkg": "./dist/umd/index.js",
+  "jsdelivr": "./dist/umd/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "rslib build",
+    "dev": "rslib build --watch",
+    "test": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@rslib/core": "^0.22.1",
+    "@types/node": "^24.13.1",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=18.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}