@go-labs-sg/bb 2.14.0 → 2.16.0

package/README.md

@@ -229,7 +229,7 @@ Project and budget query payloads keep the Asana identities explicit: `asanaTask
 | **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), `create-estimate`, `send-estimate-to-contact-person` (same contact-person email workflow as web), `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; `alreadyPaid` never bypasses them), `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 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`, `sync-customer-invoice` |
+| **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` |
 | **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`) |

package/command-manifest.json

@@ -3452,7 +3452,7 @@
 			"download-customer-invoice-pdf",
 			"download_customer_invoice_pdf"
 		],
-		"summary": "Download Customer Invoice Pdf.",
+		"summary": "Download a customer invoice PDF when permitted.",
 		"globalOptions": [
 			{
 				"name": "--help",

package/command-reference.md

@@ -610,7 +610,7 @@ Effects: state-change, email.
 
 ## `bb customer-invoice pdf download`
 
-Download Customer Invoice Pdf.
+Download a customer invoice PDF when permitted.
 
 Legacy aliases: `download-customer-invoice-pdf`, `download_customer_invoice_pdf`.
 

package/dist/index.js

@@ -7,7 +7,7 @@ import { BUDGET_BUILDER_API_BASE_URL, configureBudgetBuilderApiBaseUrl, DEFAULT_
 import { consumeCliQuietFlags, logCliAction, sanitizeFlagsForTrace, setCliQuiet, shouldLogCliActions, } from "./cli-trace.js";
 import { addBudgetItems, approveBill, approveBudget, approveCustomerInvoice, approveQuotation, approveSupplier, archiveItemsByIds, checkCustomerInvoiceReadiness, checkProjectReconciliation, cleanupStagedBillAttachments, cleanupStagedQuotationAttachments, completeProject, createApiKeyForUser, createBillApproval, createBillFromPayload, createBudgetApproval, createBudgetCategory, createBudgetFromPayload, createCompany, createContactPersonFromPayload, createCustomerInvoice, createEstimate, createInboundSource, 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, getCustomerInvoiceEmailContext, getDashboard, getErrorMetrics, getEstimatePerformance, getFinancialOverview, getInboundSource, getInboundSubmission, getItem, getItemPricingHistory, getMonthlyMetrics, getProject, getProjectHubStatus, getQuotationDetails, getRecentErrors, getSupplierAnalytics, getSupplierDetails, getSupplierPricingHistory, getSystemOverview, getUserPerformance, importQuickBooksProjectId, listApiKeysForUser, listApprovals, listBills, listBudgets, listCompanies, listContacts, listCustomerInvoices, listEligibleCustomerInvoiceBudgets, listInboundSources, listInboundSubmissions, listIntegrationOperations, listItemCategories, listItems, listProjects, listQuotations, listSuppliers, listUsers, markBudgetWonWithProof, patchBillInvoiceNumber, patchBillPayment, reactivateSuppliersByIds, reconcileProject, rejectBill, rejectBudget, rejectCustomerInvoice, rejectQuotation, rejectSupplier, removeBudgetItem, renameBudgetVersion, reorderBudgetItemsCli, restoreBudgetVersion, retryIntegrationOperation, revokeApiKeyForUser, saveInboundAutomationConfig, saveInboundMappingVersion, sendCustomerInvoiceToContactPersonFromPayload, sendEstimateToContactPersonFromPayload, setBudgetItemsNotUtilized, setupProjectHub, stageBillAttachmentsFromPaths, submitQuotation, syncCustomerInvoice, syncProjectHubCommercialDocuments, updateBillFromPayload, updateBillPaymentEvidenceFromPayload, updateBillStatus, updateBudgetCategory, updateBudgetCommissionFromPayload, updateBudgetDiscountFromPayload, updateBudgetFromPayload, updateBudgetItem, updateBudgetItemSupplierCli, updateBudgetStatus, updateCompanyFromPayload, updateContactPersonFromPayload, updateInboundProcessing, updateInboundSource, updateItemCategory, updateItemFromPayload, updateProjectFromPayload, updateProjectStatus, updateQuotationFromPayload, updateSupplierFromPayload, uploadBillAttachmentFromPath, uploadBillAttachmentsFromPaths, uploadBillDocumentsFromPaths, uploadBudgetAttachmentFromPath, uploadQuotationAttachmentFromPath, validateBillSelectionFromPayload, voidCustomerInvoice, whoAmI, } from "./commands.js";
 import { getFlag, parseArgs } from "./parse-args.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 { billStatusesForUpdateHelp, budgetStatusesForHelp, isBudgetStatusUpdate, parseApprovalTypeFlag, parseBillStatusForUpdate, parseCommaSeparatedBillStatuses, parseCommaSeparatedBudgetStatuses, parseCommaSeparatedCustomerInvoiceStatuses, parseCommaSeparatedIds, parseCommaSeparatedIntegrationOperationStatuses, 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";
 import { createCompletionScript, createHumanHelp, resolveCommand, } from "./registry/index.js";
 import { CliRuntimeError, clearActiveCliSession, confirmCurrentCommand, createProcessRuntime, emitCommandError, emitCommandResult, setActiveCliSession, } from "./runtime/index.js";
@@ -45,21 +45,6 @@ function parseCustomerInvoiceSortBy(value) {
     }
     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)
@@ -235,7 +220,8 @@ Bills
   get-bill-details <billId>
 
 Quotations
-  list-quotations            [--projectId] [--budgetId] [--supplierId] [--status CSV] [--requesterIds CSV] [--search] [--page] [--pageSize]
+  list-quotations            [--projectId] [--budgetId] [--supplierId] [--status CSV] [--createdBy CSV] [--search] [--page] [--perPage]
+    Legacy aliases --requesterIds and --pageSize remain supported.
   get-quotation <quotationId>
   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.
@@ -344,7 +330,7 @@ Errors
   get-error-metrics          (admin)
 
 Automation (admin)
-  list-integration-operations [--destination] [--status PENDING|PROCESSING|FAILED|COMPLETED] [--page] [--perPage]
+  list-integration-operations [--search] [--destination <provider,...>] [--status <PENDING|PROCESSING|FAILED|COMPLETED,...>] [--page] [--perPage]
   retry-integration-operation <operationId> [--confirmExternalStateReconciled true|false]
 
 Historical / benchmarks
@@ -1224,19 +1210,19 @@ export async function runCli(argv = process.argv, runtime = createProcessRuntime
             }
             case "list-quotations": {
                 const statusRaw = getFlag(flags, "status");
+                const createdByRaw = getFlag(flags, "createdBy") ?? getFlag(flags, "requesterIds");
+                const perPageRaw = getFlag(flags, "perPage") ?? getFlag(flags, "pageSize");
                 await listQuotations({
                     projectId: getFlag(flags, "projectId"),
                     budgetId: getFlag(flags, "budgetId"),
                     supplierId: getFlag(flags, "supplierId"),
                     status: parseCommaSeparatedQuotationStatuses(statusRaw),
-                    requesterIds: parseCommaSeparatedIds(getFlag(flags, "requesterIds")),
+                    createdBy: parseCommaSeparatedIds(createdByRaw),
                     search: getFlag(flags, "search"),
                     page: getFlag(flags, "page") !== undefined
                         ? Number(getFlag(flags, "page"))
                         : undefined,
-                    pageSize: getFlag(flags, "pageSize") !== undefined
-                        ? Number(getFlag(flags, "pageSize"))
-                        : undefined,
+                    perPage: perPageRaw !== undefined ? Number(perPageRaw) : undefined,
                 });
                 break;
             }
@@ -2009,10 +1995,11 @@ export async function runCli(argv = process.argv, runtime = createProcessRuntime
             }
             case "list-integration-operations": {
                 await listIntegrationOperations({
-                    destination: getFlag(flags, "destination"),
+                    destination: parseCommaSeparatedIds(getFlag(flags, "destination")),
                     page: parsePositiveIntFlag(getFlag(flags, "page"), "--page") ?? 1,
                     perPage: parsePositiveIntFlag(getFlag(flags, "perPage"), "--perPage") ?? 25,
-                    status: parseIntegrationOperationStatus(getFlag(flags, "status")),
+                    search: getFlag(flags, "search"),
+                    status: parseCommaSeparatedIntegrationOperationStatuses(getFlag(flags, "status")),
                 });
                 break;
             }

package/dist/parse-cli-enums.js

@@ -26,6 +26,12 @@ const SUPPLIER_ANALYTICS_TF = new Set([
 const SUPPLIER_APPROVAL_STATUS_VALUES = new Set(Object.values(ExtendedApprovalStatus));
 const EXT_ERROR_SEVERITY_VALUES = new Set(Object.values(ExtendedErrorSeverity));
 const EXT_ERROR_STATUS_VALUES = new Set(Object.values(ExtendedErrorStatus));
+const INTEGRATION_OPERATION_STATUS_VALUES = new Set([
+    "PENDING",
+    "PROCESSING",
+    "FAILED",
+    "COMPLETED",
+]);
 export function isBudgetStatusListToken(s) {
     if (s === "ALL")
         return true;
@@ -139,6 +145,22 @@ export function parseCommaSeparatedIds(raw) {
         .filter(Boolean);
     return ids.length > 0 ? ids : undefined;
 }
+export function parseCommaSeparatedIntegrationOperationStatuses(raw) {
+    if (raw === undefined)
+        return undefined;
+    const statuses = raw
+        .split(",")
+        .map((value) => value.trim().toUpperCase())
+        .filter(Boolean);
+    if (statuses.length === 0)
+        return undefined;
+    for (const status of statuses) {
+        if (!INTEGRATION_OPERATION_STATUS_VALUES.has(status)) {
+            throw new Error(`Invalid integration operation status "${status}". Use one or more of: ${[...INTEGRATION_OPERATION_STATUS_VALUES].join(", ")}.`);
+        }
+    }
+    return statuses;
+}
 export function parseCommaSeparatedBudgetStatuses(raw) {
     if (raw === undefined)
         return undefined;

package/dist/registry/index.js

@@ -192,6 +192,9 @@ const titleCase = (value) => value
 const summaryFor = (legacyTarget) => {
     if (legacyTarget === "whoami")
         return "Show the active API-key identity.";
+    if (legacyTarget === "download-customer-invoice-pdf") {
+        return "Download a customer invoice PDF when permitted.";
+    }
     if (legacyTarget.startsWith("list-")) {
         return `List ${legacyTarget.slice("list-".length).replaceAll("-", " ")}.`;
     }

package/package.json

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

@@ -98,6 +98,7 @@ This table highlights the role-sensitive command groups an agent is most likely
 | `bb bill status update ... APPROVED` or `... PAID` | `ADMIN`; state, integration, payment-reference, and payment-proof requirements still apply. |
 | `bb bill payment patch`; `bb bill invoice-number patch` | `ACCOUNTING_TEAM` or `ADMIN`, with the procedure's bill-state constraints. |
 | `bb customer-invoice approve` and `bb customer-invoice reject` | `ADMIN` batch operations selected by batch ID; the API resolves the internal pending Admin approval record. |
+| `bb customer-invoice pdf download` | `ADMIN` for pending-approval batches; other roles may download after pending approval. QuickBooks sync errors cannot be previewed or downloaded. |
 | Dashboard/performance, supplier analytics, errors, integration operations | `ADMIN`. |
 | `bb item category create`, `bb item category update`, `bb item category delete`, `bb supplier delete`, `bb supplier reactivate`, and `bb budget item placeholder-bill create` | `ADMIN`. |
 
@@ -163,7 +164,7 @@ Admin inspecting a failed integration before a confirmed retry:
 
 ```bash
 bb auth whoami
-bb integration operation list --status FAILED
+bb integration operation list --status FAILED,PENDING --search "QuickBooks"
 bb integration operation retry <operation-id>
 ```