@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/llms.md CHANGED
@@ -9,11 +9,13 @@ import recount from '@refactorlabs/recount';
9
9
 
10
10
  // reads RECOUNT_API_KEY / RECOUNT_ENVIRONMENT from env automatically
11
11
  // call init() only to override
12
- recount.init({ apiKey: 'bec_...', environment: 'production', debug: true });
12
+ recount.init({ apiKey: 'bec_...', environment: 'Production', debug: true });
13
13
  ```
14
14
 
15
15
  If no API key is found, the SDK disables itself. All calls become no-ops with no errors thrown.
16
16
 
17
+ `timeoutMs` (default `30000`) caps how long a trace upload may take, including rate-limit retries. When the limit is reached the request is cancelled and the trace is dropped.
18
+
17
19
  ## Traces
18
20
 
19
21
  ```ts
@@ -127,9 +129,11 @@ recount.addMessage('Cache warmed');
127
129
  Adds key/value pairs to the trace metadata after the trace has started:
128
130
 
129
131
  ```ts
130
- recount.addMetadata({ Decision: 'approved', Score: 87 });
132
+ recount.addMetadata({ Decision: 'Approved', Score: 87 });
131
133
  ```
132
134
 
135
+ Metadata keys and values, and environment names, are shown to people in the dashboard and in portals. Write them as plain words: `'Application ID'` not `applicationId`, `'Production'` not `production`.
136
+
133
137
  ## recount.named
134
138
 
135
139
  Sets the span name for the next auto-recorded span from an integration (Anthropic, OpenAI, MongoDB). Applies to exactly one span.
@@ -174,10 +178,15 @@ recount.addSpan('table', 'Policy validation', {
174
178
  .build()
175
179
  });
176
180
 
177
- // multiple tables in one span
178
- output: { tables: [recount.table('A').fromRecords(a).build(), recount.table('B').fromRecords(b).build()] }
181
+ // multiple tables: one table span each, inside a group (or tableSections() for shared columns)
182
+ recount.addGroup('Claim report', (g) => {
183
+ g.span('table', 'Summary', { output: recount.tableFromObject({ data: summary }) });
184
+ g.span('table', 'Breakdown', { output: recount.tableFromRecords({ data: items }) });
185
+ });
179
186
  ```
180
187
 
188
+ Column names (and `fromObject` keys) are shown to readers as-is. Write keys as plain words (`'Estimated cost'`), or rename code keys with `.label({ estimatedCost: 'Estimated cost' })`.
189
+
181
190
  Highlights: `'danger' | 'warn' | 'success' | 'info' | 'muted'`
182
191
 
183
192
  **Shorthand methods** (skip the builder chain):
@@ -195,18 +204,21 @@ recount.tableFromObject({ data: obj, title?: string })
195
204
  ```ts
196
205
  recount.addSpan('chart', 'Damage breakdown', {
197
206
  output: recount
198
- .chart('bar', 'Title') // types: 'bar'|'line'|'pie'|'scatter'
207
+ .chart('bar', 'Title') // types: 'bar'|'line'|'pie'|'scatter'
199
208
  .labels(['A', 'B', 'C'])
200
- .series('Name', [1, 2, 3]) // call multiple times for multi-series
209
+ .series('Name', [1, 2, 3]) // call multiple times for multi-series
201
210
  .referenceLine(750, 'Excess')
202
211
  .build()
203
212
  });
204
213
 
205
- // from records
206
- recount.chart('bar').fromRecords(rows, 'labelKey', ['series1', 'series2']).build()
214
+ // from records - each series is named after its key, so use readable keys
215
+ recount.chart('bar').fromRecords(rows, 'Month', ['Revenue', 'Cost']).build();
207
216
 
