@go-labs-sg/bb 2.15.0 → 2.17.0

package/README.md

@@ -183,6 +183,10 @@ external provider.
 
 ### Mutation safety
 
+While an estimate email is `QUEUED`, `PROCESSING`, or awaiting provider
+reconciliation, the API makes that Budget read-only. Budget-changing CLI
+commands return a conflict until delivery becomes `SENT` or `FAILED`.
+
 Every canonical command is classified by effect: `state-change`, `email`, `external-write`, `delete`, and/or `financial-write`. Interactive runs require one exact `CONFIRM`. Non-interactive runs require the corresponding flags (`--allow-state-change`, `--allow-email`, `--allow-external-write`, `--allow-delete`, and `--allow-financial-write`); commands with multiple effects require every matching flag. Agents must still get user confirmation in chat first—the runtime gate is not user authorization.
 
 **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.
@@ -191,7 +195,7 @@ Every canonical command is classified by effect: `state-change`, `email`, `exter
 
 **Mutations with `--payload`:** Commands such as `bb budget create`, `bb bill create`, and `bb supplier update` take a single JSON object (`--payload '<json>'`) matching the corresponding tRPC procedure input. Use ISO strings for date/datetime fields; the CLI coerces them where needed. The API still validates the full shape. Plain `description` fields for item create/update are converted to `descriptionRichText`; pass `descriptionRichText` directly when formatted Tiptap JSON is required. For **`bb project update`**, the project window is `dateRange.from` and `dateRange.to` (optional end); there are no separate event-date fields on the project payload. **`bb budget create` / `bb budget update`** do not accept `asanaTaskId`; configure the deal card on the project (`bb project update` / project settings).
 
-**Contact-person estimate email:** `bb budget estimate send --payload '<json>'` calls the same `email.sendEstimateToContactPerson` procedure as the web composer. The payload requires `budgetId`, `estimateId`, optional `estimateDocNumber`, `to`, `cc`, `replyTo`, `subject`, HTML `content`, and HTML `signature`. It sends the raw PDF returned by QuickBooks together with the standard terms and Budget Builder budget attachments, then marks the budget `ESTIMATE_SENT`. The command requires interactive `CONFIRM`; inspect the budget, recipients, and HTML first, and do not retry blindly after an ambiguous delivery failure.
+**Contact-person estimate email:** `bb budget estimate send --payload '<json>'` calls the same `email.sendEstimateToContactPerson` procedure as the web composer. The payload requires `budgetId`, `estimateId`, optional `estimateDocNumber`, `to`, `cc`, `replyTo`, `subject`, HTML `content`, and HTML `signature`. It durably queues worker delivery of the QuickBooks PDF, standard terms, and Budget Builder budget attachments, and returns the outbound-email and operation IDs immediately. Worker retries reuse one provider idempotency key; the budget becomes `ESTIMATE_SENT` only after Resend accepts the email. The command requires interactive `CONFIRM`; inspect the budget, recipients, and HTML first.
 
 **Customer-invoice workflow parity:** `bb customer-invoice list` uses the same global/project list procedure and metrics as the web pages; omit filters for the global list or use `--projectId` for project scope. `bb customer-invoice send` uses the same protected email workflow as the web composer and marks a successful invoice `SENT`. `bb customer-invoice approve` and `bb customer-invoice reject` are Admin-only batch operations: callers select a batch ID, and the API resolves its internal pending Admin approval record. `bb customer-invoice sync` follows QuickBooks' paid state and zero balance, restoring `SENT` or `APPROVED` if that payment is reversed. Invoice approval refuses voided invoices and closes the estimate only when approved invoice coverage totals 100%; deletion, voiding, rejection, expiry, and QBO synchronization use the same estimate-reopening and live-payment guards as the web app.
 
@@ -207,11 +211,14 @@ For agent-driven invoice work, use this read-before-write sequence:
 Project Hub setup and commercial-document reconciliation are durable, asynchronous Budget Builder operations. Read status before requesting either mutation:
 
 ```bash
