@fixflow/sdk 0.1.0

package/README.md

@@ -0,0 +1,143 @@
+# FixFlow SDK
+
+Lightweight error capture SDK for Node.js and browser environments.
+
+## Install
+
+```bash
+npm install @fixflow/sdk
+```
+
+## Usage
+
+```ts
+import fixflow from "@fixflow/sdk";
+
+fixflow.init("PROJECT_KEY");
+```
+
+The SDK posts to the FixFlow cloud ingest URL by default. You do **not** need to pass an `endpoint` for normal use.
+
+The SDK auto-captures uncaught errors and unhandled promise rejections after initialization.
+
+## Usage by environment
+
+**API request tracking:** In Node.js, outbound HTTP monitoring uses Axios (`trackAxios`). In the browser you can use `trackFetch`, Axios, or both.
+
+### Browser / frontend
+
+Initialize in your client entry file (for example `main.ts` or `index.tsx`) **as early as possible** so startup errors are captured:
+
+```ts
+import fixflow from "@fixflow/sdk";
+
+fixflow.init("PROJECT_KEY", {
+  trackFetch: true, // optional: instruments window.fetch (browser only)
+});
+```
+
+Use `captureError` or `capture` in `catch` blocks for handled errors (see [Capturing errors manually](#capturing-errors-manually)).
+
+`trackFetch` instruments **`window.fetch` only** and does not patch Node’s global `fetch`. For all options, see [`init` Options](#init-options) below.
+
+### React
+
+Prefer calling `init` from your **entry file** before `createRoot(...).render(...)` when the project key is available there.
+
+If the key only exists on the client (for example a `NEXT_PUBLIC_*` variable), use a **once-only** `useEffect` with an empty dependency array. Do **not** call `init` in the component render body:
+
+```tsx
+import { useEffect } from "react";
+import fixflow from "@fixflow/sdk";
+
+export function FixFlowInit() {
+  useEffect(() => {
+    const key = process.env.NEXT_PUBLIC_FIXFLOW_PROJECT_KEY;
+    if (key) {
+      fixflow.init(key, { trackFetch: true });
+    }
+  }, []);
+
+  return null;
+}
+```
+
+Mount that component once near the root of your tree. Next.js App Router users can wrap it in a small client component used from the root layout.
+
+### Node.js
+
+Call `init` **once at process startup** (for example at the top of `server.ts`, before creating or listening on your HTTP server):
+
+```ts
+import axios from "axios";
+import fixflow from "@fixflow/sdk";
+
+fixflow.init("PROJECT_KEY", {
+  trackAxios: true,
+  axios,
+  slowThreshold: 1000,
+});
+```
+
+Do **not** rely on `trackFetch` for Node in the current SDK; use `trackAxios` and pass the same `axios` instance your app uses. See [Axios option (important)](#axios-option-important).
+
+## `init` Options
+
+Typical setup combines browser `trackFetch` with server Axios tracking and passes your app's Axios instance when you use Axios on the server:
+
+```ts
+import axios from "axios";
+import fixflow from "@fixflow/sdk";
+
+fixflow.init("PROJECT_KEY", {
+  trackFetch: true,
+  trackAxios: true,
+  slowThreshold: 1000,
+  axios,
+});
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `trackFetch` | `boolean` | `false` | Enables API tracking for `window.fetch` (browser). |
+| `trackAxios` | `boolean` | `false` | Enables API tracking for Axios via interceptors. |
+| `slowThreshold` | `number` | `1000` | Request duration threshold in ms used for "slow API" events. Values below `0` are clamped to `0`. |
+| `axios` | `AxiosStatic` | `undefined` | Axios instance to instrument. Recommended for Node apps when `trackAxios` is enabled. |
+
+At init, the SDK requests `GET …/sdk/config/:projectKey` on the same API host as ingest (for the default cloud URL, that is `https://api.fixflow.ai/sdk/config/:projectKey`). It applies `apiTrackingEnabled` and `trackInDevelopment` from the project when the response is valid, and otherwise falls back to your `trackFetch` / `trackAxios` flags.
+
+
+## Axios option (important)
+
+In Node/npm projects, `@fixflow/sdk` can have a different installed Axios copy than your app.
+If that happens, interceptors attached by the SDK will not see requests made by your app's Axios import.
+
+Pass your app's Axios instance so API events are tracked from the client your code actually uses:
+
+```ts
+import axios from "axios";
+import fixflow from "@fixflow/sdk";
+
+fixflow.init("PROJECT_KEY", {
+  trackAxios: true,
+  axios,
+});
+```
+
+## Capturing errors manually
+
+```ts
+try {
+  throw new Error("Something failed");
+} catch (err) {
+  fixflow.captureError(err as Error);
+}
+```
+
+You can also call the async `capture` method directly:
+
+```ts
+import fixflow from "@fixflow/sdk";
+
+await fixflow.capture(new Error("Manual capture"));
+```

package/dist/capture.d.ts

@@ -0,0 +1,9 @@
+import type { Runtime } from "./types.js";
+export declare function isNode(): boolean;
+export declare function getRuntime(): Runtime;
+export declare function extractFile(stack?: string): string | undefined;
+export declare function extractLine(stack?: string): number | undefined;
+export declare function capture(error: Error): Promise<void>;
+export declare function setupApiTracking(): void;
+export declare function setupGlobalHandlers(): void;
+export declare function registerAutoCapture(): void;

package/dist/capture.js

@@ -0,0 +1,396 @@
+import { sendError } from "./sender.js";
+import { getSlowThreshold, getTrackingAxios, shouldTrackAxios, shouldTrackFetch } from "./core.js";
+import axios from "axios";
+let autoCaptureRegistered = false;
+let fetchTrackingRegistered = false;
+let axiosTrackingRegistered = false;
+function isReactNative() {
+    try {
+        const nav = globalThis.navigator;
+        return nav?.product === "ReactNative";
+    }
+    catch {
+        return false;
+    }
+}
+export function isNode() {
+    try {
+        const nodeProcess = globalThis.process;
+        return typeof nodeProcess !== "undefined" && nodeProcess.release?.name === "node";
+    }
+    catch {
+        return false;
+    }
+}
+export function getRuntime() {
+    try {
+        if (isReactNative()) {
+            return "react-native";
+        }
+        return isNode() ? "node" : "browser";
+    }
+    catch {
+        return "node";
+    }
+}
+export function extractFile(stack) {
+    try {
+        if (!stack) {
+            return undefined;
+        }
+        const match = stack.match(/(?:at\s+.*\()?(.+):\d+:\d+\)?/);
+        return match?.[1];
+    }
+    catch {
+        return undefined;
+    }
+}
+export function extractLine(stack) {
+    try {
+        if (!stack) {
+            return undefined;
+        }
+        const match = stack.match(/:(\d+):\d+\)?/);
+        if (!match?.[1]) {
+            return undefined;
+        }
+        const line = Number(match[1]);
+        return Number.isFinite(line) ? line : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function getEnv() {
+    try {
+        const nodeProcess = globalThis.process;
+        if (nodeProcess?.env?.NODE_ENV) {
+            return nodeProcess.env.NODE_ENV;
+        }
+        if (isNode()) {
+            return "production";
+        }
+    }
+    catch {
+        // noop
+    }
+    return "unknown";
+}
+function getNodeVersion() {
+    try {
+        const nodeProcess = globalThis.process;
+        return nodeProcess?.version;
+    }
+    catch {
+        return undefined;
+    }
+}
+function getNodePlatform() {
+    try {
+        const nodeProcess = globalThis.process;
+        return nodeProcess?.platform;
+    }
+    catch {
+        return undefined;
+    }
+}
+function markCaptured(error) {
+    try {
+        if (error.__fixflow) {
+            return true;
+        }
+        error.__fixflow = true;
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+function normalizeError(input) {
+    try {
+        if (input instanceof Error) {
+            return input;
+        }
+        return new Error(typeof input === "string" ? input : "Unknown error");
+    }
+    catch {
+        return new Error("Unknown error");
+    }
+}
+function normalizeRejectionReason(reason) {
+    try {
+        if (reason instanceof Error) {
+            return reason;
+        }
+        return new Error(JSON.stringify(reason));
+    }
+    catch {
+        return new Error("Unhandled promise rejection");
+    }
+}
+export async function capture(error) {
+    try {
+        const safeError = normalizeError(error);
+        if (markCaptured(safeError)) {
+            return;
+        }
+        await sendError({
+            message: safeError.message || "Unknown error",
+            stack: safeError.stack,
+            file: extractFile(safeError.stack),
+            line: extractLine(safeError.stack),
+            runtime: getRuntime(),
+            env: getEnv(),
+            nodeVersion: isNode() ? getNodeVersion() : undefined,
+            platform: isNode() ? getNodePlatform() : undefined,
+            type: "error",
+        });
+    }
+    catch {
+        // SDK should never throw
+    }
+}
+async function sendApiEvent(data) {
+    try {
+        await sendError({
+            message: data.message,
+            runtime: getRuntime(),
+            env: getEnv(),
+            nodeVersion: isNode() ? getNodeVersion() : undefined,
+            platform: isNode() ? getNodePlatform() : undefined,
+            type: "api",
+            url: data.url,
+            status: data.status,
+            duration: data.duration,
+        });
+    }
+    catch {
+        // SDK should never throw
+    }
+}
+export function setupApiTracking() {
+    try {
+        if (shouldTrackFetch() && !fetchTrackingRegistered && typeof window !== "undefined" && typeof window.fetch === "function") {
+            fetchTrackingRegistered = true;
+            const originalFetch = window.fetch.bind(window);
+            window.fetch = async (...args) => {
+                const start = Date.now();
+                let requestUrl = "";
+                try {
+                    const input = args[0];
+                    requestUrl = typeof input === "string" ? input : input instanceof Request ? input.url : "";
+                }
+                catch {
+                    // noop
+                }
+                try {
+                    const response = await originalFetch(...args);
+                    const duration = Date.now() - start;
+                    const threshold = getSlowThreshold();
+                    if (!response.ok || duration > threshold) {
+                        void sendApiEvent({
+                            message: !response.ok ? "API request failed" : "API request slow",
+                            url: requestUrl,
+                            status: response.status,
+                            duration,
+                        });
+                    }
+                    return response;
+                }
+                catch (error) {
+                    const duration = Date.now() - start;
+                    void sendApiEvent({
+                        message: "API request error",
+                        url: requestUrl,
+                        duration,
+                    });
+                    throw error;
+                }
+            };
+        }
+        if (shouldTrackAxios() && !axiosTrackingRegistered) {
+            axiosTrackingRegistered = true;
+            const axiosClient = getTrackingAxios() ?? axios;
+            axiosClient.interceptors.request.use((config) => {
+                try {
+                    const meta = config.__fixflowMeta || {
+                        startTime: Date.now(),
+                    };
+                    config.__fixflowMeta = meta;
+                }
+                catch {
+                    // noop
+                }
+                return config;
+            });
+            axiosClient.interceptors.response.use((response) => {
+                try {
+                    const startTime = response.config.__fixflowMeta?.startTime ||
+                        Date.now();
+                    const duration = Date.now() - startTime;
+                    const threshold = getSlowThreshold();
+                    let requestUrl = "";
+                    try {
+                        requestUrl = axiosClient.getUri(response.config);
+                    }
+                    catch {
+                        requestUrl = response.config?.url || "";
+                    }
+                    if (!response.status || response.status >= 400 || duration > threshold) {
+                        void sendApiEvent({
+                            message: response.status >= 400 ? "API request failed" : "API request slow",
+                            url: requestUrl || response.config?.url,
+                            status: response.status,
+                            duration,
+                        });
+                    }
+                }
+                catch {
+                    // noop
+                }
+                return response;
+            }, (error) => {
+                try {
+                    const config = (error?.config || {});
+                    const startTime = config.__fixflowMeta?.startTime || Date.now();
+                    const duration = Date.now() - startTime;
+                    let requestUrl = "";
+                    try {
+                        requestUrl = axiosClient.getUri(config);
+                    }
+                    catch {
+                        requestUrl = config.url || "";
+                    }
+                    void sendApiEvent({
+                        message: "API request error",
+                        url: requestUrl || config.url,
+                        status: error?.response?.status,
+                        duration,
+                    });
+                }
+                catch {
+                    // noop
+                }
+                return Promise.reject(error);
+            });
+        }
+    }
+    catch {
+        // SDK should never throw
+    }
+}
+export function setupGlobalHandlers() {
+    try {
+        if (autoCaptureRegistered) {
+            return;
+        }
+        autoCaptureRegistered = true;
+        const nodeProcess = globalThis.process;
+        if (isNode() && typeof nodeProcess?.on === "function") {
+            nodeProcess.on("uncaughtException", (error) => {
+                try {
+                    void capture(normalizeError(error));
+                }
+                catch {
+                    // noop
+                }
+            });
+            nodeProcess.on("unhandledRejection", (reason) => {
+                try {
+                    void capture(normalizeRejectionReason(reason));
+                }
+                catch {
+                    // noop
+                }
+            });
+            nodeProcess.on("beforeExit", (code) => {
+                try {
+                    console.debug("[FixFlow] process beforeExit", code);
+                }
+                catch {
+                    // noop
+                }
+            });
+            nodeProcess.on("exit", (code) => {
+                try {
+                    console.debug("[FixFlow] process exit", code);
+                }
+                catch {
+                    // noop
+                }
+            });
+        }
+        if (isReactNative()) {
+            const rnGlobal = globalThis;
+            if (typeof rnGlobal.ErrorUtils?.setGlobalHandler === "function") {
+                const previousHandler = typeof rnGlobal.ErrorUtils.getGlobalHandler === "function"
+                    ? rnGlobal.ErrorUtils.getGlobalHandler()
+                    : undefined;
+                rnGlobal.ErrorUtils.setGlobalHandler((error, isFatal) => {
+                    try {
+                        void capture(normalizeError(error));
+                    }
+                    catch {
+                        // noop
+                    }
+                    try {
+                        if (typeof previousHandler === "function") {
+                            previousHandler(error, isFatal);
+                        }
+                    }
+                    catch {
+                        // noop
+                    }
+                });
+            }
+            return;
+        }
+        if (typeof window !== "undefined") {
+            const previousOnError = window.onerror;
+            const previousUnhandledRejection = window.onunhandledrejection;
+            window.onerror = (message, source, lineno, _colno, error) => {
+                try {
+                    const normalized = normalizeError(error ?? message);
+                    if (!normalized.stack && source) {
+                        normalized.stack = `at ${source}:${lineno || 0}:0`;
+                    }
+                    void capture(normalized);
+                }
+                catch {
+                    // noop
+                }
+                try {
+                    if (typeof previousOnError === "function") {
+                        return previousOnError(message, source, lineno, _colno, error);
+                    }
+                }
+                catch {
+                    // noop
+                }
+                return false;
+            };
+            window.onunhandledrejection = (event) => {
+                try {
+                    void capture(normalizeRejectionReason(event.reason));
+                }
+                catch {
+                    // noop
+                }
+                try {
+                    if (typeof previousUnhandledRejection === "function") {
+                        previousUnhandledRejection.call(window, event);
+                    }
+                }
+                catch {
+                    // noop
+                }
+            };
+        }
+    }
+    catch {
+        // SDK should never throw
+    }
+}
+export function registerAutoCapture() {
+    setupGlobalHandlers();
+}

package/dist/core.d.ts

@@ -0,0 +1,11 @@
+import type { AxiosStatic } from "axios";
+import type { InitOptions } from "./types.js";
+export declare function initConfig(key: string, options?: InitOptions): void;
+export declare function getTrackingAxios(): AxiosStatic | undefined;
+export declare function getProjectKey(): string;
+export declare function getEndpoint(): string;
+export declare function isInitialized(): boolean;
+export declare function shouldTrackFetch(): boolean;
+export declare function shouldTrackAxios(): boolean;
+export declare function getSlowThreshold(): number;
+export declare function syncRemoteApiTrackingConfig(): Promise<void>;

package/dist/core.js

@@ -0,0 +1,135 @@
+const DEFAULT_ENDPOINT = "https://api.tryfixflow.com/sdk/error";
+const DEFAULT_SLOW_THRESHOLD = 1000;
+let projectKey = "";
+let endpoint = DEFAULT_ENDPOINT;
+let trackFetch = false;
+let trackAxios = false;
+let slowThreshold = DEFAULT_SLOW_THRESHOLD;
+let trackingAxios;
+let remoteApiTrackingEnabled = null;
+let remoteTrackInDevelopment = false;
+export function initConfig(key, options) {
+    try {
+        if (typeof key !== "string" || key.trim() === "") {
+            return;
+        }
+        projectKey = key;
+        endpoint = options?.endpoint || DEFAULT_ENDPOINT;
+        trackFetch = Boolean(options?.trackFetch);
+        trackAxios = Boolean(options?.trackAxios);
+        slowThreshold =
+            typeof options?.slowThreshold === "number" && Number.isFinite(options.slowThreshold)
+                ? Math.max(0, options.slowThreshold)
+                : DEFAULT_SLOW_THRESHOLD;
+        trackingAxios = options?.axios;
+    }
+    catch {
+        // SDK should never throw
+    }
+}
+export function getTrackingAxios() {
+    try {
+        return trackingAxios;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function getProjectKey() {
+    try {
+        return projectKey;
+    }
+    catch {
+        return "";
+    }
+}
+export function getEndpoint() {
+    try {
+        return endpoint || DEFAULT_ENDPOINT;
+    }
+    catch {
+        return DEFAULT_ENDPOINT;
+    }
+}
+export function isInitialized() {
+    try {
+        return Boolean(projectKey);
+    }
+    catch {
+        return false;
+    }
+}
+export function shouldTrackFetch() {
+    try {
+        const enabled = remoteApiTrackingEnabled !== null ? remoteApiTrackingEnabled : trackFetch;
+        if (!enabled)
+            return false;
+        if (isDevelopmentEnvironment() && !remoteTrackInDevelopment)
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function shouldTrackAxios() {
+    try {
+        const enabled = remoteApiTrackingEnabled !== null ? remoteApiTrackingEnabled : trackAxios;
+        if (!enabled)
+            return false;
+        if (isDevelopmentEnvironment() && !remoteTrackInDevelopment)
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function getSlowThreshold() {
+    try {
+        return slowThreshold;
+    }
+    catch {
+        return DEFAULT_SLOW_THRESHOLD;
+    }
+}
+function getSdkConfigEndpoint() {
+    const base = getEndpoint().replace(/\/+$/, "");
+    if (base.endsWith("/sdk/error")) {
+        const suffix = "/sdk/error";
+        return `${base.slice(0, -suffix.length)}/sdk/config`;
+    }
+    return `${base}/config`;
+}
+export async function syncRemoteApiTrackingConfig() {
+    try {
+        const key = getProjectKey();
+        if (!key)
+            return;
+        const configUrl = `${getSdkConfigEndpoint()}/${encodeURIComponent(key)}`;
+        const response = await fetch(configUrl, { method: "GET" });
+        if (!response.ok)
+            return;
+        const data = (await response.json());
+        if (typeof data?.apiTrackingEnabled === "boolean") {
+            remoteApiTrackingEnabled = data.apiTrackingEnabled;
+        }
+        if (typeof data?.trackInDevelopment === "boolean") {
+            remoteTrackInDevelopment = data.trackInDevelopment;
+        }
+    }
+    catch {
+        // SDK should never throw
+    }
+}
+function isDevelopmentEnvironment() {
+    try {
+        const processObj = globalThis.process;
+        const env = processObj?.env || {};
+        const value = env.ENVIRONMENT || env.NODE_ENV || "";
+        return String(value).toLowerCase() === "development";
+    }
+    catch {
+        return false;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { capture } from "./capture.js";
+import type { InitOptions } from "./types.js";
+export declare function init(projectKey: string, options?: InitOptions): void;
+export { capture };
+export declare function captureError(error: Error): void;
+declare const fixflow: {
+    init: typeof init;
+    capture: typeof capture;
+    captureError: typeof captureError;
+};
+export default fixflow;

package/dist/index.js

@@ -0,0 +1,29 @@
+import { initConfig, syncRemoteApiTrackingConfig } from "./core.js";
+import { capture, registerAutoCapture, setupApiTracking } from "./capture.js";
+export function init(projectKey, options) {
+    try {
+        initConfig(projectKey, options);
+        registerAutoCapture();
+        void syncRemoteApiTrackingConfig().finally(() => {
+            setupApiTracking();
+        });
+    }
+    catch {
+        // SDK should never throw
+    }
+}
+export { capture };
+export function captureError(error) {
+    try {
+        void capture(error);
+    }
+    catch {
+        // SDK should never throw
+    }
+}
+const fixflow = {
+    init,
+    capture,
+    captureError,
+};
+export default fixflow;

package/dist/sender.d.ts

@@ -0,0 +1,2 @@
+import type { ErrorPayload } from "./types.js";
+export declare function sendError(payload: Omit<ErrorPayload, "projectKey">): Promise<void>;

package/dist/sender.js

@@ -0,0 +1,32 @@
+import axios from "axios";
+import { getEndpoint, getProjectKey, isInitialized } from "./core.js";
+export async function sendError(payload) {
+    try {
+        if (!isInitialized()) {
+            return;
+        }
+        const key = getProjectKey();
+        const endpoint = getEndpoint();
+        if (!key || !endpoint) {
+            return;
+        }
+        await axios.post(endpoint, {
+            projectKey: key,
+            message: payload.message,
+            stack: payload.stack,
+            file: payload.file,
+            line: payload.line,
+            runtime: payload.runtime,
+            env: payload.env,
+            nodeVersion: payload.nodeVersion,
+            platform: payload.platform,
+            type: payload.type,
+            url: payload.url,
+            status: payload.status,
+            duration: payload.duration,
+        });
+    }
+    catch {
+        // Silent fail by design
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,33 @@
+import type { AxiosStatic } from "axios";
+export interface InitOptions {
+    /** Override ingest URL. Defaults to `https://api.fixflow.ai/sdk/error`. Only set for self-hosted APIs. */
+    endpoint?: string;
+    trackFetch?: boolean;
+    trackAxios?: boolean;
+    slowThreshold?: number;
+    /**
+     * Your application's `axios` import. Required in Node when `trackAxios` is true:
+     * npm often installs a separate `axios` copy inside `@fixflow/sdk`, so interceptors
+     * on the SDK's default axios would not see requests made with your app's axios.
+     */
+    axios?: AxiosStatic;
+}
+export type Runtime = "node" | "browser" | "react-native";
+export interface ErrorPayload {
+    projectKey: string;
+    message: string;
+    stack?: string;
+    file?: string;
+    line?: number;
+    runtime: Runtime;
+    env: string;
+    nodeVersion?: string;
+    platform?: string;
+    type?: "error" | "api";
+    url?: string;
+    status?: number;
+    duration?: number;
+}
+export type FixflowError = Error & {
+    __fixflow?: boolean;
+};

package/dist/types.js

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

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@fixflow/sdk",
+  "version": "0.1.0",
+  "description": "FixFlow SDK for error capture",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "license": "MIT",
+  "type": "module",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "axios": "^1.13.0"
+  },
+  "peerDependencies": {
+    "axios": ">=1.6.0"
+  },
+  "peerDependenciesMeta": {
+    "axios": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2"
+  }
+}