@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 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)