Getting started

1. Install

npm install @refactorlabs/because

2. Get an API key

3. Set your API key

Add BECAUSE_API_KEY to your environment. Because reads it automatically on first use - no init() call needed.

BECAUSE_API_KEY=your-api-key

If no key is found, the SDK disables itself silently with no errors thrown and no data sent.

If you need to override the API URL or enable debug logging, call because.init({ ... }) explicitly - see Traces & spans.

4. Wrap your first trace

await because.startTrace('My first trace', async () => {
  // your work here
  const result = { answer: 42 };
  because.setOutput(result);
});

That's it. The trace appears in the dashboard with its name, duration, and output.

5. Add spans

Spans record the individual steps your system takes. Add them anywhere inside a startTrace callback:

await because.startTrace(
  'Insurance claim - CLM-2024-03941',
  {
    metadata: { claimId: 'CLM-2024-03941' }
  },
  async () => {
    because.addSpan('db', 'Policy lookup', {
      metadata: { table: 'policies', queryType: 'sql' },
      input: {
        query: 'SELECT * FROM policies WHERE number = $1',
        params: ['POL-8821-AU']
      },
      output: { rows: 1 }
    });

    because.addSpan('table', 'Policy validation', {
      output: because
        .table()
        .fromRecords([
          { check: 'Policy active', result: 'Pass' },
          { check: 'Cover active at incident', result: 'Pass' },
          { check: 'Comprehensive cover', result: 'Pass' }
        ])
        .highlightRows((row) => (row.result === 'Pass' ? 'success' : 'danger'))
        .build()
    });

    because.setOutput({ claimId: 'CLM-2024-03941', decision: 'approved' });
  }
);

Now when a stakeholder asks "why was this claim approved?", the trace shows every step: what data was fetched, what rules ran, and what each decision produced.