@refactorlabs/recount 0.9.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.map +1 -1
- package/dist/index.d.cts +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js.map +1 -1
- package/llms.md +30 -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)
|