@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 +105 -30
- package/dist/index.cjs +81 -24
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +12 -2
- package/dist/index.d.ts +12 -2
- package/dist/index.js +63 -25
- package/dist/index.js.map +1 -1
- package/llms.md +32 -15
- package/package.json +4 -1
- package/recount-instrument/SKILL.md +5 -4
package/README.md
CHANGED
|
@@ -1,73 +1,148 @@
|
|
|
1
|
-
|
|
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
|
-
|
|
6
|
+
# Node.js SDK
|
|
4
7
|
|
|
5
|
-
|
|
8
|
+
[](https://www.npmjs.com/package/@refactorlabs/recount)
|
|
9
|
+
[](LICENSE)
|
|
6
10
|
|
|
7
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
28
|
+
## Configuration
|
|
29
|
+
|
|
30
|
+
The SDK reads its configuration from environment variables, so no setup code is needed:
|
|
16
31
|
|
|
17
|
-
|
|
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
|
-
|
|
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
|
-
{
|
|
28
|
-
{
|
|
66
|
+
{ Rule: 'Within 30 days', Result: 'Pass' },
|
|
67
|
+
{ Rule: 'Item not final sale', Result: 'Pass' }
|
|
29
68
|
])
|
|
30
|
-
.highlightRows((row) => (row.
|
|
69
|
+
.highlightRows((row) => (row.Result === 'Pass' ? 'success' : 'danger'))
|
|
31
70
|
.build()
|
|
32
71
|
});
|
|
33
72
|
|
|
34
|
-
recount.addSpan('json', '
|
|
35
|
-
output: { decision: '
|
|
73
|
+
recount.addSpan('json', 'Outcome', {
|
|
74
|
+
output: { decision: 'Approved', amount: 42 }
|
|
36
75
|
});
|
|
37
76
|
});
|
|
38
77
|
```
|
|
39
78
|
|
|
40
|
-
|
|
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
|
|
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
|
-
|
|
120
|
+
Each integration uses the client already installed in your project. They're optional peer dependencies.
|
|
57
121
|
|
|
58
|
-
##
|
|
122
|
+
## Redaction
|
|
59
123
|
|
|
60
|
-
|
|
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
|
-
```
|
|
65
|
-
|
|
66
|
-
|
|
126
|
+
```ts
|
|
127
|
+
recount.addSpan('json', 'Applicant', {
|
|
128
|
+
output: applicant,
|
|
129
|
+
redact: ['taxFileNumber', 'bank.accountNumber']
|
|
130
|
+
});
|
|
67
131
|
```
|
|
68
132
|
|
|
69
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
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
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
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
|