208
- // multiple charts
209
- output: { charts: [...] }
217
+ // multiple charts: one chart span each, inside a group
218
+ recount.addGroup('Claims dashboard', (g) => {
219
+ g.span('chart', 'By month', { output: byMonth });
220
+ g.span('chart', 'By category', { output: byCategory });
221
+ });
210
222
  ```
211
223
 
212
224
  **Shorthand method:**
@@ -353,9 +365,9 @@ HTTP spans automatically redact `Authorization`, `Cookie`, `X-Api-Key`, and rela
353
365
  import recount from '@refactorlabs/recount';
354
366
 
355
367
  const damage = [
356
- { component: 'Rear bumper', severity: 'major', estimatedCost: 2_400 },
357
- { component: 'Boot lid', severity: 'major', estimatedCost: 3_100 },
358
- { component: 'Rear lights', severity: 'moderate', estimatedCost: 890 }
368
+ { component: 'Rear bumper', severity: 'Major', estimatedCost: 2_400 },
369
+ { component: 'Boot lid', severity: 'Major', estimatedCost: 3_100 },
370
+ { component: 'Rear lights', severity: 'Moderate', estimatedCost: 890 }
359
371
  ];
360
372
  const total = damage.reduce((s, d) => s + d.estimatedCost, 0);
361
373
  const excess = 750;
@@ -384,10 +396,15 @@ await recount.startTrace(
384
396
  output: recount
385
397
  .table()
386
398
  .fromRecords(damage)
399
+ .label({
400
+ component: 'Component',
401
+ severity: 'Severity',
402
+ estimatedCost: 'Estimated cost'
403
+ })
387
404
  .highlightRows((row) =>
388
- row.severity === 'major'
405
+ row.severity === 'Major'
389
406
  ? 'danger'
390
- : row.severity === 'moderate'
407
+ : row.severity === 'Moderate'
391
408
  ? 'warn'
392
409
  : 'muted'
393
410
  )
package/package.json CHANGED
@@ -1,9 +1,12 @@
1
1
  {
2
2
  "name": "@refactorlabs/recount",
3
- "version": "0.8.0",
3
+ "version": "0.9.1",
4
4
  "description": "Node.js SDK for Recount",
5
5
  "homepage": "https://recount.refactor.gg",
6
6
  "license": "MIT",
7
+ "engines": {
8
+ "node": ">=18"
9
+ },
7
10
  "repository": {
8
11
  "type": "git",
9
12
  "url": "https://gitlab.com/refactor-labs/recount-node"
@@ -140,7 +140,7 @@ For each one:
140
140
 
141
141
  4. **Use the table builder properly** for any rule/comparison output - `.highlightRows()` /
142
142
  `.highlightCells()` for pass/fail or good/bad framing, `.summary()` for a rolled-up total,
143
- `.transformValues()` for currency/percent formatting. Look at
143
+ `.transformValues()` for currency/percentage formatting. Look at
144
144
  `examples/loan-eligibility.ts` and `examples/insurance-claim.ts` in this repo for the target
145
145
  quality bar - each rule/factor becomes a table row with a real highlight derived from the
146
146
  actual comparison in the code, not a hardcoded colour.
@@ -176,8 +176,9 @@ For each one:
176
176
  8. **Every name is prose, not code** - trace names, span names, group names, table/column titles,
177
177
  alert labels. Write them the way you'd say them out loud: `'Credit assessment'`, not
178
178
  `creditAssessment` or `CREDIT_CHECK`. No camelCase, no snake_case, no identifier casing left
179
- over from a variable name. Same for `metadata` keys shown in the dashboard - `'Application ID'`,
180
- not `applicationId`.
179
+ over from a variable name. Same for `metadata` keys and values shown in the dashboard -
180
+ `'Application ID'`, not `applicationId` - and for environment names: `'Production'`, not
181
+ `production`.
181
182
 
182
183
  ## Step 5 - Validate
183
184
 
@@ -185,7 +186,7 @@ Run the project's typecheck/build (`npm run typecheck` or equivalent - check `pa
185
186
  scripts) after editing. Fix any type errors from span option shapes before considering the work
186
187
  done - the SDK's types are strict about which options apply to which span type.
187
188
 
188
- ## Step 6 - Summarize
189
+ ## Step 6 - Summarise
189
190
 
190
191
  List what got instrumented: function → trace name → spans added → what's redacted. Don't commit
191
192
  unless asked.