@refactorlabs/recount 0.8.0 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,73 +1,148 @@
1
- # @refactorlabs/recount
1
+ <picture>
2
+ <source media="(prefers-color-scheme: dark)" srcset="https://recount.refactor.gg/logo.svg">
3
+ <img src="https://recount.refactor.gg/logo-light.svg" alt="Recount" height="40">
4
+ </picture>
2
5
 
3
- Application explainability for modern software. Recount captures the reasoning behind your application's decisions and presents it as an interactive timeline, making it easy for engineers, support teams, product managers, and business stakeholders to understand what happened - and why.
6
+ # Node.js SDK
4
7
 
5
- This is the Node.js SDK for [Recount](https://recount.refactor.gg).
8
+ [![npm](https://img.shields.io/npm/v/@refactorlabs/recount)](https://www.npmjs.com/package/@refactorlabs/recount)
9
+ [![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue)](LICENSE)
6
10
 
7
- **[Documentation](https://recount.refactor.gg/docs)**
11
+ The official Node.js SDK for [Recount](https://recount.refactor.gg). Recount records the steps behind each decision your software makes, including the data it fetched, the rules it applied and the model calls it made, and shows them as a timeline anyone can read.
8
12
 
9
- ## Install
13
+ - [Documentation](https://recount.refactor.gg/docs/node/getting-started)
14
+ - [API reference](https://recount.refactor.gg/docs/node/overview)
15
+ - [Dashboard](https://app.recount.refactor.gg)
16
+
17
+ ## Requirements
18
+
19
+ - Node.js 18 or later
20
+ - ES modules or CommonJS. TypeScript types are included.
21
+
22
+ ## Installation
10
23
 
11
24
  ```sh
12
25
  npm install @refactorlabs/recount
13
26
  ```
14
27
 
15
- ## Quick start
28
+ ## Configuration
29
+
30
+ The SDK reads its configuration from environment variables, so no setup code is needed:
16
31
 
17
- Wrap the function that makes a decision in `startTrace`, then add a span per step. No `RECOUNT_API_KEY`? All calls silently no-op, so it's safe to wire up before you have one.
32
+ | Variable | Description |
33
+ | --------------------- | ---------------------------------------------------------------------------- |
34
+ | `RECOUNT_API_KEY` | Your project's API key, from its **Settings** page. Required to send traces. |
35
+ | `RECOUNT_ENVIRONMENT` | Tags every trace with an environment, such as `Production`. |
36
+ | `RECOUNT_DEBUG` | Set to any non-empty value to log SDK activity to stdout. |
37
+
38
+ To configure it in code instead, call `init` once at startup:
18
39
 
19
40
  ```ts
20
41
  import recount from '@refactorlabs/recount';
21
42
 
22
- await recount.startTrace('Refund decision - ORDER-1042', async () => {
43
+ recount.init({
44
+ apiKey: process.env.RECOUNT_API_KEY,
45
+ environment: 'Production',
46
+ timeoutMs: 10_000
47
+ });
48
+ ```
49
+
50
+ See [all options](https://recount.refactor.gg/docs/node/traces#recountinitoptions).
51
+
52
+ ## Usage
53
+
54
+ Wrap the code that makes a decision in `startTrace`, and record each step that matters as a span:
55
+
56
+ ```ts
57
+ import recount from '@refactorlabs/recount';
58
+
59
+ await recount.startTrace('Refund decision', async () => {
60
+ recount.addMetadata({ 'Order ID': 'ORD-1042' });
61
+
23
62
  recount.addSpan('table', 'Refund rules', {
24
63
  output: recount
25
64
  .table()
26
65
  .fromRecords([
27
- { rule: 'Within 30 days', result: 'Pass' },
28
- { rule: 'Item not final sale', result: 'Pass' }
66
+ { Rule: 'Within 30 days', Result: 'Pass' },
67
+ { Rule: 'Item not final sale', Result: 'Pass' }
29
68
  ])
30
- .highlightRows((row) => (row.result === 'Pass' ? 'success' : 'danger'))
69
+ .highlightRows((row) => (row.Result === 'Pass' ? 'success' : 'danger'))
31
70
  .build()
32
71
  });
33
72
 
34
- recount.addSpan('json', 'Result', {
35
- output: { decision: 'approved', amount: '$42.00' }
73
+ recount.addSpan('json', 'Outcome', {
74
+ output: { decision: 'Approved', amount: 42 }
36
75
  });
37
76
  });
38
77
  ```
39
78
 
40
- That trace shows up in the [Recount dashboard](https://recount.refactor.gg) as a readable timeline - not a log dump - that a support agent or auditor can open and see exactly why the refund was approved.
79
+ The trace is sent when the callback finishes, and appears in the dashboard as a timeline of its steps. Trace names, span names, metadata and table columns are shown to readers as written, so use plain words.
80
+
81
+ Every method is also a named export:
82
+
83
+ ```ts
84
+ import { startTrace, addSpan } from '@refactorlabs/recount';
85
+ ```
86
+
87
+ ### Span types
88
+
89
+ | Type | For |
90
+ | --------- | -------------------------------------------------------------- |
91
+ | `json` | Any structured value, such as a quote or a score |
92
+ | `table` | Rows of data, built with `recount.table()` |
93
+ | `chart` | Line, bar, pie or scatter charts, built with `recount.chart()` |
94
+ | `http` | Outbound requests, usually recorded with `recount.fetch()` |
95
+ | `db` | SQL or NoSQL queries |
96
+ | `llm` | Model calls: prompt, response and token counts |
97
+ | `message` | A line of text, as info, a warning or an error |
98
+ | `image` | An image shown inline |
99
+
100
+ Use `recount.addGroup()` to collect related spans under one collapsible heading, and `recount.addAlert()` to flag a step as a warning or error.
41
101
 
42
102
  ## Integrations
43
103
 
44
- Wrap a client once and every call through it is traced automatically - don't hand-write spans for these:
104
+ Wrap a client once and its calls are recorded as spans automatically:
105
+
106
+ | Client | Import | Records |
107
+ | ------------------- | --------------------------------- | ------------------------------------------------ |
108
+ | `fetch` | `recount.fetch()` | Request and response |
109
+ | `@anthropic-ai/sdk` | `@refactorlabs/recount/anthropic` | `messages.create()`, including streaming |
110
+ | `openai` | `@refactorlabs/recount/openai` | `chat.completions.create()`, including streaming |
111
+ | `mongodb` | `@refactorlabs/recount/mongodb` | Collection operations and cursors |
45
112
 
46
113
  ```ts
114
+ import Anthropic from '@anthropic-ai/sdk';
47
115
  import { wrapAnthropic } from '@refactorlabs/recount/anthropic';
48
- import { wrapOpenAI } from '@refactorlabs/recount/openai';
49
- import { wrapCollection } from '@refactorlabs/recount/mongodb';
50
116
 
51
117
  const anthropic = wrapAnthropic(new Anthropic());
52
- const openai = wrapOpenAI(new OpenAI());
53
- const users = wrapCollection(db.collection('users')); // findOne, find, updateOne, aggregate, ...
54
118
  ```
55
119
 
56
- See the [full docs](https://recount.refactor.gg/docs) for span types, the `table()`/`chart()` builders, redaction, alerts, and `addGroup` for bounded lists.
120
+ Each integration uses the client already installed in your project. They're optional peer dependencies.
57
121
 
58
- ## Claude Code skill
122
+ ## Redaction
59
123
 
60
- This package ships a [Claude Code](https://claude.com/claude-code) Skill that finds decision logic
61
- in your codebase (pricing, billing, discounts, access control, LLM calls) and instruments it with
62
- Recount automatically. To use it in your project:
124
+ Sensitive values are removed inside your application, before anything is sent:
63
125
 
64
- ```sh
65
- mkdir -p .claude/skills/recount-instrument
66
- cp node_modules/@refactorlabs/recount/recount-instrument/SKILL.md .claude/skills/recount-instrument/
126
+ ```ts
127
+ recount.addSpan('json', 'Applicant', {
128
+ output: applicant,
129
+ redact: ['taxFileNumber', 'bank.accountNumber']
130
+ });
67
131
  ```
68
132
 
69
- Then in Claude Code, ask it to "add recount tracing to this" or "instrument this with recount".
133
+ `Authorization`, cookie and API key headers on HTTP spans are always redacted. See [Redaction](https://recount.refactor.gg/docs/node/redaction).
134
+
135
+ ## Reliability
136
+
137
+ Recording a trace never changes how your code behaves:
138
+
139
+ - Without an API key, the SDK logs one warning and every call does nothing.
140
+ - The SDK doesn't throw errors of its own, and errors from your code pass through unchanged.
141
+ - A trace that can't be sent, because of a network error, a rejected payload or a timeout, is dropped. Set `RECOUNT_DEBUG` to see why.
142
+ - Rate-limited uploads are retried up to twice, within `timeoutMs` (30 seconds by default).
143
+
144
+ See [Limits](https://recount.refactor.gg/docs/limits) for payload and rate limits.
70
145
 
71
- ## License
146
+ ## Licence
72
147
 
73
- MIT
148
+ [MIT](LICENSE)
package/dist/index.cjs CHANGED
@@ -562,6 +562,13 @@ var NOOP_RESULT2 = { traceId: "" };
562
562
  var MAX_RETRIES = 2;
563
563
  var BASE_RETRY_MS = 1e3;
564
564
  var MAX_RETRY_DELAY_MS = 6e4;
565
+ var DEFAULT_TIMEOUT_MS = 3e4;
566
+ var MAX_TIMEOUT_MS = 2 ** 31 - 1;
567
+ function resolveTimeoutMs(value) {
568
+ if (typeof value !== "number" || isNaN(value) || value <= 0)
569
+ return DEFAULT_TIMEOUT_MS;
570
+ return Math.min(value, MAX_TIMEOUT_MS);
571
+ }
565
572
  function retryDelayMs(res, attempt) {
566
573
  const header = res.headers.get("retry-after");
567
574
  if (header) {
@@ -574,17 +581,19 @@ function retryDelayMs(res, attempt) {
574
581
  }
575
582
  return BASE_RETRY_MS * 2 ** (attempt - 1);
576
583
  }
577
- var _apiKey, _apiUrl, _environment2, _disabled2, _log2;
584
+ var _apiKey, _apiUrl, _environment2, _disabled2, _timeoutMs, _log2;
578
585
  var Recount = class {
579
586
  constructor(options = {}) {
580
587
  __privateAdd(this, _apiKey);
581
588
  __privateAdd(this, _apiUrl);
582
589
  __privateAdd(this, _environment2);
583
590
  __privateAdd(this, _disabled2);
591
+ __privateAdd(this, _timeoutMs);
584
592
  __privateAdd(this, _log2);
585
593
  const debug = options.debug ?? !!process.env.RECOUNT_DEBUG;
586
594
  __privateSet(this, _log2, debug ? (msg) => console.log(`[recount] ${msg}`) : () => {
587
595
  });
596
+ __privateSet(this, _timeoutMs, resolveTimeoutMs(options.timeoutMs));
588
597
  const apiKey = options.apiKey ?? process.env.RECOUNT_API_KEY;
589
598
  if (!apiKey) {
590
599
  console.warn("Recount: no API key found - tracing disabled.");
@@ -626,33 +635,61 @@ var Recount = class {
626
635
  "Content-Type": "application/json",
627
636
  "x-api-key": __privateGet(this, _apiKey)
628
637
  };
629
- for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
630
- try {
631
- const res = await globalThis.fetch(`${__privateGet(this, _apiUrl)}/ingest`, {
632
- method: "POST",
633
- headers,
634
- body
635
- });
636
- if (res.status === 429 && attempt < MAX_RETRIES) {
637
- const delay = retryDelayMs(res, attempt + 1);
638
- __privateGet(this, _log2).call(this, `429 rate limited attempt=${attempt + 1}/${MAX_RETRIES + 1} retrying in ${delay}ms`);
639
- await res.body?.cancel().catch(() => {
638
+ const deadline = Date.now() + __privateGet(this, _timeoutMs);
639
+ const controller = new AbortController();
640
+ const timer = setTimeout(() => controller.abort(), __privateGet(this, _timeoutMs));
641
+ try {
642
+ for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
643
+ try {
644
+ const res = await globalThis.fetch(`${__privateGet(this, _apiUrl)}/ingest`, {
645
+ method: "POST",
646
+ headers,
647
+ body,
648
+ signal: controller.signal
640
649
  });
641
- await new Promise((r) => setTimeout(r, delay));
642
- continue;
643
- }
644
- if (!res.ok) {
645
- const text = await res.text().catch(() => res.statusText);
646
- __privateGet(this, _log2).call(this, `ingest error status=${res.status} message=${text}`);
650
+ if (res.status === 429 && attempt < MAX_RETRIES) {
651
+ const delay = retryDelayMs(res, attempt + 1);
652
+ await res.body?.cancel().catch(() => {
653
+ });
654
+ if (Date.now() + delay >= deadline) {
655
+ __privateGet(this, _log2).call(this, `429 rate limited attempt=${attempt + 1}/${MAX_RETRIES + 1} retry in ${delay}ms would exceed timeout=${__privateGet(this, _timeoutMs)}ms, dropping trace`);
656
+ return NOOP_RESULT2;
657
+ }
658
+ __privateGet(this, _log2).call(this, `429 rate limited attempt=${attempt + 1}/${MAX_RETRIES + 1} retrying in ${delay}ms`);
659
+ await new Promise((r) => setTimeout(r, delay));
660
+ continue;
661
+ }
662
+ if (!res.ok) {
663
+ const text = await res.text().catch(() => res.statusText);
664
+ __privateGet(this, _log2).call(this, `ingest error status=${res.status} message=${text}`);
665
+ return NOOP_RESULT2;
666
+ }
667
+ let json;
668
+ try {
669
+ json = await res.json();
670
+ } catch (err) {
671
+ if (!(err instanceof SyntaxError)) throw err;
672
+ __privateGet(this, _log2).call(this, `ingest error: invalid JSON response (${err.message})`);
673
+ return NOOP_RESULT2;
674
+ }
675
+ const traceId = json?.data?.trace?.id;
676
+ if (typeof traceId !== "string") {
677
+ __privateGet(this, _log2).call(this, `ingest error: unexpected response ${JSON.stringify(json)?.slice(0, 200)}`);
678
+ return NOOP_RESULT2;
679
+ }
680
+ __privateGet(this, _log2).call(this, `ingested traceId=${traceId}`);
681
+ return { traceId };
682
+ } catch (err) {
683
+ if (controller.signal.aborted) {
684
+ __privateGet(this, _log2).call(this, `ingest timed out after ${__privateGet(this, _timeoutMs)}ms`);
685
+ } else {
686
+ __privateGet(this, _log2).call(this, `ingest failed (network error): ${err instanceof Error ? err.message : String(err)}`);
687
+ }
647
688
  return NOOP_RESULT2;
648
689
  }
649
- const json = await res.json();
650
- __privateGet(this, _log2).call(this, `ingested traceId=${json.data.trace.id}`);
651
- return { traceId: json.data.trace.id };
652
- } catch (err) {
653
- __privateGet(this, _log2).call(this, `ingest failed (network error): ${err instanceof Error ? err.message : String(err)}`);
654
- return NOOP_RESULT2;
655
690
  }
691
+ } finally {
692
+ clearTimeout(timer);
656
693
  }
657
694
  return NOOP_RESULT2;
658
695
  }
@@ -661,6 +698,7 @@ _apiKey = new WeakMap();
661
698
  _apiUrl = new WeakMap();
662
699
  _environment2 = new WeakMap();
663
700
  _disabled2 = new WeakMap();
701
+ _timeoutMs = new WeakMap();
664
702
  _log2 = new WeakMap();
665
703
  var _key = /* @__PURE__ */ Symbol.for("@refactorlabs/recount.storage");
666
704
  var _nameKey = /* @__PURE__ */ Symbol.for("@refactorlabs/recount.spanName");
@@ -1136,7 +1174,26 @@ var recount = {
1136
1174
  };
1137
1175
  var index_default = recount;
1138
1176
 
1177
+ exports.REDACTED = REDACTED;
1178
+ exports.Recount = Recount;
1179
+ exports.RecountError = RecountError;
1139
1180
  exports.SpanGroup = SpanGroup;
1181
+ exports.addAlert = addAlert;
1182
+ exports.addGroup = addGroup;
1183
+ exports.addMessage = addMessage;
1184
+ exports.addMetadata = addMetadata;
1185
+ exports.addSpan = addSpan;
1186
+ exports.chart = chart;
1187
+ exports.chartFromRecords = chartFromRecords;
1140
1188
  exports.default = index_default;
1189
+ exports.fetch = fetch;
1190
+ exports.init = init;
1191
+ exports.named = named;
1192
+ exports.spanCell = spanCell;
1193
+ exports.startTrace = startTrace;
1194
+ exports.table = table;
1195
+ exports.tableFromObject = tableFromObject;
1196
+ exports.tableFromRecords = tableFromRecords;
1197
+ exports.tableSections = tableSections;
1141
1198
  //# sourceMappingURL=index.cjs.map
1142
1199
  //# sourceMappingURL=index.cjs.map