@go-labs-sg/bb 2.30.0 → 2.31.0

package/README.md

@@ -285,7 +285,7 @@ Bill, claim, and quotation mutations accept only suppliers whose approval status
 | **Budgets** | `list-budgets` (full payload by default; `--summary` or `--includeDetails false` for slim list), `get-budget`, `get-budget-items`, `get-budget-details`, `get-budget-categories`, `get-budget-versions`, `rename-budget-version`, `restore-budget-version`, `update-budget-status` (`ESTIMATE_ACCEPTED` requires win proof, auto-marks `PITCH` or `LOST` projects `WON`, and auto-creates an Asana Event Ops section from Prompt 5 tasks when enabled; Prompt 5 skips quantity-zero items, combines matching non-GO-internal suppliers, keeps each GO internal item separate, removes generated work that repeats another line item or group, and schedules applicable subtasks relative to the project start date; `--projectStatusOnCommercialRejection PITCH\|LOST` is required when rejecting the only accepted/closed budget on a commercial project), `mark-budget-won` (`<budgetId>` + proof file path; `PITCH` or `LOST` projects become `WON` automatically), `create-budget` / `update-budget` (`--payload`; cloned unavailable lines require `unavailableItemReviewAcknowledged: true`), `delete-budget`, `create-budget-approval` (also sends approval request emails), `create-estimate`, `send-estimate-to-contact-person` (same contact-person email workflow as web), `add-budget-items`, `update-budget-item`, `replace-budget-item`, `approve-unavailable-item-exception` (Lead/Admin), `remove-budget-item`, `reorder-budget-items`, `update-budget-item-supplier`, `mark-budget-items-not-utilized`, `restore-budget-item`, `create-placeholder-bill` (admin recovery), `create-budget-category`, `update-budget-category`, `delete-budget-category`, `update-budget-commission`, `delete-budget-commission`, `update-budget-discount`, `delete-budget-discount` (`--payload` where noted), `upload-budget-attachment` (`<budgetId>` + local file path; uses `attachment.requestBudgetAttachmentUpload` + PUT + `attachment.confirmBudgetAttachment`) |
 | **Bills / claims** | `list-bills` (`--isClaimable false` for bills, `--isClaimable true` for claims, omit for both), `list-claims` (claims only), `validate-bill-selection` (`--payload`; validates the project and supplier separately, then checks approved quotation links for each selected budget line item independent of the bill supplier; `alreadyPaid` never bypasses the checks), `stage-bill-attachment` (securely uploads invoice/payment-proof files before creation and returns attachment JSON; ownership and one-hour expiry are enforced by a server-side staged-upload record rather than encoded in the object key), `cleanup-staged-bill-attachments`, `create-bill` (`--payload`; set `isClaimable=false` for a bill, `isClaimable=true` for a claim; supplier bills require positive `extractedAmount` and `amount`, with `amount <= extractedAmount`; an already-paid supplier bill sets `alreadyPaid=true` and requires `paymentReference` plus a staged PDF in `paymentProofAttachments`; admin creation automatically queues QBO finalization while other roles remain pending approval; non-legacy supplier bills from 1 Jul 2026 00:00 SGT require approved quotation coverage linked to every selected line item, independent of the bill supplier, even when already paid), `update-bill` (`--payload`), `update-bill-payment-evidence` (`--payload`; replaces the payment reference and payment-proof PDFs for an already-paid bill), `delete-bill`, `create-bill-approval` (also sends approval request emails), `update-bill-status` (`PAID` requires `--paymentReference`; pass `--paymentProof <receipt.pdf>` to stage and submit a PDF up to 20MB atomically, or omit it only when BB already has payment proof; moving to `PAID` runs the server's paid-bill notification workflow), `patch-bill-payment` (PAID bills: `--paymentTrackingUrl`, `--paymentReference`, `--quickbooksBillId`, `--paymentDate` ISO; clearing a paid bill's QuickBooks link is not allowed), `patch-bill-invoice-number`, `get-bill-attachments`, `upload-bill-attachment` (`<billId>` + local path), `get-bill-details` |
 | **Quotations** | `list-quotations` (supports project, budget, supplier, status, requester, and text-search filters), `get-quotation`, `upload-quotation-attachment` (`<projectId>` + PDF/JPEG/PNG path up to 20MB; returns attachment JSON for payload use), `cleanup-staged-quotation-attachments`, `create-quotation` (`--payload` for `quotation.createDraft`; include `amountWithoutGst` and `gstAmount`), `update-quotation` (`--payload`; updates a `DRAFT` or `REJECTED` quotation), `delete-quotation`, `submit-quotation`, `approve-quotation`, `reject-quotation`, `download-quotation-pdf` (`original`, `staff`, or `final`) |
