@go-labs-sg/bb 2.32.0 → 2.33.0

package/README.md

@@ -232,7 +232,7 @@ Every canonical command is classified by effect: `state-change`, `email`, `exter
 
 **Draft-only bills:** Use `bb bill create --draft-only --payload '<bill-json>' --allow-state-change --allow-financial-write` when the user authorizes a draft only. The equivalent payload field is `draftOnly: true`. This creates `DRAFT` for every role, without auto-checking, auto-approval, approval requests, emails, or QuickBooks writes. It cannot be combined with `alreadyPaid: true`; conflicting flag and payload values are rejected. Draft-only creation uses the dedicated `bill.createDraft` API route and fails on older servers without falling back to ordinary creation. Deploy backend support before releasing the updated CLI. Reconciled projects must be moved to Won separately before draft-only creation, because reopening a project can trigger external integrations. Completed projects retain their existing creation restriction.
 
-**Quotation-first supplier bills:** Use `quotationIds` when approved quotations cover disjoint bill lines. When two quotations fund the same bill line, pass `quotationAllocations` entries with `{ budgetItemId, quotationId, amount }` and an exact `lineAmounts` entry for every selected budget item; `lineAmounts` must sum to the bill amount. Every quotation must belong to the bill supplier and project and cover the allocated budget item. Legacy `quotationId` remains valid for one quotation. Supplier bills that qualify for an existing exemption must state that intent with `--quotation-exempt`. Claims share budget allowance but never consume or link quotations, so quotation source fields are rejected for claims.
+**Quotation-first supplier bills:** Use `quotationIds` when approved quotations cover disjoint bill lines. When two quotations fund the same bill line, pass `quotationAllocations` entries with `{ budgetItemId, quotationId, amount }` and an exact `lineAmounts` entry for every selected budget item; `lineAmounts` must sum to the bill amount. Canonical allocation rows are the stored source of every bill-line quotation relationship. A required zero-value bill line needs one or more allocations with `amount: 0`, which record its approved source(s) without consuming quotation capacity. Every quotation must belong to the bill supplier and project and cover the allocated budget item. Legacy `quotationId` remains valid as single-quotation input and maps to the current selection. Supplier bills that qualify for an existing exemption must state that intent with `--quotation-exempt`. Claims share budget allowance but never consume or link quotations, so quotation source fields are rejected for claims.
 
 Every selected bill or claim line must belong to an active budget in `ESTIMATE_ACCEPTED` or `ESTIMATE_CLOSED`, including lines drawn from additional budgets in the project. The server checks this during selection, creation, editing, and approval. An unaccepted budget never qualifies a line for a quotation exemption. Existing pending bills expose budget and source-link blockers in `commitmentReview.blockers`.
 
@@ -403,7 +403,6 @@ relationships or allocations block approval and require review. Multi-line quota
 create/update payloads must include `lineAmounts` with `{ budgetItemId, amount }`
 for every selected line, summing to `amountWithoutGst`. The server revalidates
 existing quotation links, reviewed usage, and per-line allowance inside the
-approval transaction. Multiple source quotations use `BillLineItem.quotationId`;
-apply the updated database schema and deploy the API before releasing the CLI.
-Legacy bill-wide links remain readable, and unresolved historical overlaps
-continue to block approval.
+approval transaction. Multiple source quotations use canonical bill quotation
+allocation rows; apply the updated database schema and deploy the API before
+releasing the CLI. Unresolved historical overlaps continue to block approval.

package/dist/index.js

@@ -20166,8 +20166,8 @@ var parseQuotationReferences = (input2, commandName) => {
       const label = `${commandName} payload.quotationAllocations[${index}]`;
       const allocation = requireObject(raw, label);
       const amount = Number(allocation.amount);
-      if (!Number.isFinite(amount) || amount <= 0 || !Number.isInteger(amount * 100)) {
-        throw new Error(`${label}.amount must be a positive cent value.`);
+      if (!Number.isFinite(amount) || amount < 0 || !Number.isInteger(amount * 100)) {
+        throw new Error(`${label}.amount must be a non-negative cent value.`);
       }
       return {
         budgetItemId: requiredString(allocation.budgetItemId, `${label}.budgetItemId`),
@@ -20261,6 +20261,9 @@ var validateExplicitBillAllocations = ({
       throw new Error(`${commandName} payload.quotationAllocations references an unselected budget item.`);
     }
     allocatedById.set(allocation.budgetItemId, (allocatedById.get(allocation.budgetItemId) ?? 0) + cents(allocation.amount));
+    if (cents(allocation.amount) === 0 && lineAmountById.get(allocation.budgetItemId) !== 0) {
+      throw new Error(`${commandName} zero quotation allocations are only valid for zero-value bill lines.`);
+    }
   }
   for (const [budgetItemId, allocated] of allocatedById) {
     if (allocated > (lineAmountById.get(budgetItemId) ?? 0)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-labs-sg/bb",
-  "version": "2.32.0",
+  "version": "2.33.0",
   "description": "Budget Builder CLI for AI agents — manage budgets, bills, claims, quotations, and customer invoices with explicit workflow previews for sensitive changes.",
   "type": "module",
   "main": "./dist/index.js",

package/role-aware-agent-guide.md

@@ -129,7 +129,7 @@ The following distinctions are especially important:
 - Project Hub setup and sync are asynchronous external writes. Read `bb project hub status <project-id>` first, obtain explicit approval, and request the mutation once instead of repeatedly queueing it. Setup readiness remains visible through `status`; commercial sync returns an outbox operation ID for Admin diagnostics.
 - Bill/claim status commands have separate role rules for `CHECKED`, `APPROVED`, and `PAID`.
 - `bb bill create --payload` uses `isClaimable=false`; `isClaimable=true` creates a claim. Claims intentionally permit some base-user flows that supplier bills do not.
-- Create supplier bills from approved quotations by passing `quotationIds` for disjoint coverage, or `quotationAllocations` plus exact `lineAmounts` when quotations split a bill line. Use `--quotation-exempt` only for an existing server-validated exemption. Claims share budget allowance but never consume or link quotations, and reject quotation source fields.
+- Create supplier bills from approved quotations by passing `quotationIds` for disjoint coverage, or `quotationAllocations` plus exact `lineAmounts` when quotations split a bill line. A required zero-value bill line needs one or more `quotationAllocations` entries with `amount: 0` so its approved source(s) are retained without consuming quotation capacity. Use `--quotation-exempt` only for an existing server-validated exemption. Claims share budget allowance but never consume or link quotations, and reject quotation source fields.
 - For a draft-only bill or claim, use `bb bill create --draft-only --payload` (or `draftOnly: true` in the payload). This forces `DRAFT` for every role and requires only `--allow-state-change --allow-financial-write`. It sends no approval/email and performs no QuickBooks writes. Do not combine it with `alreadyPaid: true`. An older API without `bill.createDraft` rejects the command; never retry with ordinary creation to bypass that error.
 - Ordinary unpaid creation does not require `--allow-email`, but remains role-dependent: Accounting auto-checks and Admin auto-approves. It still requires `--allow-external-write`, including for possible placeholder adjustments. Already-paid creation retains the email gate.
 - Staged attachments belong to the user in the database. Do not reuse, share, or manually construct staged keys.