TraceBox SDK

Lightweight, production-grade JavaScript & TypeScript SDK for TraceBox — remote debugging and runtime capture platform.

Temporarily drop TraceBox into any backend or full-stack application to capture arbitrary runtime data, nested structures, circular objects, and errors, and inspect them in real time on your TraceBox Console.

Installation

npm install tracebox
# or
yarn add tracebox
# or
pnpm add tracebox
# or
bun add tracebox

Quick Start

import { TraceBox } from "tracebox";

// 1. Initialize with your project slug and API key
const trace = new TraceBox({
  projectSlug: "my-store",
  apiKey: "tb_xxxxxxxxxxxxxxxxxxxxxxxx"
});

// 2. Capture any runtime data into a named Box
const response = await fetch("https://api.example.com/checkout");
const data = await response.json();

await trace.capture(data, "affirm-issue-001");

All captures with the same box parameter ("affirm-issue-001") are grouped together under that Box in the web console.

Configuration Options

interface TraceBoxOptions {
  /** Required project slug */
  projectSlug: string;

  /** Required API key with tb_ prefix */
  apiKey: string;

  /** Optional base API URL (default: "https://api.tracebox.io") */
  baseUrl?: string;

  /** Optional request timeout in milliseconds (default: 5000ms) */
  timeoutMs?: number;

  /** If true, capture failures throw errors. Default false (failsafe) */
  strict?: boolean;
}

Local Development / Self-Hosted Server

const trace = new TraceBox({
  projectSlug: "my-store",
  apiKey: "tb_xxxxxxxxxxxxxxxxxxxxxxxx",
  baseUrl: "http://localhost:8080"
});

Labels & Metadata

You can optionally tag captures with a label and structured metadata:

await trace.capture(error, "checkout-debug", {
  label: "payment-gateway-timeout",
  metadata: {
    environment: "production",
    userId: "usr_9921",
    requestId: "req_88192a"
  }
});

Intelligent Serialization

TraceBox safely handles complex and non-standard JavaScript data without throwing or crashing host applications:

• Circular references: Cyclic graphs are marked safely as "[Circular]"
• Error objects: Preserves name, message, stack, and cause
• Axios responses: Serializes status, headers, data, and config cleanly without internal socket handles
• Deep nesting: Supports arbitrary nesting depths with zero artificial level caps
• Primitives & Dates: Serializes Date, BigInt, RegExp, null, undefined

const obj: any = { status: "pending" };
obj.self = obj;

// Safe: will not crash or cause infinite loops
await trace.capture(obj, "cyclic-test");

Reliability Guarantee

TraceBox is engineered to never impact your host application:

1. Lightweight & zero bloat: Minimal footprint, zero native runtime dependencies.
2. Never crashes host processes: If TraceBox is unreachable or times out, errors fail safely without unhandled promise rejections.
3. Non-blocking & fast: Efficient single HTTP POST request with strict timeouts.

License

MIT