@go-labs-sg/bb 1.18.1 → 1.19.0

package/README.md

@@ -6,7 +6,7 @@ For AI agents: bills and claims are stored as the same underlying bill records.
 
 For AI agents using this CLI: always check whether a newer `@go-labs-sg/bb` version is available before running Budget Builder commands, then update the CLI if needed so command flags and API behavior stay current.
 
-For AI agents using this CLI: do not execute approval decisions, approval requests, status updates, `mark-budget-won`, `submit-quotation`, or supplier approval request side effects until the user explicitly confirms the exact entity, target state, and side effects. Inspect the entity first, summarize what will change and whether emails/integrations will run, then wait for a clear confirmation from the user. These sensitive workflow commands also require an interactive `CONFIRM` prompt at runtime and abort in non-interactive shells.
+For AI agents using this CLI: do not execute approval decisions, approval requests, status updates, customer-invoice changes, integration retries, `mark-budget-won`, `submit-quotation`, or supplier approval request side effects until the user explicitly confirms the exact entity, target state, and side effects. Inspect the entity first, summarize what will change and whether emails/integrations will run, then wait for a clear confirmation from the user. These sensitive workflow commands also require an interactive `CONFIRM` prompt at runtime and abort in non-interactive shells.
 
 **Registry:** [`@go-labs-sg/bb`](https://www.npmjs.com/package/@go-labs-sg/bb)
 
@@ -72,7 +72,7 @@ Global options and flags use `--key=value` or `--key value` (see `bb help`).
 
 **Budget status automation:** Setting a budget to `ESTIMATE_ACCEPTED` requires a confirmed win-proof attachment. If the parent project is `PITCH` or `LOST`, the API now marks it `WON` automatically and, when the `asana-tasks` feature flag is enabled, creates an Asana Event Ops section from Prompt 5 tasks. 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. When rejecting the only accepted/closed budget on a commercial project, pass `--projectStatusOnCommercialRejection PITCH|LOST`.
 
-**Sensitive workflow changes:** Approval decisions/requests, entity status updates, `mark-budget-won`, `submit-quotation`, and supplier approval request side effects require an interactive `CONFIRM` prompt. Non-interactive runs abort before the guarded workflow mutation. Agents must get user confirmation in chat before attempting the command; the prompt is a final runtime guard, not a replacement for user approval.
+**Sensitive workflow changes:** Approval decisions/requests, entity status updates, customer-invoice changes, integration retries, `mark-budget-won`, `submit-quotation`, and supplier approval request side effects require an interactive `CONFIRM` prompt. Non-interactive runs abort before the guarded workflow mutation. Agents must get user confirmation in chat before attempting the command; the prompt is a final runtime guard, not a replacement for user approval.
 
 **Approval email exclusions:** Approval requests create pending database records for every eligible approver, including configured non-recipient admin accounts. Automated approval-request emails skip those accounts.
 
@@ -84,17 +84,21 @@ Global options and flags use `--key=value` or `--key value` (see `bb help`).
 
 | Area | Commands (non-exhaustive) |
 | --- | --- |
-| **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`, `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`), `delete-budget`, `create-budget-approval` (also sends approval request emails), `add-budget-items`, `update-budget-item`, `remove-budget-item`, `reorder-budget-items`, `update-budget-item-supplier`, `create-budget-category`, `update-budget-category`, `delete-budget-category`, `update-budget-commission`, `update-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), `stage-bill-attachment` (securely uploads invoice/payment-proof files before creation and returns attachment JSON), `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`, and is created pending finance approval; non-legacy supplier bills from 1 Jul 2026 00:00 SGT also require approved quotation coverage), `update-bill` (`--payload`), `delete-bill`, `create-bill-approval` (also sends approval request emails), `update-bill-status` (moving a bill or claim to `PAID` sends creator and supplier emails, CC `m@getout.sg` and BCC `noah@getout.sg`; a claim sends one email when both recipient addresses match), `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`, `get-quotation`, `upload-quotation-attachment` (`<projectId>` + local PDF path; returns attachment JSON for payload use), `create-quotation` (`--payload` for `quotation.createDraft`; include `amountWithoutGst` and `gstAmount`), `submit-quotation`, `approve-quotation`, `reject-quotation`, `download-quotation-pdf` (`original`, `staff`, or `final`) |
-| **Approvals** | `list-approvals` / `get-pending-approvals` (`--type budget\|supplier\|bill\|quotation\|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` |
-| **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), `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`, `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; for `PITCH` → `WON` also pass a Budget Builder user `--projectManagerId` or `--projectManagerEmail`; when marking `WON` without an accepted/closed budget or proof, pass `--wonOverrideReason`) |
+| **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`), `delete-budget`, `create-budget-approval` (also sends approval request emails), `add-budget-items`, `update-budget-item`, `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`; runs the same supplier, line-item, and quotation-coverage checks as the web flow), `stage-bill-attachment` (securely uploads invoice/payment-proof files before creation and returns attachment JSON), `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`, and is created pending finance approval; non-legacy supplier bills from 1 Jul 2026 00:00 SGT also require approved quotation coverage), `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` (moving a bill or claim to `PAID` sends creator and supplier emails, CC `m@getout.sg` and BCC `noah@getout.sg`; a claim sends one email when both recipient addresses match), `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-customer-invoices`, `get-customer-invoice`, `create-customer-invoice`, `discard-customer-invoice`, `delete-customer-invoice`, `void-customer-invoice`, `approve-customer-invoice`, `reject-customer-invoice`, `download-customer-invoice-pdf`, `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), `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`) |
 | **Suppliers & items** | `list-suppliers` (defaults to active suppliers, `--perPage 10`, sorted by `createdAt` desc; supports `--name`, `--sortBy` for scalar supplier fields, `--sortDir`, `--createdBy`, `--gstRegistered`, `--status`, `--supplierTags`, `--active false` for archived suppliers), `create-supplier` (`--payload`; when supplier status is `PENDING_APPROVAL`, also runs `supplier.createSupplierApproval` and `email.sendSupplierApprovalRequestEmail`), `update-supplier` (`--payload`; when supplier status is `PENDING_APPROVAL`, also runs `supplier.createSupplierApproval` and `email.sendSupplierApprovalRequestEmail`), `delete-suppliers` (`--ids` CSV; admin; archives/deactivates related items), `reactivate-suppliers` (`--ids` CSV; admin; reactivates related items), `create-certification` / `create-payment-method` / `create-supplier-role` / `create-supplier-tag` (`--name`), `get-supplier-details` (includes `supplierApprovalSummary` for pending approvers, superseded approvers, and the actual responder/respondedAt metadata), `get-supplier-analytics`, `list-items`, `create-item` (`--payload`), `update-item` (`--payload`), `delete-item`, `get-item`, `list-item-categories`, `create-item-category`, `update-item-category`, `delete-item-categories` (`--ids` CSV; admin) |
 | **Dashboard & users** | `list-users`, `create-user` (admin; provisions an API-only service identity with no Google sign-in; `--email`, optional `--name`, optional `--role` defaulting to `USER`), `create-api-key` (admin; `--userId`, `--name`; raw key shown once), `list-api-keys` (admin; optional `--userId`), `revoke-api-key` (admin; key ID plus `--userId` for another user's key), `get-user-performance`, `get-dashboard`, `get-monthly-metrics`, `get-system-overview`, `get-estimate-performance`, `get-financial-overview` |
 | **Errors** | `get-recent-errors`, `get-error-metrics` |
+| **Automation (admin)** | `list-integration-operations`, `retry-integration-operation` |
 | **Historical / benchmarks** | `get-approved-budgets`, `get-budget-category-benchmarks`, `get-item-pricing-history`, `get-supplier-pricing-history` |
 
+The CLI intentionally wraps low-level upload-request/confirm procedures into file-based commands and omits browser-only helpers such as navigation counts, combobox/facet data, recent-page bookkeeping, and live UI subscriptions. Operational workflows for bills, claims, quotations, customer invoices, project reconciliation/completion, and integration recovery are available directly.
+
 ## Output
 
 - **Stdout:** JSON (pretty-printed)

package/dist/commands.js

@@ -1,18 +1,19 @@
 import { randomUUID } from "node:crypto";
-import { readFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
 import { basename } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { contentType } from "mime-types";
 import { api } from "./api-client.js";
 import { BudgetRole, Deals, ExtendedApprovalStatus, ExtendedApprovalType, ExtendedBudgetStatus, TimeFrame, } from "./filter-enums.js";
 import { billStatusesForApi, } from "./parse-cli-enums.js";
-import { parseBudgetDiscountPayload, parseCompanyUpdatePayload, parseContactCreatePayload, parseContactUpdatePayload, parseCreateBillPayload, parseCreateBudgetPayload, parseItemCreatePayload, parseItemUpdatePayload, parseSupplierCreatePayload, parseSupplierUpdatePayload, parseUpdateBillPayload, parseUpdateBudgetCommissionPayload, parseUpdateBudgetPayload, parseUpdateProjectPayload, } from "./parse-mutation-payload.js";
-import { BudgetStatus, } from "./prisma-enums.js";
+import { parseBudgetDiscountPayload, parseCompanyUpdatePayload, parseContactCreatePayload, parseContactUpdatePayload, parseCreateBillPayload, parseCreateBudgetPayload, parseCreateCustomerInvoicePayload, parseCreateQuotationPayload, parseItemCreatePayload, parseItemUpdatePayload, parseSupplierCreatePayload, parseSupplierUpdatePayload, parseUpdateBillPayload, parseUpdateBillPaymentEvidencePayload, parseUpdateBudgetCommissionPayload, parseUpdateBudgetPayload, parseUpdateProjectPayload, parseUpdateQuotationPayload, parseValidateBillSelectionPayload, } from "./parse-mutation-payload.js";
+import { BudgetStatus, ProjectStatus, } from "./prisma-enums.js";
 import { createRichTextFromPlainText } from "./rich-text.js";
 const BUDGET = "BUDGET";
 const BILL = "BILL";
 const SUPPLIER = "SUPPLIER";
 const QUOTATION = "QUOTATION";
+const CUSTOMER_INVOICE = "CUSTOMER_INVOICE";
 const ASANA_WON_LOST_SECTION_GIDS = new Set([
     "1211678338364908",
     "1211678338364907",
@@ -261,6 +262,16 @@ const billAttachmentContentTypeForFileName = (fileName) => {
     }
     return resolvedContentType;
 };
+const QUOTATION_ATTACHMENT_MAX_SIZE = 20 * 1024 * 1024;
+const quotationAttachmentContentTypeForFileName = (fileName) => {
+    const resolvedContentType = contentTypeHeaderForFileName(fileName);
+    if (resolvedContentType === "application/pdf" ||
+        resolvedContentType === "image/jpeg" ||
+        resolvedContentType === "image/png") {
+        return resolvedContentType;
+    }
+    throw new Error(`Unsupported quotation attachment type: ${fileName}. Use PDF, JPEG, or PNG.`);
+};
 const LOCKED_BUDGET_STATUSES_REQUIRING_CONFIRMATION = new Set([
     BudgetStatus.ESTIMATE_CREATED,
     BudgetStatus.ESTIMATE_SENT,
@@ -533,6 +544,10 @@ export async function listApprovals(opts) {
             id = n.supplierQuotation.id;
             name = `Quotation ${n.supplierQuotation.supplier.name}`;
         }
+        else if (n.type === CUSTOMER_INVOICE && n.customerInvoiceBatch) {
+            id = n.customerInvoiceBatch.id;
+            name = `Customer invoice ${n.customerInvoiceBatch.project.name}`;
+        }
         else {
             id = n.id;
             name = "Unknown";
@@ -668,6 +683,13 @@ export async function stageBillAttachmentsFromPaths(projectId, filePaths) {
         attachments,
     });
 }
+export const cleanupStagedBillAttachments = async (projectId, keys) => {
+    const result = await api.attachment.deleteStagedBillAttachments.mutate({
+        projectId,
+        keys,
+    });
+    out(result);
+};
 export async function uploadBillAttachmentFromPath(billId, filePath, type = "BILL") {
     const confirmed = await uploadSingleBillAttachmentFromPath(billId, filePath, type);
     out(confirmed);
@@ -740,6 +762,10 @@ export async function uploadBillDocumentsFromPaths({ billId, invoicePaths = [],
 export async function uploadQuotationAttachmentFromPath(projectId, filePath) {
     const buf = await readFile(filePath);
     const fileName = basename(filePath);
+    if (buf.byteLength > QUOTATION_ATTACHMENT_MAX_SIZE) {
+        throw new Error("Quotation attachment must be 20MB or smaller.");
+    }
+    const attachmentContentType = quotationAttachmentContentTypeForFileName(fileName);
     const ext = fileName
         .split(".")
         .pop()
@@ -752,7 +778,7 @@ export async function uploadQuotationAttachmentFromPath(projectId, filePath) {
     const res = await fetch(uploadUrl, {
         method: "PUT",
         body: buf,
-        headers: { "Content-Type": contentTypeHeaderForFileName(fileName) },
+        headers: { "Content-Type": attachmentContentType },
     });
     if (!res.ok) {
         throw new Error(`S3 upload failed: HTTP ${res.status} ${(await res.text()).slice(0, 500)}`);
@@ -764,6 +790,13 @@ export async function uploadQuotationAttachmentFromPath(projectId, filePath) {
         size: buf.byteLength,
     });
 }
+export const cleanupStagedQuotationAttachments = async (projectId, keys) => {
+    const result = await api.quotation.deleteStagedAttachments.mutate({
+        projectId,
+        keys,
+    });
+    out(result);
+};
 export async function uploadBudgetAttachmentFromPath(budgetId, filePath) {
     await confirmLockedBudgetChangeByBudgetId(budgetId, "Upload budget attachment");
     const buf = await readFile(filePath);
@@ -990,6 +1023,68 @@ export async function updateBudgetDiscountFromPayload(raw) {
     const result = await api.budget.updateBudgetDiscount.mutate(input);
     out(result);
 }
+export const deleteBudgetDiscount = async (budgetId) => {
+    await assertSensitiveWorkflowConfirmed({
+        action: "Remove budget discount",
+        entity: `budget ${budgetId}`,
+        details: "and return the budget to DRAFT",
+    });
+    const result = await api.budget.deleteBudgetDiscount.mutate({ budgetId });
+    out(result);
+};
+export const deleteBudgetCommission = async (budgetId) => {
+    await assertSensitiveWorkflowConfirmed({
+        action: "Remove budget commission",
+        entity: `budget ${budgetId}`,
+        details: "and return the budget to DRAFT",
+    });
+    const result = await api.budget.deleteBudgetCommission.mutate({ budgetId });
+    out(result);
+};
+export const setBudgetItemsNotUtilized = async (budgetItemIds, notUtilized) => {
+    await assertSensitiveWorkflowConfirmed({
+        action: notUtilized
+            ? "Mark budget lines Not Utilized"
+            : "Restore budget line",
+        entity: `budget item${budgetItemIds.length === 1 ? "" : "s"} ${budgetItemIds.join(", ")}`,
+        details: notUtilized
+            ? "and remove linked QuickBooks placeholder expenses"
+            : "and restore its QuickBooks placeholder expense when required",
+    });
+    const result = await api.budget.setBudgetItemsNotUtilized.mutate({
+        budgetItemIds,
+        notUtilized,
+    });
+    out(result);
+};
+export const createPlaceholderBillForBudgetItem = async (budgetItemId) => {
+    await assertSensitiveWorkflowConfirmed({
+        action: "Create QuickBooks placeholder bill",
+        entity: `budget item ${budgetItemId}`,
+    });
+    const result = await api.budget.createPlaceholderBillForBudgetItem.mutate({
+        budgetItemId,
+    });
+    out(result);
+};
+export const renameBudgetVersion = async (versionId, newName) => {
+    const result = await api.budgetVersion.renameBudgetVersion.mutate({
+        versionId,
+        newName,
+    });
+    out(result);
+};
+export const restoreBudgetVersion = async (versionId) => {
+    await assertSensitiveWorkflowConfirmed({
+        action: "Restore budget version",
+        entity: `budget version ${versionId}`,
+        details: "replace the current budget, project fields, items, and attachments, clear its QuickBooks estimate link, and return it to DRAFT",
+    });
+    const result = await api.budgetVersion.restoreBudgetVersion.mutate({
+        versionId,
+    });
+    out(result);
+};
 export async function deleteItemById(itemId) {
     const result = await api.item.deleteItem.mutate({ id: itemId });
     out(result);
@@ -1044,9 +1139,19 @@ export async function getQuotationDetails(id) {
     out(result);
 }
 export async function createQuotationFromPayload(raw) {
-    const result = await api.quotation.createDraft.mutate(raw);
+    const input = parseCreateQuotationPayload(raw);
+    const result = await api.quotation.createDraft.mutate(input);
     out(result);
 }
+export const updateQuotationFromPayload = async (raw) => {
+    const input = parseUpdateQuotationPayload(raw);
+    const result = await api.quotation.updateDraftOrRejected.mutate(input);
+    out(result);
+};
+export const deleteQuotationById = async (id) => {
+    const result = await api.quotation.delete.mutate({ id });
+    out(result);
+};
 export async function submitQuotation(id) {
     await assertSensitiveWorkflowConfirmed({
         action: "Submit quotation for approval",
@@ -1062,11 +1167,121 @@ export async function downloadQuotationPdf(id, fileRole) {
     });
     out(result);
 }
+export const checkCustomerInvoiceReadiness = async (budgetId) => {
+    const result = await api.customerInvoice.getInvoiceReadiness.query({
+        budgetId,
+    });
+    out(result);
+};
+export const listCustomerInvoices = async (input) => {
+    const result = await api.customerInvoice.listByBudget.query(input);
+    out(result);
+};
+export const getCustomerInvoice = async (batchId) => {
+    const result = await api.customerInvoice.getInvoiceDetail.query({ batchId });
+    out(result);
+};
+export const createCustomerInvoice = async (raw) => {
+    const input = parseCreateCustomerInvoicePayload(raw);
+    await assertSensitiveWorkflowConfirmed({
+        action: "Create customer invoice",
+        entity: `budget ${input.budgetId}`,
+        details: "create the invoice in QuickBooks and either approve it as admin or send approval-request emails",
+    });
+    const result = await api.customerInvoice.createInvoiceBatch.mutate(input);
+    out(result);
+};
+export const discardCreatingCustomerInvoice = async (batchId) => {
+    await assertSensitiveWorkflowConfirmed({
+        action: "Discard unfinished customer invoice",
+        entity: `invoice batch ${batchId}`,
+    });
+    const result = await api.customerInvoice.discardCreatingInvoiceBatch.mutate({
+        batchId,
+    });
+    out(result);
+};
+export const deleteCustomerInvoice = async (batchId) => {
+    await assertSensitiveWorkflowConfirmed({
+        action: "Delete customer invoice",
+        entity: `invoice batch ${batchId}`,
+        details: "delete its invoices from QuickBooks and remove the local batch",
+    });
+    const result = await api.customerInvoice.deleteInvoiceBatch.mutate({
+        batchId,
+    });
+    out(result);
+};
+export const voidCustomerInvoice = async (batchId) => {
+    await assertSensitiveWorkflowConfirmed({
+        action: "Void customer invoice",
+        entity: `invoice batch ${batchId}`,
+        details: "void its invoices in QuickBooks",
+    });
+    const result = await api.customerInvoice.voidInvoiceBatch.mutate({ batchId });
+    out(result);
+};
+export const approveCustomerInvoice = async (batchId) => {
+    await assertSensitiveWorkflowConfirmed({
+        action: "Approve customer invoice",
+        entity: `invoice batch ${batchId}`,
+        details: "and notify its creator",
+    });
+    const result = await api.customerInvoice.approveInvoiceBatch.mutate({
+        batchId,
+    });
+    out(result);
+};
+export const rejectCustomerInvoice = async (batchId, rejectionReason) => {
+    await assertSensitiveWorkflowConfirmed({
+        action: "Reject customer invoice",
+        entity: `invoice batch ${batchId}`,
+        details: `with reason "${rejectionReason}", void it in QuickBooks, and notify its creator`,
+    });
+    const result = await api.customerInvoice.rejectInvoiceBatch.mutate({
+        batchId,
+        rejectionReason,
+    });
+    out(result);
+};
+export const downloadCustomerInvoicePdf = async (invoiceId, outputPath) => {
+    const result = await api.customerInvoice.downloadPdf.mutate({ invoiceId });
+    const resolvedOutputPath = outputPath?.trim() || result.fileName;
+    const contents = Buffer.from(result.base64, "base64");
+    await writeFile(resolvedOutputPath, contents);
+    out({
+        contentType: result.contentType,
+        fileName: result.fileName,
+        outputPath: resolvedOutputPath,
+        size: contents.byteLength,
+    });
+};
+export const syncCustomerInvoice = async (invoiceId) => {
+    await assertSensitiveWorkflowConfirmed({
+        action: "Sync customer invoice from QuickBooks",
+        entity: `invoice ${invoiceId}`,
+        details: "and update its local status, QuickBooks metadata, balance, and history",
+    });
+    const result = await api.customerInvoice.syncInvoiceStatus.mutate({
+        invoiceId,
+    });
+    out(result);
+};
 export async function updateBillFromPayload(raw) {
     const input = parseUpdateBillPayload(raw);
     const result = await api.bill.update.mutate(input);
     out(result);
 }
+export const validateBillSelectionFromPayload = async (raw) => {
+    const input = parseValidateBillSelectionPayload(raw);
+    const result = await api.bill.validateSelection.mutate(input);
+    out(result);
+};
+export const updateBillPaymentEvidenceFromPayload = async (raw) => {
+    const input = parseUpdateBillPaymentEvidencePayload(raw);
+    const result = await api.bill.updatePaymentEvidence.mutate(input);
+    out(result);
+};
 export async function deleteBillById(id) {
     const result = await api.bill.delete.mutate({ id });
     out(result);
@@ -1576,6 +1791,47 @@ export async function updateProjectStatus(id, status, opts) {
     });
     out(result);
 }
+export const checkProjectReconciliation = async (projectId) => {
+    const result = await api.project.getReconciliationReview.query({ projectId });
+    out(result);
+};
+export const reconcileProject = async (projectId) => {
+    await assertSensitiveWorkflowConfirmed({
+        action: "Reconcile project",
+        entity: `project ${projectId}`,
+        details: "rerun all reconciliation checks and mark it RECONCILED",
+    });
+    const result = await api.project.reconcile.mutate({ projectId });
+    out(result);
+};
+export const completeProject = async (projectId) => {
+    await updateProjectStatus(projectId, ProjectStatus.COMPLETED);
+};
+export const importQuickBooksProjectId = async (projectId, projectUrl) => {
+    const result = await api.project.importQboProjectId.mutate({
+        projectId,
+        projectUrl,
+    });
+    out(result);
+};
+export const listIntegrationOperations = async (input) => {
+    const result = await api.integration.listOperations.query(input);
+    out(result);
+};
+export const retryIntegrationOperation = async (operationId, confirmExternalStateReconciled) => {
+    await assertSensitiveWorkflowConfirmed({
+        action: "Retry integration operation",
+        entity: `operation ${operationId}`,
+        details: confirmExternalStateReconciled
+            ? "after confirming the external state has been reconciled"
+            : undefined,
+    });
+    const result = await api.integration.retryOperation.mutate({
+        operationId,
+        confirmExternalStateReconciled,
+    });
+    out(result);
+};
 // --- Contacts ---
 export async function listContacts(companyId) {
     const contacts = await api.contactPerson.getContactPersonByCompanyId.query({

package/dist/index.js

@@ -2,9 +2,9 @@
 import "./load-env.js";
 import { requireApiKey } from "./api-client.js";
 import { consumeCliQuietFlags, logCliAction, sanitizeFlagsForTrace, setCliQuiet, shouldLogCliActions, } from "./cli-trace.js";
-import { addBudgetItems, approveBill, approveBudget, approveQuotation, approveSupplier, createApiKeyForUser, createBillApproval, createBillFromPayload, createBudgetApproval, createBudgetCategory, createBudgetFromPayload, createCompany, createContactPersonFromPayload, createEstimate, createItemCategory, createItemFromPayload, createProject, createQuotationFromPayload, createSupplierCertification, createSupplierFromPayload, createSupplierPaymentMethod, createSupplierRoleOption, createSupplierTagOption, createUser, deleteBillById, deleteBudgetById, deleteBudgetCategory, deleteCompanyById, deleteItemById, deleteItemCategoriesByIds, deleteProjectById, deleteSuppliersByIds, downloadQuotationPdf, getApprovedBudgets, getBillAttachments, getBillDetails, getBudget, getBudgetCategories, getBudgetCategoryBenchmarks, getBudgetDetails, getBudgetItemsOnly, getBudgetVersions, getCompany, getDashboard, getErrorMetrics, getEstimatePerformance, getFinancialOverview, getItem, getItemPricingHistory, getMonthlyMetrics, getProject, getQuotationDetails, getRecentErrors, getSupplierAnalytics, getSupplierDetails, getSupplierPricingHistory, getSystemOverview, getUserPerformance, listApiKeysForUser, listApprovals, listBills, listBudgets, listCompanies, listContacts, listItemCategories, listItems, listProjects, listQuotations, listSuppliers, listUsers, markBudgetWonWithProof, patchBillInvoiceNumber, patchBillPayment, reactivateSuppliersByIds, rejectBill, rejectBudget, rejectQuotation, rejectSupplier, removeBudgetItem, reorderBudgetItemsCli, revokeApiKeyForUser, stageBillAttachmentsFromPaths, submitQuotation, updateBillFromPayload, updateBillStatus, updateBudgetCategory, updateBudgetCommissionFromPayload, updateBudgetDiscountFromPayload, updateBudgetFromPayload, updateBudgetItem, updateBudgetItemSupplierCli, updateBudgetStatus, updateCompanyFromPayload, updateContactPersonFromPayload, updateItemCategory, updateItemFromPayload, updateProjectFromPayload, updateProjectStatus, updateSupplierFromPayload, uploadBillAttachmentFromPath, uploadBillAttachmentsFromPaths, uploadBillDocumentsFromPaths, uploadBudgetAttachmentFromPath, uploadQuotationAttachmentFromPath, } from "./commands.js";
+import { addBudgetItems, approveBill, approveBudget, approveCustomerInvoice, approveQuotation, approveSupplier, checkCustomerInvoiceReadiness, checkProjectReconciliation, cleanupStagedBillAttachments, cleanupStagedQuotationAttachments, completeProject, createApiKeyForUser, createBillApproval, createBillFromPayload, createBudgetApproval, createBudgetCategory, createBudgetFromPayload, createCompany, createContactPersonFromPayload, createCustomerInvoice, createEstimate, createItemCategory, createItemFromPayload, createPlaceholderBillForBudgetItem, createProject, createQuotationFromPayload, createSupplierCertification, createSupplierFromPayload, createSupplierPaymentMethod, createSupplierRoleOption, createSupplierTagOption, createUser, deleteBillById, deleteBudgetById, deleteBudgetCategory, deleteBudgetCommission, deleteBudgetDiscount, deleteCompanyById, deleteCustomerInvoice, deleteItemById, deleteItemCategoriesByIds, deleteProjectById, deleteQuotationById, deleteSuppliersByIds, discardCreatingCustomerInvoice, downloadCustomerInvoicePdf, downloadQuotationPdf, getApprovedBudgets, getBillAttachments, getBillDetails, getBudget, getBudgetCategories, getBudgetCategoryBenchmarks, getBudgetDetails, getBudgetItemsOnly, getBudgetVersions, getCompany, getCustomerInvoice, getDashboard, getErrorMetrics, getEstimatePerformance, getFinancialOverview, getItem, getItemPricingHistory, getMonthlyMetrics, getProject, getQuotationDetails, getRecentErrors, getSupplierAnalytics, getSupplierDetails, getSupplierPricingHistory, getSystemOverview, getUserPerformance, importQuickBooksProjectId, listApiKeysForUser, listApprovals, listBills, listBudgets, listCompanies, listContacts, listCustomerInvoices, listIntegrationOperations, listItemCategories, listItems, listProjects, listQuotations, listSuppliers, listUsers, markBudgetWonWithProof, patchBillInvoiceNumber, patchBillPayment, reactivateSuppliersByIds, reconcileProject, rejectBill, rejectBudget, rejectCustomerInvoice, rejectQuotation, rejectSupplier, removeBudgetItem, renameBudgetVersion, reorderBudgetItemsCli, restoreBudgetVersion, retryIntegrationOperation, revokeApiKeyForUser, setBudgetItemsNotUtilized, stageBillAttachmentsFromPaths, submitQuotation, syncCustomerInvoice, updateBillFromPayload, updateBillPaymentEvidenceFromPayload, updateBillStatus, updateBudgetCategory, updateBudgetCommissionFromPayload, updateBudgetDiscountFromPayload, updateBudgetFromPayload, updateBudgetItem, updateBudgetItemSupplierCli, updateBudgetStatus, updateCompanyFromPayload, updateContactPersonFromPayload, updateItemCategory, updateItemFromPayload, updateProjectFromPayload, updateProjectStatus, updateQuotationFromPayload, updateSupplierFromPayload, uploadBillAttachmentFromPath, uploadBillAttachmentsFromPaths, uploadBillDocumentsFromPaths, uploadBudgetAttachmentFromPath, uploadQuotationAttachmentFromPath, validateBillSelectionFromPayload, voidCustomerInvoice, } from "./commands.js";
 import { getFlag, parseArgs } from "./parse-args.js";
-import { billStatusesForUpdateHelp, budgetStatusesForHelp, isBudgetStatusUpdate, parseApprovalTypeFlag, parseBillStatusForUpdate, parseCommaSeparatedBillStatuses, parseCommaSeparatedBudgetStatuses, parseCommaSeparatedIds, parseCommaSeparatedSupplierStatuses, parseOptionalBillListSortBy, parseOptionalBillListSortDir, parseOptionalDashboardRole, parseOptionalDeals, parseOptionalErrorSeverity, parseOptionalErrorStatus, parseOptionalExtendedProjectStatus, parseOptionalFinancialRole, parseOptionalSupplierAnalyticsTimeFrame, parseOptionalTimeFrame, parseProjectStatusForUpdate, parseUserRole, projectStatusesForHelp, userRolesForHelp, } from "./parse-cli-enums.js";
+import { billStatusesForUpdateHelp, budgetStatusesForHelp, isBudgetStatusUpdate, parseApprovalTypeFlag, parseBillStatusForUpdate, parseCommaSeparatedBillStatuses, parseCommaSeparatedBudgetStatuses, parseCommaSeparatedCustomerInvoiceStatuses, parseCommaSeparatedIds, parseCommaSeparatedQuotationStatuses, parseCommaSeparatedSupplierStatuses, parseOptionalBillListSortBy, parseOptionalBillListSortDir, parseOptionalDashboardRole, parseOptionalDeals, parseOptionalErrorSeverity, parseOptionalErrorStatus, parseOptionalExtendedProjectStatus, parseOptionalFinancialRole, parseOptionalSupplierAnalyticsTimeFrame, parseOptionalTimeFrame, parseProjectStatusForUpdate, parseUserRole, projectStatusesForHelp, userRolesForHelp, } from "./parse-cli-enums.js";
 import { parseJsonFlag, parseOptionalNumber as parseOptNum, } from "./parse-json-flag.js";
 function parsePositiveIntFlag(value, flagName) {
     if (value === undefined)
@@ -26,6 +26,35 @@ function parseOptionalBoolFlag(flags, key) {
         return false;
     throw new Error(`--${key} must be true or false.`);
 }
+const CUSTOMER_INVOICE_SORT_FIELDS = [
+    "createdAt",
+    "status",
+    "totalNetAmount",
+    "approvalExpiresAt",
+];
+function parseCustomerInvoiceSortBy(value) {
+    if (value === undefined)
+        return "createdAt";
+    if (!CUSTOMER_INVOICE_SORT_FIELDS.includes(value)) {
+        throw new Error(`Invalid --sortBy "${value}". Use one of: ${CUSTOMER_INVOICE_SORT_FIELDS.join(", ")}.`);
+    }
+    return value;
+}
+const INTEGRATION_OPERATION_STATUSES = [
+    "PENDING",
+    "PROCESSING",
+    "FAILED",
+    "COMPLETED",
+];
+function parseIntegrationOperationStatus(value) {
+    if (value === undefined)
+        return undefined;
+    const normalized = value.toUpperCase();
+    if (!INTEGRATION_OPERATION_STATUSES.includes(normalized)) {
+        throw new Error(`Invalid --status "${value}". Use one of: ${INTEGRATION_OPERATION_STATUSES.join(", ")}.`);
+    }
+    return normalized;
+}
 function parseCommercialRejectionProjectStatus(flags) {
     const raw = flags.projectStatusOnCommercialRejection;
     if (raw === undefined)
@@ -120,8 +149,9 @@ Global: --quiet | -q | BB_CLI_QUIET=1 — hide action logs (default: log command
 Auth: Set BB_API_KEY in the environment (same API key as MCP / Goracle).
 
 Sensitive workflow changes: approval decisions/requests, entity status updates,
-mark-budget-won, submit-quotation, and supplier approval request side effects
-require an interactive CONFIRM prompt and abort in non-interactive shells.
+customer invoices, integration retries, mark-budget-won, submit-quotation, and
+supplier approval request side effects require an interactive CONFIRM prompt
+and abort in non-interactive shells.
 AI agents must inspect the entity first, summarize the exact entity, target
 state, and side effects, then wait for explicit user confirmation before running
 the sensitive command.
@@ -133,6 +163,8 @@ Budgets
   get-budget-details <id>    Full detail (margins, suppliers, etc.)
   get-budget-categories
   get-budget-versions <budgetId>
+  rename-budget-version <versionId> --name <text>
+  restore-budget-version <versionId>   Replace current budget data and return it to DRAFT.
   update-budget-status <id> <status> [--projectManagerId <id>] [--markProjectWon true|false] [--projectStatusOnCommercialRejection PITCH|LOST]
     Budget-changing commands require interactive "yes" confirmation when the current budget is ESTIMATE_CREATED, ESTIMATE_SENT, ESTIMATE_ACCEPTED, ESTIMATE_REJECTED, or ESTIMATE_CLOSED.
     ESTIMATE_ACCEPTED requires win proof, auto-marks PITCH or LOST projects WON, requires --projectManagerId when the project has no PM, and auto-creates the Asana project/section when enabled.
@@ -154,6 +186,11 @@ Budgets
   delete-budget-category <id>
   update-budget-commission   --payload '<json>'  (budget.updateBudgetCommission)
   update-budget-discount     --payload '<json>'  (budget.updateBudgetDiscount; type percentage|amount)
+  delete-budget-commission <budgetId>   Remove commission and return the budget to DRAFT.
+  delete-budget-discount <budgetId>     Remove discount and return the budget to DRAFT.
+  mark-budget-items-not-utilized --ids <csv>   Remove unused lines from reconciliation and clear QBO placeholders.
+  restore-budget-item <budgetItemId>           Restore one Not Utilized line and its QBO placeholder when required.
+  create-placeholder-bill <budgetItemId>       Admin-only placeholder recovery.
   upload-budget-attachment <budgetId> <filePath>   Presigned S3 upload + confirm
 
 Bills
@@ -163,8 +200,11 @@ Bills
     New supplier bills from 1 Jul 2026 00:00 SGT require approved quotation coverage for each non-legacy line item.
   create-bill-approval <billId>       (also sends approval request emails)
   create-bill                --payload '<json>'  (bill.create; payload.isClaimable false = bill, true = claim)
+  validate-bill-selection    --payload '<json>'  Check projectId, supplierId, budgetItemIds, and optional alreadyPaid before creation.
   stage-bill-attachment <projectId> <filePath...> [--file <path>] [--files <csv>]   Upload files before create-bill; returns attachment JSON for attachments/paymentProofAttachments
+  cleanup-staged-bill-attachments <projectId> --keys <csv>   Delete unattached staged bill/claim uploads.
   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]
     status (${billStatusesForUpdateHelp.join(", ")}) — not PENDING_APPROVAL; use create-bill-approval
@@ -179,17 +219,33 @@ Bills
   get-bill-details <billId>
 
 Quotations
-  list-quotations            [--projectId] [--budgetId] [--supplierId] [--status CSV] [--page] [--pageSize]
+  list-quotations            [--projectId] [--budgetId] [--supplierId] [--status CSV] [--requesterIds CSV] [--search] [--page] [--pageSize]
   get-quotation <quotationId>
-  upload-quotation-attachment <projectId> <filePath>   Presigned S3 upload; returns attachment JSON for create-quotation payload
+  upload-quotation-attachment <projectId> <filePath>   Upload one PDF, JPEG, or PNG up to 20MB; returns attachment JSON for a quotation payload.
+  cleanup-staged-quotation-attachments <projectId> --keys <csv>   Delete unattached staged quotation uploads.
   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>
   reject-quotation <quotationId> --reason <text>
   download-quotation-pdf <quotationId> [original|staff|final]
 
+Customer invoices
+  check-customer-invoice-readiness <budgetId>
+  list-customer-invoices <budgetId> [--status CSV] [--search] [--sortBy createdAt|status|totalNetAmount|approvalExpiresAt] [--sortDir asc|desc] [--page] [--perPage]
+  get-customer-invoice <batchId>
+  create-customer-invoice --payload '<json>'   budgetId + one split with label, percentage, and dueDate.
+  discard-customer-invoice <batchId>           Discard a reserved CREATING batch with no created QBO invoices.
+  delete-customer-invoice <batchId>            Delete QBO invoices and the local batch.
+  void-customer-invoice <batchId>              Void the invoice batch in QuickBooks.
+  approve-customer-invoice <batchId>           Admin approval; notifies the creator.
+  reject-customer-invoice <batchId> --reason <text>   Admin rejection; voids QBO invoices and notifies the creator.
+  download-customer-invoice-pdf <invoiceId> [--output <path>]
+  sync-customer-invoice <invoiceId>             Refresh local status and balance from QuickBooks.
+
 Approvals
-  list-approvals | get-pending-approvals   [--type budget|supplier|bill|quotation|all]
+  list-approvals | get-pending-approvals   [--type budget|supplier|bill|quotation|customer_invoice|all]
   approve-bill <billId>               (also sends requester reply email)
   reject-bill <billId> --reason <text> (also sends requester reply email)
   approve-budget <budgetId>           (also sends requester reply email)
@@ -211,8 +267,12 @@ Companies & projects
   create-project             --name --companyId --contactPersonId --insideSalesId --businessDevelopmentId --venue --startDate <ISO> [--projectManagerId <userId>] [--asanaTaskId] [--asanaSearch <text>] [--slackChannelId --slackChannelUrl --slackChannelName] [--pax] [--endDate <ISO>] [--description]
   update-project             --payload '<json>'  (project.updateProject; optional projectManagerId and requestQboAccountantNotification; default notify like web)
   delete-project <id>
+  check-project-reconciliation <id>   Run the same live reconciliation review as the web app without changing status.
+  reconcile-project <id>              Rerun all checks transactionally and mark an eligible WON project RECONCILED.
+  complete-project <id>               Rerun reconciliation validation, mark a RECONCILED project COMPLETED, and queue QBO placeholder cleanup.
+  import-qbo-project <projectId> --url <quickBooksProjectUrl>
   update-project-status <id> <status> [--projectManagerId <userId>] [--projectManagerEmail <email>] [--wonOverrideReason <text>]
-	Required when moving PITCH → WON: supply --projectManagerId or --projectManagerEmail.
+    Required when moving PITCH → WON: supply --projectManagerId or --projectManagerEmail.
     Required when moving to WON without accepted/closed budget or win proof: --wonOverrideReason (10+ chars).
     status: ${projectStatusesForHelp.join(", ")}
 
@@ -261,6 +321,10 @@ Errors
   get-recent-errors          [--page] [--perPage] [--severity] [--status]
   get-error-metrics
 
+Automation (admin)
+  list-integration-operations [--destination] [--status PENDING|PROCESSING|FAILED|COMPLETED] [--page] [--perPage]
+  retry-integration-operation <operationId> [--confirmExternalStateReconciled true|false]
+
 Historical / benchmarks
   get-approved-budgets       [--projectId] [--limit] [--minRevenue] [--maxRevenue]
   get-budget-category-benchmarks <categoryId> [--limit]
@@ -377,6 +441,23 @@ async function main() {
                 await getBudgetVersions(id);
                 break;
             }
+            case "rename-budget-version": {
+                const versionId = positional[0];
+                const newName = getFlag(flags, "name");
+                if (!versionId || newName === undefined) {
+                    throw new Error("rename-budget-version requires <versionId> --name <text>");
+                }
+                await renameBudgetVersion(versionId, String(newName));
+                break;
+            }
+            case "restore-budget-version": {
+                const versionId = positional[0];
+                if (!versionId) {
+                    throw new Error("restore-budget-version requires <versionId>");
+                }
+                await restoreBudgetVersion(versionId);
+                break;
+            }
             case "update-budget-status": {
                 const [id, status] = positional;
                 if (!id || !status) {
@@ -560,6 +641,46 @@ async function main() {
                 await updateBudgetDiscountFromPayload(raw);
                 break;
             }
+            case "delete-budget-commission": {
+                const budgetId = positional[0];
+                if (!budgetId) {
+                    throw new Error("delete-budget-commission requires <budgetId>");
+                }
+                await deleteBudgetCommission(budgetId);
+                break;
+            }
+            case "delete-budget-discount": {
+                const budgetId = positional[0];
+                if (!budgetId) {
+                    throw new Error("delete-budget-discount requires <budgetId>");
+                }
+                await deleteBudgetDiscount(budgetId);
+                break;
+            }
+            case "mark-budget-items-not-utilized": {
+                const budgetItemIds = parseCommaSeparatedIds(getFlag(flags, "ids"));
+                if (!budgetItemIds?.length) {
+                    throw new Error("mark-budget-items-not-utilized requires --ids <csv>");
+                }
+                await setBudgetItemsNotUtilized(budgetItemIds, true);
+                break;
+            }
+            case "restore-budget-item": {
+                const budgetItemId = positional[0];
+                if (!budgetItemId) {
+                    throw new Error("restore-budget-item requires <budgetItemId>");
+                }
+                await setBudgetItemsNotUtilized([budgetItemId], false);
+                break;
+            }
+            case "create-placeholder-bill": {
+                const budgetItemId = positional[0];
+                if (!budgetItemId) {
+                    throw new Error("create-placeholder-bill requires <budgetItemId>");
+                }
+                await createPlaceholderBillForBudgetItem(budgetItemId);
+                break;
+            }
             case "list-bills": {
                 await listBills(parseListBillsFlags(flags));
                 break;
@@ -587,6 +708,15 @@ async function main() {
                 await createBillFromPayload(raw);
                 break;
             }
+            case "validate-bill-selection": {
+                const payloadRaw = getFlag(flags, "payload");
+                if (!payloadRaw) {
+                    throw new Error("validate-bill-selection requires --payload '<json>'");
+                }
+                const raw = parseJsonFlag(String(payloadRaw), "--payload");
+                await validateBillSelectionFromPayload(raw);
+                break;
+            }
             case "update-bill": {
                 const payloadRaw = getFlag(flags, "payload");
                 if (!payloadRaw) {
@@ -596,6 +726,15 @@ async function main() {
                 await updateBillFromPayload(raw);
                 break;
             }
+            case "update-bill-payment-evidence": {
+                const payloadRaw = getFlag(flags, "payload");
+                if (!payloadRaw) {
+                    throw new Error("update-bill-payment-evidence requires --payload '<json>'");
+                }
+                const raw = parseJsonFlag(String(payloadRaw), "--payload");
+                await updateBillPaymentEvidenceFromPayload(raw);
+                break;
+            }
             case "delete-bill": {
                 const id = positional[0];
                 if (!id)
@@ -714,6 +853,15 @@ async function main() {
                 await stageBillAttachmentsFromPaths(projectId, filePaths);
                 break;
             }
+            case "cleanup-staged-bill-attachments": {
+                const projectId = positional[0];
+                const keys = parseCommaSeparatedIds(getFlag(flags, "keys"));
+                if (!projectId || !keys) {
+                    throw new Error("cleanup-staged-bill-attachments requires <projectId> --keys <csv>");
+                }
+                await cleanupStagedBillAttachments(projectId, keys);
+                break;
+            }
             case "upload-bill-attachment":
             case "attach-bill-attachment":
             case "attach-bill-payment-receipt": {
@@ -794,12 +942,9 @@ async function main() {
                     projectId: getFlag(flags, "projectId"),
                     budgetId: getFlag(flags, "budgetId"),
                     supplierId: getFlag(flags, "supplierId"),
-                    status: statusRaw !== undefined
-                        ? String(statusRaw)
-                            .split(",")
-                            .map((value) => value.trim().toUpperCase())
-                            .filter(Boolean)
-                        : undefined,
+                    status: parseCommaSeparatedQuotationStatuses(statusRaw),
+                    requesterIds: parseCommaSeparatedIds(getFlag(flags, "requesterIds")),
+                    search: getFlag(flags, "search"),
                     page: getFlag(flags, "page") !== undefined
                         ? Number(getFlag(flags, "page"))
                         : undefined,
@@ -824,6 +969,15 @@ async function main() {
                 await uploadQuotationAttachmentFromPath(projectId, filePath);
                 break;
             }
+            case "cleanup-staged-quotation-attachments": {
+                const projectId = positional[0];
+                const keys = parseCommaSeparatedIds(getFlag(flags, "keys"));
+                if (!projectId || !keys) {
+                    throw new Error("cleanup-staged-quotation-attachments requires <projectId> --keys <csv>");
+                }
+                await cleanupStagedQuotationAttachments(projectId, keys);
+                break;
+            }
             case "create-quotation": {
                 const payloadRaw = getFlag(flags, "payload");
                 if (!payloadRaw) {
@@ -833,6 +987,22 @@ async function main() {
                 await createQuotationFromPayload(raw);
                 break;
             }
+            case "update-quotation": {
+                const payloadRaw = getFlag(flags, "payload");
+                if (!payloadRaw) {
+                    throw new Error("update-quotation requires --payload '<json>'");
+                }
+                const raw = parseJsonFlag(String(payloadRaw), "--payload");
+                await updateQuotationFromPayload(raw);
+                break;
+            }
+            case "delete-quotation": {
+                const id = positional[0];
+                if (!id)
+                    throw new Error("delete-quotation requires <quotationId>");
+                await deleteQuotationById(id);
+                break;
+            }
             case "submit-quotation": {
                 const id = positional[0];
                 if (!id)
@@ -866,10 +1036,114 @@ async function main() {
                     ? "ORIGINAL"
                     : roleRaw === "staff"
                         ? "STAFF_SIGNED"
-                        : "FINAL_SIGNED";
+                        : roleRaw === "final"
+                            ? "FINAL_SIGNED"
+                            : null;
+                if (!fileRole) {
+                    throw new Error("download-quotation-pdf role must be original, staff, or final");
+                }
                 await downloadQuotationPdf(id, fileRole);
                 break;
             }
+            case "check-customer-invoice-readiness": {
+                const budgetId = positional[0];
+                if (!budgetId) {
+                    throw new Error("check-customer-invoice-readiness requires <budgetId>");
+                }
+                await checkCustomerInvoiceReadiness(budgetId);
+                break;
+            }
+            case "list-customer-invoices": {
+                const budgetId = positional[0];
+                if (!budgetId) {
+                    throw new Error("list-customer-invoices requires <budgetId>");
+                }
+                const statusRaw = getFlag(flags, "status");
+                const sortDir = parseOptionalBillListSortDir(getFlag(flags, "sortDir"));
+                await listCustomerInvoices({
+                    budgetId,
+                    page: parsePositiveIntFlag(getFlag(flags, "page"), "--page") ?? 1,
+                    perPage: parsePositiveIntFlag(getFlag(flags, "perPage"), "--perPage") ?? 12,
+                    q: getFlag(flags, "search") ?? "",
+                    statuses: parseCommaSeparatedCustomerInvoiceStatuses(statusRaw !== undefined ? String(statusRaw) : undefined),
+                    sortBy: parseCustomerInvoiceSortBy(getFlag(flags, "sortBy")),
+                    sortDir: sortDir ?? "desc",
+                });
+                break;
+            }
+            case "get-customer-invoice": {
+                const batchId = positional[0];
+                if (!batchId) {
+                    throw new Error("get-customer-invoice requires <batchId>");
+                }
+                await getCustomerInvoice(batchId);
+                break;
+            }
+            case "create-customer-invoice": {
+                const payloadRaw = getFlag(flags, "payload");
+                if (!payloadRaw) {
+                    throw new Error("create-customer-invoice requires --payload '<json>'");
+                }
+                await createCustomerInvoice(parseJsonFlag(String(payloadRaw), "--payload"));
+                break;
+            }
+            case "discard-customer-invoice": {
+                const batchId = positional[0];
+                if (!batchId) {
+                    throw new Error("discard-customer-invoice requires <batchId>");
+                }
+                await discardCreatingCustomerInvoice(batchId);
+                break;
+            }
+            case "delete-customer-invoice": {
+                const batchId = positional[0];
+                if (!batchId) {
+                    throw new Error("delete-customer-invoice requires <batchId>");
+                }
+                await deleteCustomerInvoice(batchId);
+                break;
+            }
+            case "void-customer-invoice": {
+                const batchId = positional[0];
+                if (!batchId) {
+                    throw new Error("void-customer-invoice requires <batchId>");
+                }
+                await voidCustomerInvoice(batchId);
+                break;
+            }
+            case "approve-customer-invoice": {
+                const batchId = positional[0];
+                if (!batchId) {
+                    throw new Error("approve-customer-invoice requires <batchId>");
+                }
+                await approveCustomerInvoice(batchId);
+                break;
+            }
+            case "reject-customer-invoice": {
+                const batchId = positional[0];
+                const reason = getFlag(flags, "reason");
+                if (!batchId || reason === undefined) {
+                    throw new Error("reject-customer-invoice requires <batchId> --reason <text>");
+                }
+                await rejectCustomerInvoice(batchId, String(reason));
+                break;
+            }
+            case "download-customer-invoice-pdf": {
+                const invoiceId = positional[0];
+                if (!invoiceId) {
+                    throw new Error("download-customer-invoice-pdf requires <invoiceId> [--output <path>]");
+                }
+                await downloadCustomerInvoicePdf(invoiceId, getFlag(flags, "output"));
+                break;
+            }
+            case "sync-customer-invoice": {
+                const invoiceId = positional[0];
+                if (!invoiceId) {
+                    throw new Error("sync-customer-invoice requires <invoiceId>");
+                }
+                await syncCustomerInvoice(invoiceId);
+                break;
+            }
             case "list-approvals":
             case "get-pending-approvals": {
                 const typeRaw = getFlag(flags, "type");
@@ -1057,6 +1331,37 @@ async function main() {
                 await deleteProjectById(id);
                 break;
             }
+            case "check-project-reconciliation": {
+                const id = positional[0];
+                if (!id) {
+                    throw new Error("check-project-reconciliation requires <id>");
+                }
+                await checkProjectReconciliation(id);
+                break;
+            }
+            case "reconcile-project": {
+                const id = positional[0];
+                if (!id)
+                    throw new Error("reconcile-project requires <id>");
+                await reconcileProject(id);
+                break;
+            }
+            case "complete-project": {
+                const id = positional[0];
+                if (!id)
+                    throw new Error("complete-project requires <id>");
+                await completeProject(id);
+                break;
+            }
+            case "import-qbo-project": {
+                const projectId = positional[0];
+                const projectUrl = getFlag(flags, "url");
+                if (!projectId || projectUrl === undefined) {
+                    throw new Error("import-qbo-project requires <projectId> --url <quickBooksProjectUrl>");
+                }
+                await importQuickBooksProjectId(projectId, String(projectUrl));
+                break;
+            }
             case "update-project-status": {
                 const [id, statusRaw] = positional;
                 if (!id || !statusRaw) {
@@ -1344,6 +1649,24 @@ async function main() {
                 await getErrorMetrics();
                 break;
             }
+            case "list-integration-operations": {
+                await listIntegrationOperations({
+                    destination: getFlag(flags, "destination"),
+                    page: parsePositiveIntFlag(getFlag(flags, "page"), "--page") ?? 1,
+                    perPage: parsePositiveIntFlag(getFlag(flags, "perPage"), "--perPage") ?? 25,
+                    status: parseIntegrationOperationStatus(getFlag(flags, "status")),
+                });
+                break;
+            }
+            case "retry-integration-operation": {
+                const operationId = positional[0];
+                if (!operationId) {
+                    throw new Error("retry-integration-operation requires <operationId>");
+                }
+                await retryIntegrationOperation(operationId, parseOptionalBoolFlag(flags, "confirmExternalStateReconciled") ??
+                    false);
+                break;
+            }
             case "get-approved-budgets": {
                 await getApprovedBudgets({
                     projectId: getFlag(flags, "projectId"),

package/dist/parse-cli-enums.js

@@ -1,8 +1,10 @@
 import { BudgetRole, Deals, ExtendedApprovalStatus, ExtendedBillStatus, ExtendedErrorSeverity, ExtendedErrorStatus, ExtendedProjectStatus, TimeFrame, } from "./filter-enums.js";
-import { BillStatus, BudgetStatus, ProjectStatus, UserRole, } from "./prisma-enums.js";
+import { BillStatus, BudgetStatus, CustomerInvoiceBatchStatus, ProjectStatus, SupplierQuotationStatus, UserRole, } from "./prisma-enums.js";
 const BUDGET_STATUS_VALUES = new Set(Object.values(BudgetStatus));
 const BILL_STATUS_VALUES = new Set(Object.values(BillStatus));
 const PROJECT_STATUS_VALUES = new Set(Object.values(ProjectStatus));
+const SUPPLIER_QUOTATION_STATUS_VALUES = new Set(Object.values(SupplierQuotationStatus));
+const CUSTOMER_INVOICE_BATCH_STATUS_VALUES = new Set(Object.values(CustomerInvoiceBatchStatus));
 const USER_ROLE_VALUES = new Set(Object.values(UserRole));
 const EXTENDED_PROJECT_STATUS_VALUES = new Set(Object.values(ExtendedProjectStatus));
 const DASHBOARD_ROLE_VALUES = new Set([
@@ -173,6 +175,38 @@ export function parseCommaSeparatedSupplierStatuses(raw) {
     }
     return out;
 }
+export function parseCommaSeparatedQuotationStatuses(raw) {
+    if (raw === undefined)
+        return undefined;
+    const parts = raw
+        .split(",")
+        .map((value) => value.trim().toUpperCase())
+        .filter(Boolean);
+    if (parts.length === 0)
+        return undefined;
+    for (const status of parts) {
+        if (!SUPPLIER_QUOTATION_STATUS_VALUES.has(status)) {
+            throw new Error(`Invalid quotation status "${status}". Use one of: ${[...SUPPLIER_QUOTATION_STATUS_VALUES].join(", ")}.`);
+        }
+    }
+    return parts;
+}
+export function parseCommaSeparatedCustomerInvoiceStatuses(raw) {
+    if (raw === undefined)
+        return undefined;
+    const parts = raw
+        .split(",")
+        .map((value) => value.trim().toUpperCase())
+        .filter(Boolean);
+    if (parts.length === 0)
+        return undefined;
+    for (const status of parts) {
+        if (!CUSTOMER_INVOICE_BATCH_STATUS_VALUES.has(status)) {
+            throw new Error(`Invalid customer invoice status "${status}". Use one of: ${[...CUSTOMER_INVOICE_BATCH_STATUS_VALUES].join(", ")}.`);
+        }
+    }
+    return parts;
+}
 export function parseBillStatusFlag(raw) {
     if (raw === undefined)
         return undefined;
@@ -225,7 +259,11 @@ export function parseOptionalBillListSortDir(raw) {
     return raw;
 }
 function isPendingRequestType(s) {
-    return (s === "BUDGET" || s === "BILL" || s === "SUPPLIER" || s === "QUOTATION");
+    return (s === "BUDGET" ||
+        s === "BILL" ||
+        s === "SUPPLIER" ||
+        s === "QUOTATION" ||
+        s === "CUSTOMER_INVOICE");
 }
 export function parseApprovalTypeFlag(raw) {
     if (raw === undefined)
@@ -234,7 +272,7 @@ export function parseApprovalTypeFlag(raw) {
     if (u === "ALL")
         return "ALL";
     if (!isPendingRequestType(u)) {
-        throw new Error(`Invalid --type "${raw}". Use budget, supplier, bill, quotation, or all.`);
+        throw new Error(`Invalid --type "${raw}". Use budget, supplier, bill, quotation, customer_invoice, or all.`);
     }
     return u;
 }

package/dist/parse-mutation-payload.js

@@ -190,6 +190,42 @@ export function parseUpdateBillPayload(raw) {
         id: requiredString(o.id, "update-bill payload.id"),
     };
 }
+/** Server performs the authoritative bill-selection and quotation-coverage checks. */
+export function parseValidateBillSelectionPayload(raw) {
+    requireObject(raw, "validate-bill-selection payload");
+    return raw;
+}
+/** Matches bill.updatePaymentEvidence for already-paid supplier bills. */
+export function parseUpdateBillPaymentEvidencePayload(raw) {
+    requireObject(raw, "update-bill-payment-evidence payload");
+    return raw;
+}
+/** Server validates quotation amounts, line items, and the single attachment. */
+export function parseCreateQuotationPayload(raw) {
+    requireObject(raw, "create-quotation payload");
+    return raw;
+}
+export function parseUpdateQuotationPayload(raw) {
+    requireObject(raw, "update-quotation payload");
+    return raw;
+}
+export function parseCreateCustomerInvoicePayload(raw) {
+    const input = requireObject(raw, "create-customer-invoice payload");
+    if (!Array.isArray(input.splits) || input.splits.length === 0) {
+        throw new Error("create-customer-invoice payload.splits must be a non-empty array.");
+    }
+    return {
+        budgetId: requiredString(input.budgetId, "create-customer-invoice payload.budgetId"),
+        splits: input.splits.map((rawSplit, index) => {
+            const split = requireObject(rawSplit, `create-customer-invoice payload.splits[${index}]`);
+            return {
+                dueDate: toDate(split.dueDate, `create-customer-invoice payload.splits[${index}].dueDate`),
+                label: requiredString(split.label, `create-customer-invoice payload.splits[${index}].label`),
+                percentage: Number(split.percentage),
+            };
+        }),
+    };
+}
 /** Matches project.updateProject — dateRange.from/to may be ISO strings. */
 export function parseUpdateProjectPayload(raw) {
     const o = requireObject(raw, "update-project payload");

package/dist/prisma-enums.js

@@ -10,8 +10,24 @@ export const ProjectStatus = {
     PITCH: "PITCH",
     WON: "WON",
     COMPLETED: "COMPLETED",
+    RECONCILED: "RECONCILED",
     LOST: "LOST",
 };
+export const SupplierQuotationStatus = {
+    DRAFT: "DRAFT",
+    PENDING_APPROVAL: "PENDING_APPROVAL",
+    APPROVED: "APPROVED",
+    REJECTED: "REJECTED",
+    SUPERSEDED: "SUPERSEDED",
+};
+export const CustomerInvoiceBatchStatus = {
+    CREATING: "CREATING",
+    PENDING_APPROVAL: "PENDING_APPROVAL",
+    APPROVED: "APPROVED",
+    REJECTED_VOIDED: "REJECTED_VOIDED",
+    EXPIRED_VOIDED: "EXPIRED_VOIDED",
+    PARTIAL_QBO_FAILURE: "PARTIAL_QBO_FAILURE",
+};
 export const BudgetStatus = {
     DRAFT: "DRAFT",
     PENDING_APPROVAL: "PENDING_APPROVAL",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-labs-sg/bb",
-  "version": "1.18.1",
+  "version": "1.19.0",
   "description": "Budget Builder CLI for AI agents — manage budgets, bills, and claims; bill records use isClaimable=false for bills and isClaimable=true for claims.",
   "type": "module",
   "main": "./dist/index.js",