-| **Customer invoices** | `check-customer-invoice-readiness`, `list-eligible-customer-invoice-budgets`, `list-customer-invoices` (global/project/budget filters plus summary metrics), `get-customer-invoice`, `get-customer-invoice-email-context`, `create-customer-invoice`, `discard-customer-invoice`, `delete-customer-invoice`, `void-customer-invoice`, `approve-customer-invoice` (admin), `reject-customer-invoice` (admin), `send-customer-invoice-to-contact-person`, `download-customer-invoice-pdf` (non-admins cannot download while approval is pending), `sync-customer-invoice` |
+| **Customer invoices** | `check-customer-invoice-readiness`, `list-eligible-customer-invoice-budgets`, `list-customer-invoices` (global/project/budget filters plus summary metrics; `--sortBy totalInvoiceAmount` sorts provider-confirmed totals including GST, with unknown amounts last), `get-customer-invoice`, `get-customer-invoice-email-context`, `create-customer-invoice`, `discard-customer-invoice`, `delete-customer-invoice`, `void-customer-invoice`, `approve-customer-invoice` (admin), `reject-customer-invoice` (admin), `send-customer-invoice-to-contact-person`, `download-customer-invoice-pdf` (non-admins cannot download while approval is pending), `sync-customer-invoice` |
 | **Approvals** | `list-approvals` / `get-pending-approvals` (`--type budget\|supplier\|bill\|quotation\|customer_invoice\|all`), `approve-bill` / `reject-bill` (send reply email), `approve-budget` / `reject-budget` (send reply email), `approve-supplier` / `reject-supplier` (send reply email), `approve-quotation` / `reject-quotation`, `approve-customer-invoice` / `reject-customer-invoice` |
 | **Companies & projects** | `list-companies`, `get-company`, `create-company`, `update-company` (`--payload`), `delete-company`, `list-projects`, `get-project` (its budget overview returns `totalRevenue`, calculated only from Estimate Accepted and Estimate Closed budgets), `get-project-hub-status`, `setup-project-hub`, `sync-project-hub-commercial-documents`, `create-project` (required: `--name`, `--companyId`, `--contactPersonId`, `--insideSalesId`, `--businessDevelopmentId`, `--venue`, `--startDate` as ISO datetime for project/window start; when `--asanaTaskId` is omitted, the CLI searches open Asana lead tasks in the Deals project, prompts for one of the top five matches, and resolves Slack channel fields from the selected deal card; optional `--asanaSearch`, `--pax`, `--endDate`, `--description`, `--projectManagerId`; always requests QBO project import like the web app), `update-project` (`--payload` with `dateRange.from` / `dateRange.to` for the project window; optional `projectManagerId` and `requestQboAccountantNotification` in JSON), `delete-project`, `check-project-reconciliation <id>` (runs the web app's live checks without changing status), `reconcile-project <id>` (reruns checks transactionally and marks an eligible project `RECONCILED`), `complete-project <id>` (reruns validation, marks a reconciled project `COMPLETED`, and queues QuickBooks placeholder cleanup), `import-qbo-project`, `update-project-status` (`<id>` `<status>`: `PITCH` \| `WON` \| `COMPLETED` \| `RECONCILED` \| `LOST`; close-out follows `WON` → `RECONCILED` → `COMPLETED`, and reconciliation requires every accepted/closed budget line to have an Approved/Paid bill or claim or be explicitly Not Utilized; marking `COMPLETED` queues deletion of every remaining project placeholder bill from QuickBooks; for `PITCH` → `WON` also pass a Budget Builder user `--projectManagerId` or `--projectManagerEmail`; when marking `WON` without an accepted/closed budget or proof, pass `--wonOverrideReason`) |
 | **Contacts** | `list-contacts`, `create-contact-person` (`--payload`), `update-contact-person` (`--payload`) |
@@ -349,3 +349,15 @@ The list also accepts `PARTIALLY_SENT`, `PARTIALLY_PAID`, `PAID`, and `VOIDED`,
 alongside existing approval states such as `APPROVED` and `PENDING_APPROVAL`.
 `--sortBy status` sorts by lifecycle; `lifecycleStatus` in list/detail output is
 separate from the stored approval/operational `status`.
+
+### Shared allowance decisions
+
+Quotation approval/submission and bill approval/status commands accept an optional
+`--overBudgetOverrideReason "<reason>"`. Bill create/update JSON payloads accept
+`overBudgetOverrideReason`. Only admins may override an assessed overrun; missing
+relationships or allocations block approval and require review. Multi-line quotation
+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. No new database fields or relationship declarations are
+required; unresolved historical overlaps continue to block approval.

package/dist/index.js

@@ -21326,7 +21326,7 @@ async function listBills(opts) {
   const result = await api2.bill.getAll.query(input2);
   out(result);
 }
-async function approveBill(billId) {
+async function approveBill(billId, overBudgetOverrideReason) {
   await assertSensitiveWorkflowConfirmed({
     action: "Approve bill",
     entity: `bill ${billId}`,
@@ -21340,7 +21340,8 @@ async function approveBill(billId) {
   }
   const result = await api2.bill.updateApproval.mutate({
     billApprovalId: approval.id,
-    status: "APPROVED"
+    status: "APPROVED",
+    overBudgetOverrideReason
   });
   if (result.processing) {
     out(result);
@@ -21519,7 +21520,8 @@ async function updateBillStatus(opts) {
       rejectionReason: opts.rejectionReason,
       paymentTrackingUrl: opts.paymentTrackingUrl,
       paymentReference: opts.paymentReference,
-      paymentProofAttachments: paymentProof ? [paymentProof] : undefined
+      paymentProofAttachments: paymentProof ? [paymentProof] : undefined,
+      overBudgetOverrideReason: opts.overBudgetOverrideReason
     });
     out(result);
   } catch (error61) {
@@ -22088,12 +22090,15 @@ var deleteQuotationById = async (id) => {
   const result = await api2.quotation.delete.mutate({ id });
   out(result);
 };
-async function submitQuotation(id) {
+async function submitQuotation(id, overBudgetOverrideReason) {
   await assertSensitiveWorkflowConfirmed({
     action: "Submit quotation for approval",
     entity: `quotation ${id}`
   });
-  const result = await api2.quotation.submitForApproval.mutate({ id });
+  const result = await api2.quotation.submitForApproval.mutate({
+    id,
+    overBudgetOverrideReason
+  });
   out(result);
 }
 async function downloadQuotationPdf(id, fileRole) {
@@ -22523,7 +22528,7 @@ async function rejectBill(billId, reason) {
     email: email3
   });
 }
-async function approveQuotation(quotationId) {
+async function approveQuotation(quotationId, overBudgetOverrideReason) {
   await assertSensitiveWorkflowConfirmed({
     action: "Approve quotation",
     entity: `quotation ${quotationId}`
@@ -22535,7 +22540,8 @@ async function approveQuotation(quotationId) {
     throw new Error("No pending quotation approval found.");
   }
   const result = await api2.quotation.approve.mutate({
-    quotationApprovalId: approval.id
+    quotationApprovalId: approval.id,
+    overBudgetOverrideReason
   });
   out(result);
 }
@@ -23711,6 +23717,7 @@ function parseOptionalBoolFlag(flags, key) {
 var CUSTOMER_INVOICE_SORT_FIELDS = [
   "createdAt",
   "status",
+  "totalInvoiceAmount",
   "totalNetAmount",
   "approvalExpiresAt"
 ];
@@ -23886,7 +23893,7 @@ Bills
   update-bill                --payload '<json>'  (bill.update; must include id)
   update-bill-payment-evidence --payload '<json>'  Replace paymentReference/paymentProofAttachments for an already-paid bill.
   delete-bill <billId>
-  update-bill-status <id> <status> [--rejectionReason] [--paymentTrackingUrl] [--paymentReference] [--paymentProof <receipt.pdf>]
+  update-bill-status <id> <status> [--rejectionReason] [--paymentTrackingUrl] [--paymentReference] [--paymentProof <receipt.pdf>] [--overBudgetOverrideReason <text>]
     status (${billStatusesForUpdateHelp.join(", ")}) \u2014 not PENDING_APPROVAL; use create-bill-approval
     PAID requires --paymentReference and a payment-proof PDF. Use --paymentProof to stage and submit the PDF atomically, or omit it only when BB already has a BILL_PAYMENT_PROOF attachment.
     Moving a bill or claim to PAID runs the server's paid-bill notification workflow.
@@ -23908,15 +23915,15 @@ Quotations
   create-quotation           --payload '<json>'  (quotation.createDraft; requires amountWithoutGst and gstAmount)
   update-quotation           --payload '<json>'  Update a DRAFT or REJECTED quotation; same payload plus id.
   delete-quotation <quotationId>
-  submit-quotation <quotationId>
-  approve-quotation <quotationId>
+  submit-quotation <quotationId> [--overBudgetOverrideReason <text>]
+  approve-quotation <quotationId> [--overBudgetOverrideReason <text>]
   reject-quotation <quotationId> --reason <text>
   download-quotation-pdf <quotationId> [original|staff|final]
 
 Customer invoices
   check-customer-invoice-readiness <budgetId>
   list-eligible-customer-invoice-budgets <projectId>   Accepted budgets that are ready and still have invoice coverage remaining.
-  list-customer-invoices [budgetId] [--projectId <id>] [--companyIds CSV] [--projectIds CSV] [--budgetIds CSV] [--createdByIds CSV] [--status CSV] [--search] [--sortBy createdAt|status|totalNetAmount|approvalExpiresAt] [--sortDir asc|desc] [--page] [--perPage]
+  list-customer-invoices [budgetId] [--projectId <id>] [--companyIds CSV] [--projectIds CSV] [--budgetIds CSV] [--createdByIds CSV] [--status CSV] [--search] [--sortBy createdAt|status|totalInvoiceAmount|approvalExpiresAt] [--sortDir asc|desc] [--page] [--perPage]
     No scope flag lists invoices globally. --projectId uses the project scope. A positional budgetId is a backward-compatible shortcut for --budgetIds.
   get-customer-invoice <batchId>
   get-customer-invoice-email-context <batchId>        Contact, required CC, budget, and project context for composing an invoice email.
@@ -23932,7 +23939,7 @@ Customer invoices
 
 Approvals
   list-approvals | get-pending-approvals   [--type budget|supplier|bill|quotation|customer_invoice|all]
-  approve-bill <billId>               (also sends requester reply email)
+  approve-bill <billId> [--overBudgetOverrideReason <text>]   (also sends requester reply email)
   reject-bill <billId> --reason <text> (also sends requester reply email)
   approve-budget <budgetId>           (also sends requester reply email)
   reject-budget <budgetId> --reason <text> (also sends requester reply email)
@@ -24785,7 +24792,8 @@ Waiting for approval\u2026
           rejectionReason: getFlag(flags, "rejectionReason"),
           paymentTrackingUrl: getFlag(flags, "paymentTrackingUrl"),
           paymentReference: getFlag(flags, "paymentReference"),
-          paymentProofPath: paymentProofFlag
+          paymentProofPath: paymentProofFlag,
+          overBudgetOverrideReason: getFlag(flags, "overBudgetOverrideReason")
         });
         break;
       }
@@ -25023,14 +25031,14 @@ Waiting for approval\u2026
         const id = positional[0];
         if (!id)
           throw new Error("submit-quotation requires <quotationId>");
-        await submitQuotation(id);
+        await submitQuotation(id, getFlag(flags, "overBudgetOverrideReason"));
         break;
       }
       case "approve-quotation": {
         const id = positional[0];
         if (!id)
           throw new Error("approve-quotation requires <quotationId>");
-        await approveQuotation(id);
+        await approveQuotation(id, getFlag(flags, "overBudgetOverrideReason"));
         break;
       }
       case "reject-quotation": {
@@ -25200,7 +25208,7 @@ Waiting for approval\u2026
         const id = positional[0];
         if (!id)
           throw new Error("approve-bill requires <billId>");
-        await approveBill(id);
+        await approveBill(id, getFlag(flags, "overBudgetOverrideReason"));
         break;
       }
       case "reject-bill": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-labs-sg/bb",
-  "version": "2.30.0",
+  "version": "2.31.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",