@bilig/headless 0.11.18 → 0.11.22

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.
Files changed (2) hide show
  1. package/README.md +91 -2
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -22,6 +22,46 @@ Requires Node `24+` and ESM imports.
22
22
  npm install @bilig/headless
23
23
  ```
24
24
 
25
+ ## Clean npm Sanity Check
26
+
27
+ Run this from an empty directory when you want to verify the published package
28
+ before cloning the repository:
29
+
30
+ ```sh
31
+ mkdir bilig-headless-sanity
32
+ cd bilig-headless-sanity
33
+ npm init -y
34
+ npm install @bilig/headless
35
+ node --input-type=module <<'EOF'
36
+ import { WorkPaper } from '@bilig/headless'
37
+
38
+ const workbook = WorkPaper.buildFromSheets({
39
+ Revenue: [
40
+ ['Units', 'Price', 'Revenue'],
41
+ [7, 6, '=A2*B2'],
42
+ ],
43
+ })
44
+
45
+ const sheet = workbook.getSheetId('Revenue')
46
+ if (sheet === undefined) {
47
+ throw new Error('Revenue sheet was not created')
48
+ }
49
+
50
+ const cell = workbook.getCellValue({ sheet, row: 1, col: 2 })
51
+ if (typeof cell !== 'object' || cell === null || cell.value !== 42) {
52
+ throw new Error(`unexpected formula readback: ${JSON.stringify(cell)}`)
53
+ }
54
+
55
+ console.log({ revenue: cell.value, verified: true })
56
+ EOF
57
+ ```
58
+
59
+ Expected output:
60
+
61
+ ```json
62
+ { "revenue": 42, "verified": true }
63
+ ```
64
+
25
65
  Inside this monorepo:
26
66
 
27
67
  ```sh
@@ -31,7 +71,8 @@ pnpm --filter @bilig/headless build
31
71
 
32
72
  ## Start Here
33
73
 