+bb project hub list --q <project-or-company> --status WON,COMPLETED
 bb project hub status <project-id>
 bb project hub setup <project-id>
 bb project hub sync <project-id>
 ```
 
+`list` is read-only and returns active projects with a Project Hub integration, including setup state and the stored Hub URL when available. It supports project/company search, project-status filters, pagination, and sorting.
+
 `status` reports eligibility, whether setup can be requested, the current setup status, the latest setup error, and the client Hub URL. `setup` uses the same eligibility and accepted-estimate checks as the web button and may create the operational Asana project before provisioning Drive and Project Hub. `sync` requires an existing `READY` native-layout integration and queues a complete reconciliation of accepted estimates, commercial attachments, win proofs, and eligible customer invoices into Asana and Drive.
 
 Both mutation commands write external state asynchronously and therefore require `state-change` and `external-write` confirmation. In non-interactive use, pass both `--allow-state-change` and `--allow-external-write` only after obtaining explicit user approval. A successful `queued` response means the durable operation was accepted. `status` tracks setup readiness; the sync response returns its outbox operation ID, which an Admin can inspect with the integration-operation commands when completion or failure diagnostics are required.
@@ -229,14 +236,14 @@ 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`) |
 | **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` (admin), `list-items`, `create-item` (`--payload`), `update-item` (`--payload`), `archive-items` (`--ids` CSV, max 100; Budget Builder only; users can archive their own items, leads/admins any item; blocked by Draft/Pending Approval/Approved budgets), `delete-item` (admin; archives in Budget Builder and makes the item inactive in QuickBooks), `get-item`, `list-item-categories`, `create-item-category` / `update-item-category` / `delete-item-categories` (admin; `--ids` CSV for delete) |
 | **Dashboard & users** | `whoami` (current API-key owner identity and role), `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` (`--name`; defaults to the caller; admin-only `--userId` for another user; raw key shown once), `list-api-keys` (defaults to the caller; admin-only `--userId` for another user), `revoke-api-key` (key ID; admin-only `--userId` for another user), `get-user-performance`, `get-dashboard`, `get-monthly-metrics`, `get-system-overview`, `get-estimate-performance`, `get-financial-overview` (performance/dashboard commands are admin-only) |
 | **Errors (admin)** | `get-recent-errors`, `get-error-metrics` |
-| **Automation (admin)** | `list-integration-operations`, `retry-integration-operation` |
+| **Automation (admin)** | `list-integration-operations`, `retry-integration-operation` (Resend resolution requires `--confirmExternalStateReconciled true` plus `--outboundEmailResolution ACCEPTED\|NOT_ACCEPTED_RETRY`; include `--providerMessageId` when accepted) |
 | **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.

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",
@@ -4190,6 +4190,76 @@
 		"effects": [],
 		"legacyTarget": "list-projects"
 	},
+	{
+		"path": ["project", "hub", "list"],
+		"legacyAliases": ["list-project-hubs", "list_project_hubs"],
+		"summary": "List project hubs.",
+		"globalOptions": [
+			{
+				"name": "--help",
+				"description": "Show help for this command."
+			},
+			{
+				"name": "--quiet",
+				"description": "Suppress non-error diagnostics."
+			},
+			{
+				"name": "--debug",
+				"description": "Emit sanitized diagnostic traces."
+			},
+			{
+				"name": "--api-url",
+				"description": "Override the Budget Builder API base URL."
+			},
+			{
+				"name": "--allow-state-change",
+				"description": "Allow a Budget Builder state change in non-interactive use."
+			},
+			{
+				"name": "--allow-email",
+				"description": "Allow sending email in non-interactive use."
+			},
+			{
+				"name": "--allow-external-write",
+				"description": "Allow writes to external systems in non-interactive use."
+			},
+			{
+				"name": "--allow-delete",
+				"description": "Allow deleting data in non-interactive use."
+			},
+			{
+				"name": "--allow-financial-write",
+				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--q",
+				"description": "Search project and company names."
+			},
+			{
+				"name": "--status",
+				"description": "Filter by comma-separated project statuses."
+			},
+			{
+				"name": "--page",
+				"description": "Select a results page."
+			},
+			{
+				"name": "--perPage",
+				"description": "Set the results page size."
+			},
+			{
+				"name": "--sortBy",
+				"description": "Sort by startDate, name, companyName, or status."
+			},
+			{
+				"name": "--sortDir",
+				"description": "Sort in asc or desc order."
+			}
+		],
+		"argumentMode": "legacy-passthrough",
+		"effects": [],
+		"legacyTarget": "list-project-hubs"
+	},
 	{
 		"path": ["project", "get"],
 		"legacyAliases": ["get-project", "get_project"],

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`.
 
