@go-labs-sg/bb 1.20.0 → 1.21.0

package/README.md

@@ -6,14 +6,17 @@ 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, estimate emails, 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.
+For AI agents using this CLI: run `bb whoami` before reading or changing Budget Builder data. The CLI displays every command regardless of the authenticated user's role, but the API authorizes each request using the API-key owner's role, resource ownership or project assignment, current workflow state, and approval assignment. See the [role-aware agent guide](./role-aware-agent-guide.md) before choosing commands.
+
+For AI agents using this CLI: do not execute approval decisions, approval requests, status updates, estimate emails, 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. Sensitive commands print a workflow preview with separate **Action**, **Target**, and **Effects** fields before an interactive `CONFIRM` prompt, and abort in non-interactive shells.
 
 **Registry:** [`@go-labs-sg/bb`](https://www.npmjs.com/package/@go-labs-sg/bb)
 
 ## Requirements
 
 - **Node.js** 18+ (ESM; relative imports in `dist` use `.js` extensions)
-- A **Budget Builder API key** (same key used for the MCP server)
+- A Budget Builder account with any active user role
+- A **Budget Builder API key** (the same key is used for the CLI and MCP server)
 
 ## Install
 
@@ -29,13 +32,33 @@ npx @go-labs-sg/bb <command>
 
 ## Authentication
 
-Set your API key before running commands:
+Sign in to Budget Builder and create your first key under **API Keys**. Every
+active user can manage their own keys; an admin is only required to manage a key
+for someone else.
+
+Load the key from your shell's secret manager or environment before running
+commands:
+
+```bash
+export BB_API_KEY="<your-key>"
+```
+
+Do not put the raw key in a command argument, commit it to a repository, or paste
+it into logs. The CLI redacts API-key values from its request tracing. If you use
+a local `.env`, keep it out of version control and restrict its file permissions.
+
+Once authenticated, any user can rotate or manage their own keys from the CLI:
 
 ```bash
-export BB_API_KEY=<your-key>
+bb whoami
+bb create-api-key --name "My CLI"
+bb list-api-keys
+bb revoke-api-key <api-key-id>
 ```
 
-Create or revoke keys in the web app: **Goracle → API Keys** (MCP API keys).
+The raw key is returned only by `create-api-key`; copy it immediately. Listing
+keys returns metadata only. Revoking the key currently stored in `BB_API_KEY`
+will cause subsequent commands to fail until it is replaced.
 
 Admins can provision API-only service identities and manage their keys from the
 CLI. These identities are not human web accounts: `create-user` does not create
@@ -48,15 +71,56 @@ bb list-api-keys --userId <user-id>
 bb revoke-api-key <api-key-id> --userId <user-id>
 ```
 
-The raw key is returned only by `create-api-key`; copy it immediately. Listing
-keys returns metadata only.
-
 The CLI talks to the production API: `https://budget-builder.getout.events`.
 
+## Role-aware agent startup
+
+Every agent session that uses an API key must begin with:
+
+```bash
+bb version
+bb whoami
+```
+
+`whoami` returns the identity and database role attached to the active key:
+
+```json
+{
+  "id": "...",
+  "name": "...",
+  "email": "...",
+  "role": "USER"
+}
+```
+
+Record that identity in the agent's working context before selecting commands. Do not infer the role from the key name, email address, task description, or commands shown by `bb help`. Do not switch to another key to bypass a permission failure.
+
+The following is a practical guide, not a client-side allowlist. The API remains authoritative.
+
+| `whoami.role` | What an agent may normally do | Important limits |
+| --- | --- | --- |
+| `USER` | Manage its own API keys; use shared authenticated reads and catalog/CRM operations; work with resources it created or projects/budgets where its user ID is assigned; create its own bills, claims, and quotation drafts; request approval. | No admin dashboards, user provisioning, integration recovery, final finance actions, or approval decisions unless the user is the recorded approver. |
+| `INSIDE_SALES` | All applicable base-user operations, assigned project/budget work, and the broader supplier workflow exposed to Inside Sales. | Budget and supplier approval requests still follow the Lead/Admin workflow. Assignment, ownership, state, and recorded-approver checks still apply. |
+| `LEAD` | All applicable base-user operations plus Lead-stage budget and supplier approval work; supplier creation is auto-approved for this role. | Lead is not Admin. Do not attempt admin dashboards, user administration, integration recovery, final bill payment, or admin-only customer-invoice actions. |
+| `ACCOUNTING_TEAM` | All applicable authenticated operations plus finance-stage bill work, including checking bills and correcting allowed payment or invoice-number metadata. Act on bill approvals only when the API lists the user as an approver. | Direct `APPROVED` and `PAID` bill status changes, customer-invoice payment, user administration, and system operations remain Admin-only. |
+| `ADMIN` | Cross-user API-key and service-identity administration, global dashboard/error/integration operations, broad resource access, final bill approval/payment, and admin customer-invoice workflows. | Admin access does not bypass valid state transitions, required evidence, resource consistency, external-operation locks, or the agent's duty to obtain explicit confirmation for sensitive commands. |
+
+Permissions are also resource- and state-dependent:
+
+- Budget/project mutations generally require Admin, resource ownership, or assignment as Business Development, Inside Sales, or Project Manager.
+- Bill and quotation edits/deletes are commonly limited to their creator or Admin, and only in supported statuses.
+- Approval commands require the authenticated user to be the recorded pending approver; having a generally elevated role is not sufficient by itself.
+- Own-key commands are available to every active role. Passing `--userId` to manage another user's keys requires Admin.
+- `bb help` is a command catalog, not proof that the current identity is authorized.
+
+If the API returns `FORBIDDEN`, stop. Report the command, target resource, `whoami` identity/role, and the missing ownership, assignment, approver, or role condition when known. Do not retry through a lower-level command or another credential unless the user explicitly changes the operating identity.
+
 ## Usage
 
 ```bash
 bb help
+bb version
+bb whoami
 bb list-budgets
 bb get-budget <budget-id>
 bb update-budget-status <budget-id> <status> [--markProjectWon true] [--projectStatusOnCommercialRejection PITCH|LOST]
@@ -68,9 +132,11 @@ bb list-suppliers
 
 Global options and flags use `--key=value` or `--key value` (see `bb help`).
 
-**Authoritative command list:** run `bb help` — it includes every command, positional args, and flags. MCP exposes a subset of the same tRPC surface; the CLI additionally includes a few procedures mainly used by the web UI (e.g. `reorder-budget-items`, `update-budget-item-supplier`). You can also use MCP-style `snake_case` (e.g. `bb list_bills`); it is normalized to kebab-case.
+Run `bb version` before agent-driven work to record the installed package version and production API target. This is read-only and does not require `BB_API_KEY`.
+
+**Authoritative command list:** run `bb help` — it includes every command, positional args, and flags, but does not filter the list by the current `whoami` role. MCP exposes a subset of the same tRPC surface; the CLI additionally includes a few procedures mainly used by the web UI (e.g. `reorder-budget-items`, `update-budget-item-supplier`). You can also use MCP-style `snake_case` (e.g. `bb list_bills`); it is normalized to kebab-case.
 
-**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`.
+**Budget status automation:** Setting a budget to `ESTIMATE_ACCEPTED` requires a confirmed win-proof attachment. The first accepted estimate also requires `--invoiceSettings '<json>'` while customer invoicing is enabled. Provide `depositPercentage`, `balancePercentage`, `deliveryMethod`, and the matching `billingEmail` or HTTPS `uploadUrl`; revenue at or below S$5,000 requires `100/0`. If the parent project is `PITCH` or `LOST`, the API marks it `WON` automatically and runs enabled Asana automation. When rejecting the only accepted/closed budget on a commercial project, pass `--projectStatusOnCommercialRejection PITCH|LOST`.
 
 **Sensitive workflow changes:** Approval decisions/requests, entity status updates, estimate emails, 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.
 
@@ -82,20 +148,29 @@ Global options and flags use `--key=value` or `--key value` (see `bb help`).
 
 **Contact-person estimate email:** `send-estimate-to-contact-person --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.
 
+**Customer-invoice workflow parity:** `list-customer-invoices` now uses the same global/project list procedure and metrics as the web pages; omit filters for the global list, use `--projectId` for project scope, or pass a positional budget ID as the legacy shortcut. `send-customer-invoice-to-contact-person` uses the same protected email workflow as the web composer and marks a successful invoice `SENT`. `mark-customer-invoice-paid` requires an admin, a payment date, and a local PDF/GIF/JPEG/PNG proof up to 20MB; it uploads the proof, creates a QuickBooks Payment for the live outstanding balance when necessary, attempts to attach the proof in QuickBooks, and records the result in Budget Builder. Invoice approval refuses voided invoices and closes the estimate only when approved invoice coverage totals 100%; deletion, voiding, rejection, and QBO synchronization use the same estimate-reopening and active-payment guards as the web app.
+
+For agent-driven invoice work, use this read-before-write sequence:
+
+1. Run `get-customer-invoice <batchId>` and, when composing email, `get-customer-invoice-email-context <batchId>`.
+2. For creation, run `list-eligible-customer-invoice-budgets <projectId>` or `check-customer-invoice-readiness <budgetId>` first.
+3. State the exact invoice or batch, current status, intended mutation, QuickBooks effect, email recipients, proof file, and estimate-closing/reopening effect to the user.
+4. Wait for explicit confirmation, then run the sensitive command interactively and verify its JSON result. Do not treat the runtime `CONFIRM` prompt as user authorization.
+
 ### Command overview
 
 | 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`, `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), `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` (`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` |
+| **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; 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 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` (`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-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` |
+| **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`, `mark-customer-invoice-paid` (admin; high-level proof upload + QBO Payment workflow), `download-customer-invoice-payment-proof`, `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` |
+| **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`), `delete-item`, `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` |
 | **Historical / benchmarks** | `get-approved-budgets`, `get-budget-category-benchmarks`, `get-item-pricing-history`, `get-supplier-pricing-history` |
 

package/dist/api-client.js

@@ -1,7 +1,7 @@
 import { createTRPCProxyClient, httpBatchLink, loggerLink } from "@trpc/client";
 import SuperJSON from "superjson";
 import { sanitizeValueForTrace, shouldLogCliActions } from "./cli-trace.js";
-const BASE_URL = "https://budget-builder.getout.events";
+export const BUDGET_BUILDER_API_BASE_URL = "https://budget-builder.getout.events";
 function getAuthHeader() {
     const key = process.env.BB_API_KEY;
     if (!key?.trim())
@@ -31,7 +31,7 @@ export const api = createTRPCProxyClient({
             },
         }),
         httpBatchLink({
-            url: `${BASE_URL}/api/trpc`,
+            url: `${BUDGET_BUILDER_API_BASE_URL}/api/trpc`,
             transformer: SuperJSON,
             headers: () => {
                 const headers = {

package/dist/cli-trace.js

@@ -29,8 +29,12 @@ const SENSITIVE_TRACE_FIELD = new Set([
     "paymentproofattachments",
     "paymentproofpath",
     "paymentreference",
+    "proof",
     "receipt",
 ]);
+const isPresignedUrl = (value) => typeof value === "string" &&
+    (/[?&]X-Amz-(?:Algorithm|Credential|Signature)=/i.test(value) ||
+        /[?&]X-Goog-(?:Algorithm|Credential|Signature)=/i.test(value));
 export const sanitizeValueForTrace = (value, seen = new WeakSet()) => {
     if (typeof value !== "object" || value === null)
         return value;
@@ -45,7 +49,8 @@ export const sanitizeValueForTrace = (value, seen = new WeakSet()) => {
         return value;
     return Object.fromEntries(Object.entries(value).map(([key, nestedValue]) => [
         key,
-        SENSITIVE_TRACE_FIELD.has(key.toLowerCase())
+        SENSITIVE_TRACE_FIELD.has(key.toLowerCase()) ||
+            isPresignedUrl(nestedValue)
             ? "[redacted]"
             : sanitizeValueForTrace(nestedValue, seen),
     ]));

package/dist/commands.js

@@ -6,7 +6,7 @@ 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, parseCreateCustomerInvoicePayload, parseCreateQuotationPayload, parseItemCreatePayload, parseItemUpdatePayload, parseSendEstimateToContactPersonPayload, parseSupplierCreatePayload, parseSupplierUpdatePayload, parseUpdateBillPayload, parseUpdateBillPaymentEvidencePayload, parseUpdateBudgetCommissionPayload, parseUpdateBudgetPayload, parseUpdateProjectPayload, parseUpdateQuotationPayload, parseValidateBillSelectionPayload, } from "./parse-mutation-payload.js";
+import { parseBudgetDiscountPayload, parseCompanyUpdatePayload, parseContactCreatePayload, parseContactUpdatePayload, parseCreateBillPayload, parseCreateBudgetPayload, parseCreateCustomerInvoicePayload, parseCreateQuotationPayload, parseItemCreatePayload, parseItemUpdatePayload, parseSendCustomerInvoiceToContactPersonPayload, parseSendEstimateToContactPersonPayload, parseSupplierCreatePayload, parseSupplierUpdatePayload, parseUpdateBillPayload, parseUpdateBillPaymentEvidencePayload, parseUpdateBudgetCommissionPayload, parseUpdateBudgetPayload, parseUpdateProjectPayload, parseUpdateQuotationPayload, parseValidateBillSelectionPayload, } from "./parse-mutation-payload.js";
 import { BillStatus, BudgetStatus, ProjectStatus } from "./prisma-enums.js";
 import { createRichTextFromPlainText } from "./rich-text.js";
 const BUDGET = "BUDGET";
@@ -263,7 +263,18 @@ const billAttachmentContentTypeForFileName = (fileName) => {
     return resolvedContentType;
 };
 const PAYMENT_PROOF_MAX_SIZE = 20 * 1024 * 1024;
+const CUSTOMER_INVOICE_PAYMENT_PROOF_MAX_SIZE = 20 * 1024 * 1024;
 const QUOTATION_ATTACHMENT_MAX_SIZE = 20 * 1024 * 1024;
+const customerInvoicePaymentProofContentTypeForFileName = (fileName) => {
+    const resolvedContentType = contentTypeHeaderForFileName(fileName);
+    if (resolvedContentType === "application/pdf" ||
+        resolvedContentType === "image/gif" ||
+        resolvedContentType === "image/jpeg" ||
+        resolvedContentType === "image/png") {
+        return resolvedContentType;
+    }
+    throw new Error(`Unsupported customer invoice payment-proof type: ${fileName}. Use PDF, GIF, JPEG, or PNG.`);
+};
 const quotationAttachmentContentTypeForFileName = (fileName) => {
     const resolvedContentType = contentTypeHeaderForFileName(fileName);
     if (resolvedContentType === "application/pdf" ||
@@ -290,18 +301,27 @@ const lockedBudgetStatusLabels = {
 const lockedBudgetStatusLabel = (status) => status in lockedBudgetStatusLabels
     ? lockedBudgetStatusLabels[status]
     : status;
-const assertSensitiveWorkflowConfirmed = async ({ action, entity, details, }) => {
+export const buildSensitiveWorkflowPreview = ({ action, entity, details, }) => {
+    const effects = details ?? "may change workflow state or send notifications";
+    return [
+        "Budget Builder workflow preview",
+        `Action: ${action}`,
+        `Target: ${entity}`,
+        `Effects: ${effects}`,
+    ].join("\n");
+};
+const assertSensitiveWorkflowConfirmed = async (input) => {
     const expected = "CONFIRM";
-    const detailText = details ? ` ${details}` : "";
+    const preview = buildSensitiveWorkflowPreview(input);
     if (!process.stdin.isTTY || !process.stderr.isTTY) {
-        throw new Error(`${action} on ${entity}${detailText} is a sensitive Budget Builder workflow change. Run this command in an interactive terminal after the user explicitly confirms the exact action, then type "${expected}" to continue.`);
+        throw new Error(`${preview}\nThis is a sensitive workflow change. Run it in an interactive terminal only after the user explicitly confirms this exact action, then type "${expected}" to continue.`);
     }
     const rl = createInterface({
         input: process.stdin,
         output: process.stderr,
     });
     try {
-        const answer = await rl.question(`${action} on ${entity}${detailText} may change workflow status, approvals, or send notification emails. Confirm the user explicitly approved this exact action, then type "${expected}" to continue: `);
+        const answer = await rl.question(`${preview}\nConfirm the user explicitly approved this exact action, then type "${expected}" to continue: `);
         if (answer.trim() !== expected) {
             throw new Error("Aborted.");
         }
@@ -392,6 +412,9 @@ export async function updateBudgetStatus(budgetId, status, opts) {
         ...(opts?.projectStatusOnCommercialRejection !== undefined && {
             projectStatusOnCommercialRejection: opts.projectStatusOnCommercialRejection,
         }),
+        ...(opts?.projectInvoiceSettings !== undefined && {
+            projectInvoiceSettings: opts.projectInvoiceSettings,
+        }),
     });
     out(result);
 }
@@ -503,7 +526,9 @@ export async function approveBill(billId) {
     }
     let email;
     try {
-        await api.email.sendReplyBillApprovalEmail.mutate(result.updatedApproval);
+        await api.email.sendReplyBillApprovalEmail.mutate({
+            id: result.updatedApproval.id,
+        });
         email = { sent: true };
     }
     catch (error) {
@@ -709,8 +734,8 @@ export async function updateBillStatus(opts) {
     catch (error) {
         await rethrowAfterStagedPaymentProofCleanup(error, bill && paymentProof
             ? async () => {
-                // The cleanup endpoint checks Attachment rows and refuses to delete a key
-                // that an ambiguously successful status update already attached.
+                // The cleanup endpoint checks the staged-upload record and refuses to
+                // delete a key that an ambiguously successful update already consumed.
                 await deleteStagedPaymentProof(bill.projectId, paymentProof.key);
             }
             : undefined);
@@ -867,6 +892,8 @@ export async function uploadQuotationAttachmentFromPath(projectId, filePath) {
     const key = `quotations/${projectId}/${randomUUID()}.${ext || "pdf"}`;
     const uploadUrl = await api.attachment.getPresignedUrlToUpload.mutate({
         key,
+        size: buf.byteLength,
+        contentType: attachmentContentType,
     });
     const res = await fetch(uploadUrl, {
         method: "PUT",
@@ -958,6 +985,9 @@ export async function uploadBudgetWinProofFromPath(budgetId, filePath, opts) {
         ...(opts?.markProjectWon !== undefined && {
             markProjectWon: opts.markProjectWon,
         }),
+        ...(opts?.projectInvoiceSettings !== undefined && {
+            projectInvoiceSettings: opts.projectInvoiceSettings,
+        }),
     });
     out(result);
 }
@@ -1278,19 +1308,31 @@ export const checkCustomerInvoiceReadiness = async (budgetId) => {
     out(result);
 };
 export const listCustomerInvoices = async (input) => {
-    const result = await api.customerInvoice.listByBudget.query(input);
+    const result = await api.customerInvoice.list.query(input);
+    out(result);
+};
+export const listEligibleCustomerInvoiceBudgets = async (projectId) => {
+    const result = await api.customerInvoice.getEligibleBudgets.query({
+        projectId,
+    });
     out(result);
 };
 export const getCustomerInvoice = async (batchId) => {
     const result = await api.customerInvoice.getInvoiceDetail.query({ batchId });
     out(result);
 };
+export const getCustomerInvoiceEmailContext = async (batchId) => {
+    const result = await api.customerInvoice.getInvoiceEmailContext.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",
+        details: "creates one invoice in QuickBooks; admin-created invoices are approved immediately, while other invoices request approval; approved cumulative coverage of 100% closes the QuickBooks estimate",
     });
     const result = await api.customerInvoice.createInvoiceBatch.mutate(input);
     out(result);
@@ -1299,6 +1341,7 @@ export const discardCreatingCustomerInvoice = async (batchId) => {
     await assertSensitiveWorkflowConfirmed({
         action: "Discard unfinished customer invoice",
         entity: `invoice batch ${batchId}`,
+        details: "removes only a reserved CREATING batch that has no invoice created in QuickBooks",
     });
     const result = await api.customerInvoice.discardCreatingInvoiceBatch.mutate({
         batchId,
@@ -1309,7 +1352,7 @@ 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",
+        details: "deletes its invoices from QuickBooks and removes the local batch; paid invoices are blocked until their QBO payments are reversed; removing approved coverage may reopen the estimate",
     });
     const result = await api.customerInvoice.deleteInvoiceBatch.mutate({
         batchId,
@@ -1320,7 +1363,7 @@ export const voidCustomerInvoice = async (batchId) => {
     await assertSensitiveWorkflowConfirmed({
         action: "Void customer invoice",
         entity: `invoice batch ${batchId}`,
-        details: "void its invoices in QuickBooks",
+        details: "voids its invoices in QuickBooks and updates Budget Builder; paid invoices are blocked until their QBO payments are reversed; removing approved coverage may reopen the estimate",
     });
     const result = await api.customerInvoice.voidInvoiceBatch.mutate({ batchId });
     out(result);
@@ -1329,7 +1372,7 @@ export const approveCustomerInvoice = async (batchId) => {
     await assertSensitiveWorkflowConfirmed({
         action: "Approve customer invoice",
         entity: `invoice batch ${batchId}`,
-        details: "and notify its creator",
+        details: "approves the batch and notifies its creator; voided invoices cannot be approved; cumulative approved coverage of 100% closes the QuickBooks estimate",
     });
     const result = await api.customerInvoice.approveInvoiceBatch.mutate({
         batchId,
@@ -1340,7 +1383,7 @@ 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`,
+        details: `records the rejection reason, voids it in QuickBooks, notifies its creator, and reopens a prematurely closed estimate when applicable`,
     });
     const result = await api.customerInvoice.rejectInvoiceBatch.mutate({
         batchId,
@@ -1364,13 +1407,104 @@ 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",
+        details: "refreshes local status, QuickBooks metadata, balance, and history; a QBO-voided invoice becomes VOIDED locally and may reopen its estimate",
     });
     const result = await api.customerInvoice.syncInvoiceStatus.mutate({
         invoiceId,
     });
     out(result);
 };
+export const describeCustomerInvoiceEmailConfirmation = (input) => `emails the QBO invoice PDF to ${input.to}; requested CC ${input.cc.length > 0 ? input.cc.join(", ") : "none"}; reply-to ${input.replyTo}; subject "${input.subject}"; server-required admin, creator, business-development, and inside-sales CC recipients are added; success marks the invoice SENT; do not retry blindly after an ambiguous delivery failure`;
+export const sendCustomerInvoiceToContactPersonFromPayload = async (raw) => {
+    const input = parseSendCustomerInvoiceToContactPersonPayload(raw);
+    await assertSensitiveWorkflowConfirmed({
+        action: "Send customer invoice email",
+        entity: `invoice ${input.invoiceId}`,
+        details: describeCustomerInvoiceEmailConfirmation(input),
+    });
+    const result = await api.customerInvoice.sendInvoiceToContactPerson.mutate(input);
+    out(result);
+};
+export const describeCustomerInvoicePaymentConfirmation = ({ invoiceId, paymentDate, paymentReference, proofFileName, proofSize, }) => `for invoice ${invoiceId}, records payment date ${paymentDate}${paymentReference
+    ? " with a payment reference"
+    : " without a payment reference"}; uploads ${proofFileName} (${proofSize} bytes); creates a QuickBooks Payment for the live outstanding balance when non-zero, attaches the proof to QBO when possible, and records the payment in Budget Builder`;
+const assertPaymentDate = (paymentDate) => {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(paymentDate)) {
+        throw new Error("--paymentDate must use YYYY-MM-DD.");
+    }
+    const parsed = new Date(`${paymentDate}T00:00:00.000Z`);
+    if (Number.isNaN(parsed.getTime()) ||
+        parsed.toISOString().slice(0, 10) !== paymentDate) {
+        throw new Error("--paymentDate must be a valid calendar date.");
+    }
+    return paymentDate;
+};
+export const markCustomerInvoicePaidFromPath = async ({ invoiceId, paymentDate, paymentProofPath, paymentReference, }) => {
+    const normalizedPaymentDate = assertPaymentDate(paymentDate);
+    const proofContents = await readFile(paymentProofPath);
+    const proofFileName = basename(paymentProofPath);
+    if (proofContents.byteLength === 0) {
+        throw new Error("Customer invoice payment proof must not be empty.");
+    }
+    if (proofContents.byteLength > CUSTOMER_INVOICE_PAYMENT_PROOF_MAX_SIZE) {
+        throw new Error("Customer invoice payment proof must be 20MB or smaller.");
+    }
+    const proofContentType = customerInvoicePaymentProofContentTypeForFileName(proofFileName);
+    await assertSensitiveWorkflowConfirmed({
+        action: "Mark customer invoice paid",
+        entity: `invoice ${invoiceId}`,
+        details: describeCustomerInvoicePaymentConfirmation({
+            invoiceId,
+            paymentDate: normalizedPaymentDate,
+            paymentReference,
+            proofFileName,
+            proofSize: proofContents.byteLength,
+        }),
+    });
+    const proofUpload = await api.customerInvoice.requestPaymentProofUpload.mutate({
+        invoiceId,
+        fileName: proofFileName,
+        size: proofContents.byteLength,
+        contentType: proofContentType,
+    });
+    const uploadResponse = await fetch(proofUpload.uploadUrl, {
+        method: "PUT",
+        body: proofContents,
+        headers: { "Content-Type": proofUpload.contentType },
+    });
+    if (!uploadResponse.ok) {
+        throw new Error(`Payment-proof upload failed: HTTP ${uploadResponse.status} ${(await uploadResponse.text()).slice(0, 500)}`);
+    }
+    const result = await api.customerInvoice.markPaid.mutate({
+        invoiceId,
+        paymentDate: normalizedPaymentDate,
+        paymentReference,
+        proof: {
+            key: proofUpload.key,
+            name: proofUpload.name,
+            size: proofContents.byteLength,
+            contentType: proofUpload.contentType,
+        },
+    });
+    out(result);
+};
+export const downloadCustomerInvoicePaymentProof = async (invoiceId, outputPath) => {
+    const proof = await api.customerInvoice.getPaymentProofDownloadUrl.mutate({
+        invoiceId,
+    });
+    const response = await fetch(proof.url);
+    if (!response.ok) {
+        throw new Error(`Payment-proof download failed: HTTP ${response.status} ${(await response.text()).slice(0, 500)}`);
+    }
+    const contents = Buffer.from(await response.arrayBuffer());
+    const resolvedOutputPath = outputPath?.trim() || basename(proof.fileName);
+    await writeFile(resolvedOutputPath, contents);
+    out({
+        fileName: proof.fileName,
+        outputPath: resolvedOutputPath,
+        size: contents.byteLength,
+    });
+};
 export async function updateBillFromPayload(raw) {
     const input = parseUpdateBillPayload(raw);
     const result = await api.bill.update.mutate(input);
@@ -1539,7 +1673,9 @@ export async function approveBudget(budgetId) {
     });
     let email;
     try {
-        await api.email.sendReplyApprovalEmail.mutate(result.updatedApproval);
+        await api.email.sendReplyApprovalEmail.mutate({
+            id: result.updatedApproval.id,
+        });
         email = { sent: true };
     }
     catch (error) {
@@ -1576,7 +1712,9 @@ export async function rejectBudget(budgetId, reason) {
     });
     let email;
     try {
-        await api.email.sendReplyApprovalEmail.mutate(result.updatedApproval);
+        await api.email.sendReplyApprovalEmail.mutate({
+            id: result.updatedApproval.id,
+        });
         email = { sent: true };
     }
     catch (error) {
@@ -1673,8 +1811,7 @@ export async function approveSupplier(supplierId) {
     let email;
     try {
         await api.email.sendReplySupplierApprovalEmail.mutate({
-            ...result.updatedApproval,
-            rejectionReason: result.updatedApproval.rejectionReason ?? undefined,
+            id: result.updatedApproval.id,
         });
         email = { sent: true };
     }
@@ -1712,8 +1849,7 @@ export async function rejectSupplier(supplierId, reason) {
     let email;
     try {
         await api.email.sendReplySupplierApprovalEmail.mutate({
-            ...result.updatedApproval,
-            rejectionReason: result.updatedApproval.rejectionReason ?? undefined,
+            id: result.updatedApproval.id,
         });
         email = { sent: true };
     }
@@ -1754,7 +1890,9 @@ export async function rejectBill(billId, reason) {
     }
     let email;
     try {
-        await api.email.sendReplyBillApprovalEmail.mutate(result.updatedApproval);
+        await api.email.sendReplyBillApprovalEmail.mutate({
+            id: result.updatedApproval.id,
+        });
         email = { sent: true };
     }
     catch (error) {
@@ -1995,6 +2133,10 @@ export async function listUsers() {
     const users = await api.user.getAllUsers.query();
     out(users);
 }
+export async function whoAmI() {
+    const user = await api.user.getCurrentUser.query();
+    out(user);
+}
 export async function getUserPerformance(userId) {
     const result = await api.dashboard.getUserPerformance.query({ userId });
     out(result);

package/dist/index.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import "./load-env.js";
-import { requireApiKey } from "./api-client.js";
+import { readFileSync } from "node:fs";
+import { 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, 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, sendEstimateToContactPersonFromPayload, 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 { 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, downloadCustomerInvoicePaymentProof, downloadCustomerInvoicePdf, downloadQuotationPdf, getApprovedBudgets, getBillAttachments, getBillDetails, getBudget, getBudgetCategories, getBudgetCategoryBenchmarks, getBudgetDetails, getBudgetItemsOnly, getBudgetVersions, getCompany, getCustomerInvoice, getCustomerInvoiceEmailContext, getDashboard, getErrorMetrics, getEstimatePerformance, getFinancialOverview, getItem, getItemPricingHistory, getMonthlyMetrics, getProject, getQuotationDetails, getRecentErrors, getSupplierAnalytics, getSupplierDetails, getSupplierPricingHistory, getSystemOverview, getUserPerformance, importQuickBooksProjectId, listApiKeysForUser, listApprovals, listBills, listBudgets, listCompanies, listContacts, listCustomerInvoices, listEligibleCustomerInvoiceBudgets, listIntegrationOperations, listItemCategories, listItems, listProjects, listQuotations, listSuppliers, listUsers, markBudgetWonWithProof, markCustomerInvoicePaidFromPath, patchBillInvoiceNumber, patchBillPayment, reactivateSuppliersByIds, reconcileProject, rejectBill, rejectBudget, rejectCustomerInvoice, rejectQuotation, rejectSupplier, removeBudgetItem, renameBudgetVersion, reorderBudgetItemsCli, restoreBudgetVersion, retryIntegrationOperation, revokeApiKeyForUser, sendCustomerInvoiceToContactPersonFromPayload, sendEstimateToContactPersonFromPayload, 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, 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 { parseJsonFlag, parseOptionalNumber as parseOptNum, } from "./parse-json-flag.js";
@@ -144,9 +145,18 @@ bb — Budget Builder CLI for AI agents (parity with MCP tools)
 
 Usage: bb <command> [options] [args]
 
+Identity: bb version — print the installed CLI package version and API target as JSON.
+
 Global: --quiet | -q | BB_CLI_QUIET=1 — hide action logs (default: log command + each tRPC call to stderr; stdout JSON unchanged).
 
-Auth: Set BB_API_KEY in the environment (same API key as MCP / Goracle).
+Auth: Create a key under API Keys in Budget Builder and set BB_API_KEY in the environment.
+
+Authorization: Run bb whoami before choosing commands. bb help lists the full
+catalog for every role; it does not prove the active key may call a command.
+The API evaluates whoami.role (USER, INSIDE_SALES, LEAD, ACCOUNTING_TEAM, or
+ADMIN) together with resource ownership/project assignment, current state, and
+pending-approver assignment. On FORBIDDEN, stop and report the identity, role,
+command, and target; do not switch keys or try a lower-level procedure.
 
 Sensitive workflow changes: approval decisions/requests, entity status updates,
 estimate emails, customer invoices, integration retries, mark-budget-won,
@@ -170,7 +180,7 @@ Budgets
     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.
     ESTIMATE_REJECTED requires --projectStatusOnCommercialRejection when rejecting the only accepted/closed budget on a commercial project.
     status: ${budgetStatusesForHelp.join(", ")}
-  mark-budget-won <budgetId> <filePath> [--projectManagerId <id>] [--markProjectWon true|false]   Upload signed quote/PO proof and set status to ESTIMATE_ACCEPTED; PITCH or LOST projects become WON automatically and require PM when none is assigned
+	mark-budget-won <budgetId> <filePath> [--projectManagerId <id>] [--invoiceSettings <json>]   Upload signed quote/PO proof and set status to ESTIMATE_ACCEPTED; first acceptance requires invoice settings when customer invoicing is enabled
   create-budget              --payload '<json>'  (budget.createBudget; Asana deal card is on the project)
   update-budget              --payload '<json>'  (budget.updateBudget; must include id)
   delete-budget <budgetId>
@@ -235,16 +245,23 @@ Quotations
 
 Customer invoices
   check-customer-invoice-readiness <budgetId>
-  list-customer-invoices <budgetId> [--status CSV] [--search] [--sortBy createdAt|status|totalNetAmount|approvalExpiresAt] [--sortDir asc|desc] [--page] [--perPage]
+  list-eligible-customer-invoice-budgets <projectId>   Accepted budgets that are ready and still have invoice coverage remaining.
+  list-customer-invoices [budgetId] [--projectId <id>] [--companyIds CSV] [--projectIds CSV] [--budgetIds CSV] [--createdByIds CSV] [--status CSV] [--search] [--sortBy createdAt|status|totalNetAmount|approvalExpiresAt] [--sortDir asc|desc] [--page] [--perPage]
+    No scope flag lists invoices globally. --projectId uses the project scope. A positional budgetId is a backward-compatible shortcut for --budgetIds.
   get-customer-invoice <batchId>
+  get-customer-invoice-email-context <batchId>        Contact, required CC, budget, and project context for composing an invoice email.
   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.
+  approve-customer-invoice <batchId>           Admin approval; rejects voided invoices, notifies the creator, and closes the estimate at cumulative 100% coverage.
   reject-customer-invoice <batchId> --reason <text>   Admin rejection; voids QBO invoices and notifies the creator.
+  send-customer-invoice-to-contact-person --payload '<json>'   Same composer workflow as web; requires invoiceId, to, cc, replyTo, subject, HTML content, and HTML signature.
+  mark-customer-invoice-paid <invoiceId> --paymentDate YYYY-MM-DD --paymentProof <path> [--paymentReference <text>]
+    Admin-only. Uploads proof, creates a QBO Payment for the live balance when needed, attaches proof in QBO when possible, and records payment history in BB.
+  download-customer-invoice-payment-proof <invoiceId> [--output <path>]
   download-customer-invoice-pdf <invoiceId> [--output <path>]
-  sync-customer-invoice <invoiceId>             Refresh local status and balance from QuickBooks.
+  sync-customer-invoice <invoiceId>             Refresh local status and balance from QuickBooks; QBO voids can reopen a closed estimate.
 
 Approvals
   list-approvals | get-pending-approvals   [--type budget|supplier|bill|quotation|customer_invoice|all]
@@ -298,30 +315,31 @@ Suppliers & items
   update-item                --payload '<json>'  (item.updateItem; must include id)
   delete-item <id>
   get-supplier-details <supplierId>
-  get-supplier-analytics     [--name] [--page] [--perPage] [--timeFrame ALL|LAST_YEAR|…]
+  get-supplier-analytics     [--name] [--page] [--perPage] [--timeFrame ALL|LAST_YEAR|…]  (admin)
   list-items                 [--name] [--page] [--perPage]
   get-item <id>
   list-item-categories       [--page] [--perPage]
-  create-item-category       --name
-  update-item-category       --id --name
+  create-item-category       --name  (admin)
+  update-item-category       --id --name  (admin)
   delete-item-categories     --ids <csv>  (itemCategory.deleteItemCategories; admin; empty categories only)
 
 Dashboard & users
+  whoami                    Show the user identity and role for the active API key.
   list-users
   create-user                --email <email> [--name <name>] [--role ${userRolesForHelp.join("|")}]  (admin; API-only service identity with no Google sign-in)
-  create-api-key             --userId <userId> --name <label>  (admin; raw key is shown once)
-  list-api-keys              [--userId <userId>]  (admin; defaults to the caller)
-  revoke-api-key <apiKeyId>  [--userId <userId>]  (admin; --userId is required for another user's key)
-  get-user-performance       [--userId]
-  get-dashboard              [--userId] [--role BD|CREATOR|INSIDE_SALES|ALL] [--deals ALL|SUCCESSFUL|LOST] [--timeFrame] [--startDate] [--endDate]
-  get-monthly-metrics        [same optional flags as get-dashboard]  (dashboard.getMonthlyMetrics)
-  get-system-overview        [same optional flags as get-dashboard]  (dashboard.getSystemOverview)
-  get-estimate-performance   [same optional flags as get-dashboard]  (dashboard.getEstimatePerformance)
-  get-financial-overview     [same optional flags as dashboard; role uses BudgetRole enum]
+  create-api-key             --name <label> [--userId <userId>]  (defaults to the caller; admin required for another user; raw key is shown once)
+  list-api-keys              [--userId <userId>]  (defaults to the caller; admin required for another user)
+  revoke-api-key <apiKeyId>  [--userId <userId>]  (defaults to the caller; admin required for another user)
+  get-user-performance       [--userId]  (admin)
+  get-dashboard              [--userId] [--role BD|CREATOR|INSIDE_SALES|ALL] [--deals ALL|SUCCESSFUL|LOST] [--timeFrame] [--startDate] [--endDate]  (admin)
+  get-monthly-metrics        [same optional flags as get-dashboard]  (admin; dashboard.getMonthlyMetrics)
+  get-system-overview        [same optional flags as get-dashboard]  (admin; dashboard.getSystemOverview)
+  get-estimate-performance   [same optional flags as get-dashboard]  (admin; dashboard.getEstimatePerformance)
+  get-financial-overview     [same optional flags as dashboard; role uses BudgetRole enum]  (admin)
 
 Errors
-  get-recent-errors          [--page] [--perPage] [--severity] [--status]
-  get-error-metrics
+  get-recent-errors          [--page] [--perPage] [--severity] [--status]  (admin)
+  get-error-metrics          (admin)
 
 Automation (admin)
   list-integration-operations [--destination] [--status PENDING|PROCESSING|FAILED|COMPLETED] [--page] [--perPage]
@@ -345,6 +363,20 @@ Not covered vs MCP get_budget: "get-budget" also fetches line items in one call.
 `.trim();
     console.log(help);
 }
+const getCliPackageMetadata = () => {
+    const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    if (!packageJson.name || !packageJson.version) {
+        throw new Error("Could not read Budget Builder CLI package metadata.");
+    }
+    return { name: packageJson.name, version: packageJson.version };
+};
+const printVersion = () => {
+    const metadata = getCliPackageMetadata();
+    console.log(JSON.stringify({
+        ...metadata,
+        apiBaseUrl: BUDGET_BUILDER_API_BASE_URL,
+    }, null, 2));
+};
 /** MCP registers tools with snake_case; CLI commands are kebab-case. */
 function normalizeCliCommand(raw) {
     return raw.replace(/_/g, "-");
@@ -353,6 +385,10 @@ async function main() {
     const { command, positional, flags } = parseArgs(process.argv);
     setCliQuiet(consumeCliQuietFlags(flags));
     const cmd = normalizeCliCommand(command ?? "");
+    if (cmd === "version" || flags.version === true) {
+        printVersion();
+        process.exit(0);
+    }
     if (!cmd || cmd === "help" || flags.help === true) {
         printHelp();
         process.exit(0);
@@ -370,6 +406,10 @@ async function main() {
     }
     try {
         switch (cmd) {
+            case "whoami": {
+                await whoAmI();
+                break;
+            }
             case "list-budgets": {
                 const statusStr = getFlag(flags, "status");
                 const statuses = parseCommaSeparatedBudgetStatuses(statusStr !== undefined ? String(statusStr) : undefined);
@@ -415,6 +455,9 @@ async function main() {
                         ? String(getFlag(flags, "projectManagerId"))
                         : undefined,
                     markProjectWon: parseOptionalBoolFlag(flags, "markProjectWon"),
+                    projectInvoiceSettings: getFlag(flags, "invoiceSettings") !== undefined
+                        ? parseJsonFlag(String(getFlag(flags, "invoiceSettings")), "--invoiceSettings")
+                        : undefined,
                 });
                 break;
             }
@@ -474,6 +517,9 @@ async function main() {
                         : undefined,
                     markProjectWon: parseOptionalBoolFlag(flags, "markProjectWon"),
                     projectStatusOnCommercialRejection: parseCommercialRejectionProjectStatus(flags),
+                    projectInvoiceSettings: getFlag(flags, "invoiceSettings") !== undefined
+                        ? parseJsonFlag(String(getFlag(flags, "invoiceSettings")), "--invoiceSettings")
+                        : undefined,
                 });
                 break;
             }
@@ -1070,19 +1116,39 @@ async function main() {
                 await checkCustomerInvoiceReadiness(budgetId);
                 break;
             }
-            case "list-customer-invoices": {
-                const budgetId = positional[0];
-                if (!budgetId) {
-                    throw new Error("list-customer-invoices requires <budgetId>");
+            case "list-eligible-customer-invoice-budgets": {
+                const projectId = positional[0];
+                if (!projectId) {
+                    throw new Error("list-eligible-customer-invoice-budgets requires <projectId>");
                 }
+                await listEligibleCustomerInvoiceBudgets(projectId);
+                break;
+            }
+            case "list-customer-invoices": {
+                const positionalBudgetId = positional[0];
+                const projectId = getFlag(flags, "projectId");
+                const projectIds = parseCommaSeparatedIds(getFlag(flags, "projectIds"));
+                if (projectId && projectIds) {
+                    throw new Error("Use either --projectId for project scope or --projectIds for a global filter, not both.");
+                }
+                const budgetIds = [
+                    ...(positionalBudgetId ? [positionalBudgetId] : []),
+                    ...(parseCommaSeparatedIds(getFlag(flags, "budgetIds")) ?? []),
+                ];
                 const statusRaw = getFlag(flags, "status");
                 const sortDir = parseOptionalBillListSortDir(getFlag(flags, "sortDir"));
                 await listCustomerInvoices({
-                    budgetId,
+                    scope: projectId
+                        ? { type: "project", projectId }
+                        : { type: "global" },
                     page: parsePositiveIntFlag(getFlag(flags, "page"), "--page") ?? 1,
-                    perPage: parsePositiveIntFlag(getFlag(flags, "perPage"), "--perPage") ?? 12,
+                    perPage: parsePositiveIntFlag(getFlag(flags, "perPage"), "--perPage") ?? 20,
                     q: getFlag(flags, "search") ?? "",
                     statuses: parseCommaSeparatedCustomerInvoiceStatuses(statusRaw !== undefined ? String(statusRaw) : undefined),
+                    companyIds: parseCommaSeparatedIds(getFlag(flags, "companyIds")),
+                    projectIds,
+                    budgetIds: budgetIds.length > 0 ? [...new Set(budgetIds)] : undefined,
+                    createdByIds: parseCommaSeparatedIds(getFlag(flags, "createdByIds")),
                     sortBy: parseCustomerInvoiceSortBy(getFlag(flags, "sortBy")),
                     sortDir: sortDir ?? "desc",
                 });
@@ -1096,6 +1162,14 @@ async function main() {
                 await getCustomerInvoice(batchId);
                 break;
             }
+            case "get-customer-invoice-email-context": {
+                const batchId = positional[0];
+                if (!batchId) {
+                    throw new Error("get-customer-invoice-email-context requires <batchId>");
+                }
+                await getCustomerInvoiceEmailContext(batchId);
+                break;
+            }
             case "create-customer-invoice": {
                 const payloadRaw = getFlag(flags, "payload");
                 if (!payloadRaw) {
@@ -1145,6 +1219,37 @@ async function main() {
                 await rejectCustomerInvoice(batchId, String(reason));
                 break;
             }
+            case "send-customer-invoice-to-contact-person": {
+                const payloadRaw = getFlag(flags, "payload");
+                if (!payloadRaw) {
+                    throw new Error("send-customer-invoice-to-contact-person requires --payload '<json>'");
+                }
+                await sendCustomerInvoiceToContactPersonFromPayload(parseJsonFlag(String(payloadRaw), "--payload"));
+                break;
+            }
+            case "mark-customer-invoice-paid": {
+                const invoiceId = positional[0];
+                const paymentDate = getFlag(flags, "paymentDate");
+                const paymentProofPath = getFlag(flags, "paymentProof");
+                if (!invoiceId || !paymentDate || !paymentProofPath) {
+                    throw new Error("mark-customer-invoice-paid requires <invoiceId> --paymentDate YYYY-MM-DD --paymentProof <path> [--paymentReference <text>]");
+                }
+                await markCustomerInvoicePaidFromPath({
+                    invoiceId,
+                    paymentDate,
+                    paymentProofPath,
+                    paymentReference: getFlag(flags, "paymentReference"),
+                });
+                break;
+            }
+            case "download-customer-invoice-payment-proof": {
+                const invoiceId = positional[0];
+                if (!invoiceId) {
+                    throw new Error("download-customer-invoice-payment-proof requires <invoiceId> [--output <path>]");
+                }
+                await downloadCustomerInvoicePaymentProof(invoiceId, getFlag(flags, "output"));
+                break;
+            }
             case "download-customer-invoice-pdf": {
                 const invoiceId = positional[0];
                 if (!invoiceId) {
@@ -1601,8 +1706,8 @@ async function main() {
             case "create-api-key": {
                 const userId = getFlag(flags, "userId");
                 const name = getFlag(flags, "name");
-                if (!userId || !name) {
-                    throw new Error("create-api-key requires --userId <userId> --name <label>");
+                if (!name) {
+                    throw new Error("create-api-key requires --name <label> [--userId <userId>]");
                 }
                 await createApiKeyForUser({ userId, name });
                 break;

package/dist/load-env.js

@@ -3,4 +3,4 @@
  */
 import path from "node:path";
 import { config } from "dotenv";
-config({ path: path.resolve(process.cwd(), ".env") });
+config({ path: path.resolve(process.cwd(), ".env"), quiet: true });

package/dist/parse-mutation-payload.js

@@ -42,24 +42,37 @@ const requiredEmail = (value, fieldLabel) => {
     }
     return email;
 };
+const parseContactPersonEmailPayload = (input, commandName) => {
+    if (!Array.isArray(input.cc)) {
+        throw new Error(`${commandName} payload.cc must be an email array.`);
+    }
+    return {
+        to: requiredEmail(input.to, `${commandName} payload.to`),
+        cc: input.cc.map((email, index) => requiredEmail(email, `${commandName} payload.cc[${index}]`)),
+        replyTo: requiredEmail(input.replyTo, `${commandName} payload.replyTo`),
+        subject: requiredString(input.subject, `${commandName} payload.subject`),
+        content: requiredString(input.content, `${commandName} payload.content`),
+        signature: requiredString(input.signature, `${commandName} payload.signature`),
+    };
+};
 /** Matches the web estimate composer (`email.sendEstimateToContactPerson`). */
 export const parseSendEstimateToContactPersonPayload = (raw) => {
     const input = requireObject(raw, "send-estimate-to-contact-person payload");
-    if (!Array.isArray(input.cc)) {
-        throw new Error("send-estimate-to-contact-person payload.cc must be an email array.");
-    }
     return {
-        to: requiredEmail(input.to, "send-estimate-to-contact-person payload.to"),
-        cc: input.cc.map((email, index) => requiredEmail(email, `send-estimate-to-contact-person payload.cc[${index}]`)),
-        replyTo: requiredEmail(input.replyTo, "send-estimate-to-contact-person payload.replyTo"),
-        subject: requiredString(input.subject, "send-estimate-to-contact-person payload.subject"),
-        content: requiredString(input.content, "send-estimate-to-contact-person payload.content"),
-        signature: requiredString(input.signature, "send-estimate-to-contact-person payload.signature"),
+        ...parseContactPersonEmailPayload(input, "send-estimate-to-contact-person"),
         estimateId: requiredString(input.estimateId, "send-estimate-to-contact-person payload.estimateId"),
         estimateDocNumber: optionalString(input.estimateDocNumber),
         budgetId: requiredString(input.budgetId, "send-estimate-to-contact-person payload.budgetId"),
     };
 };
+/** Matches the web customer-invoice email composer. */
+export const parseSendCustomerInvoiceToContactPersonPayload = (raw) => {
+    const input = requireObject(raw, "send-customer-invoice-to-contact-person payload");
+    return {
+        ...parseContactPersonEmailPayload(input, "send-customer-invoice-to-contact-person"),
+        invoiceId: requiredString(input.invoiceId, "send-customer-invoice-to-contact-person payload.invoiceId"),
+    };
+};
 /** Matches budget.createBudget — optional pipedriveDealId; Asana deal is project.asanaTaskId. */
 export function parseCreateBudgetPayload(raw) {
     const o = requireObject(raw, "create-budget payload");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@go-labs-sg/bb",
-  "version": "1.20.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.",
+  "version": "1.21.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",
   "bin": {