34
- - Run the [quickstart](#quickstart) for a one-file formula and persistence
74
+ - Run the [clean npm sanity check](#clean-npm-sanity-check) before cloning, or
75
+ the [quickstart](#quickstart) for a one-file formula and persistence
35
76
  smoke test.
36
77
  - Try the runnable examples:
37
78
  [`examples/headless-workpaper`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper) and
@@ -39,8 +80,26 @@ pnpm --filter @bilig/headless build
39
80
  for in-process records, or
40
81
  [`npm run json-file`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#json-file-input)
41
82
  for records already saved on disk, or
83
+ [`npm run formula-diagnostics`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#formula-diagnostics)
84
+ for structured formula error handling, or
85
+ [`npm run markdown-report`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#markdown-report-output)
86
+ for a calculated Markdown table, or
87
+ [`npm run snapshot-diff`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#snapshot-diff)
88
+ for before/after persisted-state comparison, or
89
+ [`npm run range-readback`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#range-readback)
90
+ for computed values and serialized formulas from the same range, or
91
+ [`npm run sheet-inspection`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#sheet-inspection)
92
+ for checking restored workbook shape before writes, or
42
93
  [`npm run http-json-summary`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#http-json-summary)
43
- for a no-framework Node HTTP boundary.
94
+ for a no-framework Node HTTP boundary, or
95
+ [`npm run invoice-totals`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#invoice-totals)
96
+ for subtotal, tax, and total formula readback, or
97
+ [`npm run budget-variance`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#budget-variance-alerts)
98
+ for formula-backed budget variance alerts, or
99
+ [`npm run subscription-mrr`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#subscription-mrr-forecast)
100
+ for churn, expansion, and ending MRR formulas, or
101
+ [`npm run quote-approval`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#quote-approval-threshold)
102
+ for formula-backed quote discount approvals.
44
103
  - Run the
45
104
  [serverless WorkPaper API example](https://github.com/proompteng/bilig/tree/main/examples/serverless-workpaper-api)
46
105
  when the workbook belongs behind an HTTP or agent-tool boundary.
@@ -58,6 +117,26 @@ pnpm --filter @bilig/headless build
58
117
  - Star or bookmark the project:
59
118
  <https://github.com/proompteng/bilig>.
60
119
 
120
+ ## Which Example Should I Run?
121
+
122
+ The full example catalog lives in
123
+ [`examples/headless-workpaper/README.md`](https://github.com/proompteng/bilig/blob/main/examples/headless-workpaper/README.md).
124
+
125
+ | Need | Start with | Existing example |
126
+ | ------------------------------------ | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
127
+ | Evaluate formulas from API records | `npm run json-records` | [JSON records input](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#json-records-input) |
128
+ | Load records already saved on disk | `npm run json-file` | [JSON file input](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#json-file-input) |
129
+ | Persist and restore a workbook | `npm run persistence` | [Persistence round trip](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#persistence-round-trip) |
130
+ | Verify an agent writeback | `npm run agent:verify` | [Agent writeback verification](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#agent-writeback-verification) |
131
+ | Wrap WorkPaper operations as tools | `npm run agent:tool-call` | [Agent tool call loop](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#agent-tool-call-loop) |
132
+ | Flag budget variance rows | `npm run budget-variance` | [Budget variance alerts](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#budget-variance-alerts) |
133
+ | Check quote approval threshold | `npm run quote-approval` | [Quote approval threshold](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#quote-approval-threshold) |
134
+ | Forecast subscription MRR | `npm run subscription-mrr` | [Subscription MRR forecast](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#subscription-mrr-forecast) |
135
+ | Return workbook results over HTTP | `npm run http-json-summary` | [HTTP JSON summary](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#http-json-summary) |
136
+ | Calculate invoice totals | `npm run invoice-totals` | [Invoice totals](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#invoice-totals) |
137
+ | Inspect restored workbook shape | `npm run sheet-inspection` | [Sheet inspection](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#sheet-inspection) |
138
+ | Compare computed values and formulas | `npm run range-readback` | [Range readback](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#range-readback) |
139
+
61
140
  ## Production Status
62
141
 
63
142
  Use this package in production for documented WorkPaper/headless API workflows:
@@ -140,6 +219,16 @@ Repository links:
140
219
  [`examples/headless-workpaper`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper)
141
220
  - JSON records input example:
142
221
  [`npm run json-records`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#json-records-input)
222
+ - Formula diagnostics example:
223
+ [`npm run formula-diagnostics`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#formula-diagnostics)
224
+ - Markdown report output example:
225
+ [`npm run markdown-report`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#markdown-report-output)
226
+ - Snapshot diff example:
227
+ [`npm run snapshot-diff`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#snapshot-diff)
228
+ - Range readback example:
229
+ [`npm run range-readback`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#range-readback)
230
+ - Sheet inspection example:
231
+ [`npm run sheet-inspection`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#sheet-inspection)
143
232
  - serverless API route example:
144
233
  [`examples/serverless-workpaper-api`](https://github.com/proompteng/bilig/tree/main/examples/serverless-workpaper-api)
145
234
  - Node service recipe:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bilig/headless",
3
- "version": "0.11.18",
3
+ "version": "0.11.22",
4
4
  "description": "Headless spreadsheet engine for Node.js formulas, workbook JSON persistence, and service-side spreadsheet automation.",
5
5
  "keywords": [
6
6
  "agent",
@@ -66,9 +66,9 @@
66
66
  "build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json"
67
67
  },
68
68
  "dependencies": {
69
- "@bilig/core": "0.11.18",
70
- "@bilig/formula": "0.11.18",
71
- "@bilig/protocol": "0.11.18"
69
+ "@bilig/core": "0.11.22",
70
+ "@bilig/formula": "0.11.22",
71
+ "@bilig/protocol": "0.11.22"
72
72
  },
73
73
  "engines": {
74
74
  "node": ">=24.0.0"