@@ -736,6 +736,14 @@ Legacy aliases: `list-projects`, `list_projects`.
 
 Effects: none.
 
+## `bb project hub list`
+
+List project hubs.
+
+Legacy aliases: `list-project-hubs`, `list_project_hubs`.
+
+Effects: none.
+
 ## `bb project get`
 
 Get project.

package/dist/commands.js

@@ -1091,7 +1091,7 @@ export async function createEstimate(budgetId, preflight) {
     const result = await api.quickbooks.createEstimate.mutate({ budgetId });
     out(result);
 }
-export const describeEstimateEmailConfirmation = (input) => `to ${input.to}; CC ${input.cc.length > 0 ? input.cc.join(", ") : "none"}; reply-to ${input.replyTo}; subject "${input.subject}"; attach the QBO estimate PDF, terms and conditions, and Budget Builder attachments, then mark the estimate sent`;
+export const describeEstimateEmailConfirmation = (input) => `to ${input.to}; CC ${input.cc.length > 0 ? input.cc.join(", ") : "none"}; reply-to ${input.replyTo}; subject "${input.subject}"; queue durable worker delivery with the QBO estimate PDF, terms and conditions, and Budget Builder attachments; mark the estimate sent after provider acceptance`;
 export const sendEstimateToContactPersonFromPayload = async (raw) => {
     const input = parseSendEstimateToContactPersonPayload(raw);
     await assertSensitiveWorkflowConfirmed({
@@ -1907,6 +1907,14 @@ export async function listProjects(opts) {
     });
     out(result);
 }
+export const listProjectHubs = async (opts) => {
+    const result = await api.project.getAllProjectHubs.query({
+        ...opts,
+        page: opts.page ?? 1,
+        perPage: opts.perPage ?? 20,
+    });
+    out(result);
+};
 export async function getProject(id) {
     const [project, budgetsOverview, billsOverview] = await Promise.all([
         api.project.getProjectDetailsById.query({ id }),
@@ -2015,17 +2023,25 @@ export const listIntegrationOperations = async (input) => {
     const result = await api.integration.listOperations.query(input);
     out(result);
 };
-export const retryIntegrationOperation = async (operationId, confirmExternalStateReconciled) => {
+export const retryIntegrationOperation = async (operationId, confirmExternalStateReconciled, outboundEmailResolution, providerMessageId) => {
     await assertSensitiveWorkflowConfirmed({
-        action: "Retry integration operation",
+        action: outboundEmailResolution === "ACCEPTED"
+            ? "Reconcile integration operation as completed"
+            : "Retry integration operation",
         entity: `operation ${operationId}`,
-        details: confirmExternalStateReconciled
-            ? "after confirming the external state has been reconciled"
-            : undefined,
+        details: outboundEmailResolution === "ACCEPTED"
+            ? `mark provider-accepted email sent with message ID ${providerMessageId ?? "<missing>"}`
+            : outboundEmailResolution === "NOT_ACCEPTED_RETRY"
+                ? "rotate the Resend idempotency key and retry provider delivery"
+                : confirmExternalStateReconciled
+                    ? "after confirming the external state has been reconciled"
+                    : undefined,
     });
     const result = await api.integration.retryOperation.mutate({
         operationId,
         confirmExternalStateReconciled,
+        outboundEmailResolution,
+        providerMessageId,
     });
     out(result);
 };

package/dist/index.js

@@ -5,9 +5,9 @@ import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { BUDGET_BUILDER_API_BASE_URL, configureBudgetBuilderApiBaseUrl, DEFAULT_BUDGET_BUILDER_API_BASE_URL, requireApiKey, } from "./api-client.js";
 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 { 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, listProjectHubs, 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, parseCommaSeparatedIntegrationOperationStatuses, 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, parseCommaSeparatedProjectStatuses, parseCommaSeparatedQuotationStatuses, parseCommaSeparatedSupplierStatuses, parseOptionalBillListSortBy, parseOptionalBillListSortDir, parseOptionalDashboardRole, parseOptionalDeals, parseOptionalErrorSeverity, parseOptionalErrorStatus, parseOptionalExtendedProjectStatus, parseOptionalFinancialRole, parseOptionalProjectHubSortBy, 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";
@@ -155,6 +155,9 @@ 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.
 
+Budget mutations return a conflict while an estimate email is queued,
+processing, or awaiting provider reconciliation.
+
 Budgets
   list-budgets              [--projectId] [--name] [--status CSV] [--createdBy] [--dateFrom] [--dateTo] [--sortBy] [--sortDir] [--page] [--perPage] [--summary]
   get-budget <id>            Budget + line items
@@ -220,7 +223,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.
@@ -267,6 +271,8 @@ Companies & projects
   delete-company <id>
   list-projects              [--companyId] [--name] [--status] [--active true|false] [--page] [--perPage]
     Omit --active to include both active and inactive projects.
+  list-project-hubs          [--q] [--status CSV] [--page] [--perPage] [--sortBy startDate|name|companyName|status] [--sortDir asc|desc]
+    List active projects that have a Project Hub integration.
   get-project <id>
     Budget overview totalRevenue includes Estimate Accepted and Estimate Closed budgets only.
   create-project             --name --companyId --contactPersonId --insideSalesId --businessDevelopmentId --venue --startDate <ISO> [--projectManagerId <userId>] [--asanaTaskId] [--asanaSearch <text>] [--slackChannelId --slackChannelUrl --slackChannelName] [--pax] [--endDate <ISO>] [--description]
@@ -330,7 +336,7 @@ Errors
 
 Automation (admin)
   list-integration-operations [--search] [--destination <provider,...>] [--status <PENDING|PROCESSING|FAILED|COMPLETED,...>] [--page] [--perPage]
-  retry-integration-operation <operationId> [--confirmExternalStateReconciled true|false]
+  retry-integration-operation <operationId> [--confirmExternalStateReconciled true|false] [--outboundEmailResolution ACCEPTED|NOT_ACCEPTED_RETRY] [--providerMessageId <id>]
 
 Historical / benchmarks
   get-approved-budgets       [--projectId] [--limit] [--minRevenue] [--maxRevenue]
@@ -1209,19 +1215,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;
             }
@@ -1568,6 +1574,17 @@ export async function runCli(argv = process.argv, runtime = createProcessRuntime
                 });
                 break;
             }
+            case "list-project-hubs": {
+                await listProjectHubs({
+                    q: getFlag(flags, "q"),
+                    statuses: parseCommaSeparatedProjectStatuses(getFlag(flags, "status")),
+                    page: parsePositiveIntFlag(getFlag(flags, "page"), "--page"),
+                    perPage: parsePositiveIntFlag(getFlag(flags, "perPage"), "--perPage"),
+                    sortBy: parseOptionalProjectHubSortBy(getFlag(flags, "sortBy")),
+                    sortDir: parseOptionalBillListSortDir(getFlag(flags, "sortDir")),
+                });
+                break;
+            }
             case "get-project": {
                 const id = positional[0];
                 if (!id)
@@ -2007,8 +2024,14 @@ export async function runCli(argv = process.argv, runtime = createProcessRuntime
                 if (!operationId) {
                     throw new Error("retry-integration-operation requires <operationId>");
                 }
+                const outboundEmailResolution = getFlag(flags, "outboundEmailResolution");
+                if (outboundEmailResolution &&
+                    outboundEmailResolution !== "ACCEPTED" &&
+                    outboundEmailResolution !== "NOT_ACCEPTED_RETRY") {
+                    throw new Error("--outboundEmailResolution must be ACCEPTED or NOT_ACCEPTED_RETRY");
+                }
                 await retryIntegrationOperation(operationId, parseOptionalBoolFlag(flags, "confirmExternalStateReconciled") ??
-                    false);
+                    false, outboundEmailResolution, getFlag(flags, "providerMessageId"));
                 break;
             }
             case "list-inbound-sources": {

package/dist/parse-cli-enums.js

@@ -78,6 +78,36 @@ export function parseOptionalExtendedProjectStatus(raw) {
     }
     return raw;
 }
+export function parseCommaSeparatedProjectStatuses(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 (!PROJECT_STATUS_VALUES.has(status)) {
+            throw new Error(`Invalid project status "${status}". Use one of: ${[...PROJECT_STATUS_VALUES].join(", ")}.`);
+        }
+    }
+    return statuses;
+}
+const PROJECT_HUB_SORT_FIELDS = new Set([
+    "startDate",
+    "name",
+    "companyName",
+    "status",
+]);
+export function parseOptionalProjectHubSortBy(raw) {
+    if (raw === undefined || raw === "")
+        return undefined;
+    if (!PROJECT_HUB_SORT_FIELDS.has(raw)) {
+        throw new Error(`Invalid --sortBy "${raw}". Use one of: ${[...PROJECT_HUB_SORT_FIELDS].join(", ")}.`);
+    }
+    return raw;
+}
 export function parseOptionalDashboardRole(raw) {
     if (raw === undefined || raw === "")
         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("-", " ")}.`;
     }
@@ -206,11 +209,11 @@ const aliasesFor = (legacyTarget, aliases) => [
         alias.replaceAll("-", "_"),
     ])),
 ];
-const legacyCommand = (legacyTarget, path, aliases = []) => ({
+const legacyCommand = (legacyTarget, path, aliases = [], commandOptions = []) => ({
     path,
     legacyAliases: aliasesFor(legacyTarget, aliases),
     summary: summaryFor(legacyTarget),
-    options: globalCommandOptions,
+    options: [...globalCommandOptions, ...commandOptions],
     effects: effectsFor(legacyTarget),
     legacyTarget,
 });
@@ -364,6 +367,23 @@ const registry = [
     legacyCommand("update-company", ["company", "update"]),
     legacyCommand("delete-company", ["company", "delete"]),
     legacyCommand("list-projects", ["project", "list"]),
+    legacyCommand("list-project-hubs", ["project", "hub", "list"], [], [
+        {
+            name: "--q",
+            description: "Search project and company names.",
+        },
+        {
+            name: "--status",
+            description: "Filter by comma-separated project statuses.",
+        },
+        { name: "--page", description: "Select a results page." },
+        { name: "--perPage", description: "Set the results page size." },
+        {
+            name: "--sortBy",
+            description: "Sort by startDate, name, companyName, or status.",
+        },
+        { name: "--sortDir", description: "Sort in asc or desc order." },
+    ]),
     legacyCommand("get-project", ["project", "get"]),
     legacyCommand("get-project-hub-status", ["project", "hub", "status"]),
     legacyCommand("setup-project-hub", ["project", "hub", "setup"]),

package/package.json

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

@@ -86,6 +86,7 @@ This table highlights the role-sensitive command groups an agent is most likely
 
 | Commands or action | Required identity condition |
 | --- | --- |
+| `bb project hub list` | Any active authenticated role; the command is read-only and returns only active projects with a Project Hub integration. |
 | `bb auth whoami`; own `bb user api-key create`, `bb user api-key list`, and `bb user api-key revoke` | Any active role; omit `--userId` to act as the current user. |
 | Cross-user API-key commands; `bb user create` | `ADMIN`. |
 | Budget/project mutations, estimates, and budget attachments | `ADMIN`, budget creator, or project assignment as Business Development, Inside Sales, or Project Manager, depending on the endpoint. |
@@ -98,6 +99,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`. |