bilig

Five Node.js workbook automation examples

These examples are for the common case where spreadsheet logic belongs inside a service, queue worker, API route, or agent tool instead of a browser grid. Each script builds a small WorkPaper, writes formulas, reads computed values, and prints verified: true after the expected checks pass.

The examples use the published @bilig/headless package from npm.

90-second npm-only check

If you are evaluating from search, HN, or an agent-tool shortlist, start here before cloning the repository. This checks the published npm package in an empty directory, edits an input cell, recalculates formulas, persists the WorkPaper JSON, restores it, and prints verified: true.

mkdir bilig-headless-eval
cd bilig-headless-eval
npm init -y
npm pkg set type=module
npm install @bilig/headless
npm install -D tsx typescript @types/node
curl -fsSLo quickstart.ts https://proompteng.github.io/bilig/npm-eval.ts
npx tsx quickstart.ts

Use the clone path below when you want the full workflow set: invoice totals, budget variance, MRR forecast, quote approval, fulfillment capacity, agent tool-call readback, and MCP transcript checks.

Clone and run

git clone https://github.com/proompteng/bilig.git
cd bilig/examples/headless-workpaper
npm install
npm run invoice-totals
npm run budget-variance
npm run subscription-mrr
npm run quote-approval
npm run fulfillment-capacity

What each example proves

Workflow	Command	What to inspect
Invoice totals	npm run invoice-totals	line totals, subtotal, tax, grand total, and serialized formulas
Budget variance alerts	npm run budget-variance	budget vs actual rows, variance percent, and review flags
Subscription MRR forecast	npm run subscription-mrr	churn, expansion, new customers, ending MRR, and forecast formulas
Quote approval threshold	npm run quote-approval	discount amount, quote total, max line discount, and approval status
Fulfillment capacity plan	npm run fulfillment-capacity	forecast orders, required hours, available labor, capacity gap, and short days

Output shape

The full JSON output is intentionally small enough to paste into an issue, agent trace, or service log. Current example outputs include these checks.

npm run invoice-totals:

{
  "invoiceNumber": "INV-2026-001",
  "lineItems": 4,
  "subtotal": 1890,
  "tax": 151.2,
  "total": 2041.2,
  "verified": true
}

npm run budget-variance:

{
  "flaggedDepartment": "Marketing",
  "varianceAmount": 7500,
  "variancePercent": 0.15,
  "summary": {
    "totalBudget": 185000,
    "totalActual": 196600,
    "reviewCount": 1
  },
  "verified": true
}

npm run subscription-mrr:

{
  "months": 4,
  "startingMrr": 5880,
  "endingMrr": 9604.03,
  "mrrDelta": 3724.03,
  "verified": true
}

npm run quote-approval:

{
  "quoteId": "Q-2026-041",
  "listTotal": 6980,
  "discountAmount": 993,
  "quoteTotal": 5987,
  "approvalRequired": "Review",
  "verified": true
}

npm run fulfillment-capacity:

{
  "days": 4,
  "forecastOrders": 2020,
  "requiredHours": 61.0318,
  "availableHours": 60,
  "capacityGap": -1.0318,
  "status": "Short",
  "verified": true
}

Plain Postgres persistence

If one of these automation scripts needs durable workbook state in a Node service, the WorkPaper Node service recipe includes a low-level pg path for teams that are not using Prisma, Drizzle, or Kysely. It shows the workpaper_documents table, parameterized save/load SQL, and a restore verification check with createWorkPaperFromDocument(parseWorkPaperDocument(saved)) before accepting stored JSON as valid.

Why this matters

Most backend spreadsheet automation examples stop at printing a table. These scripts are more useful because they keep the workbook behavior visible:

• formulas stay in the workbook instead of being rewritten as application code
• computed values are read back through the engine
• the output includes the business result and the formula row that produced it
• each workflow can become a small API response, job result, or agent tool log

If one of these workflows is close to a real system you are building, use the show-and-tell discussion to ask for the next example. If the package saves you a workbook automation spike, star the repo so it is easier to find later: https://github.com/proompteng/bilig/stargazers.

If it almost matches but a gap blocks adoption, use the adoption blocker form: https://github.com/proompteng/bilig/discussions/new?category=general.

This site is open source. Improve this page.