@go-labs-sg/bb 1.18.1 → 1.20.0

package/README.md

@@ -6,7 +6,7 @@ For AI agents: bills and claims are stored as the same underlying bill records.
 
 For AI agents using this CLI: always check whether a newer `@go-labs-sg/bb` version is available before running Budget Builder commands, then update the CLI if needed so command flags and API behavior stay current.
 
-For AI agents using this CLI: do not execute approval decisions, approval requests, status updates, `mark-budget-won`, `submit-quotation`, or supplier approval request side effects until the user explicitly confirms the exact entity, target state, and side effects. Inspect the entity first, summarize what will change and whether emails/integrations will run, then wait for a clear confirmation from the user. These sensitive workflow commands also require an interactive `CONFIRM` prompt at runtime and abort in non-interactive shells.
+For AI agents using this CLI: do not execute approval decisions, approval requests, status updates, 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.
 
 **Registry:** [`@go-labs-sg/bb`](https://www.npmjs.com/package/@go-labs-sg/bb)
 
@@ -72,7 +72,7 @@ Global options and flags use `--key=value` or `--key value` (see `bb help`).
 
 **Budget status automation:** Setting a budget to `ESTIMATE_ACCEPTED` requires a confirmed win-proof attachment. If the parent project is `PITCH` or `LOST`, the API now marks it `WON` automatically and, when the `asana-tasks` feature flag is enabled, creates an Asana Event Ops section from Prompt 5 tasks. Prompt 5 skips quantity-zero items, combines matching non-GO-internal suppliers, keeps each GO internal item separate, removes generated work that repeats another line item or group, and schedules applicable subtasks relative to the project start date. When rejecting the only accepted/closed budget on a commercial project, pass `--projectStatusOnCommercialRejection PITCH|LOST`.
 
-**Sensitive workflow changes:** Approval decisions/requests, entity status updates, `mark-budget-won`, `submit-quotation`, and supplier approval request side effects require an interactive `CONFIRM` prompt. Non-interactive runs abort before the guarded workflow mutation. Agents must get user confirmation in chat before attempting the command; the prompt is a final runtime guard, not a replacement for user approval.
+**Sensitive workflow changes:** Approval decisions/requests, entity status updates, 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.
 
 **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.
 
@@ -80,21 +80,27 @@ Global options and flags use `--key=value` or `--key value` (see `bb help`).
 
 **Mutations with `--payload`:** Commands such as `create-budget`, `create-bill`, `update-supplier`, etc. 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 **`update-project`**, the project window is `dateRange.from` and `dateRange.to` (optional end); there are no separate event-date fields on the project payload. **`create-budget` / `update-budget`** do not accept `asanaTaskId`; configure the deal card on the project (`update-project` / project settings).
 
+**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.
+
 ### 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`, `update-budget-status` (`ESTIMATE_ACCEPTED` requires win proof, auto-marks `PITCH` or `LOST` projects `WON`, and auto-creates an Asana Event Ops section from Prompt 5 tasks when enabled; Prompt 5 skips quantity-zero items, combines matching non-GO-internal suppliers, keeps each GO internal item separate, removes generated work that repeats another line item or group, and schedules applicable subtasks relative to the project start date; `--projectStatusOnCommercialRejection PITCH\|LOST` is required when rejecting the only accepted/closed budget on a commercial project), `mark-budget-won` (`<budgetId>` + proof file path; `PITCH` or `LOST` projects become `WON` automatically), `create-budget` / `update-budget` (`--payload`), `delete-budget`, `create-budget-approval` (also sends approval request emails), `add-budget-items`, `update-budget-item`, `remove-budget-item`, `reorder-budget-items`, `update-budget-item-supplier`, `create-budget-category`, `update-budget-category`, `delete-budget-category`, `update-budget-commission`, `update-budget-discount` (`--payload` where noted), `upload-budget-attachment` (`<budgetId>` + local file path; uses `attachment.requestBudgetAttachmentUpload` + PUT + `attachment.confirmBudgetAttachment`) |
-| **Bills / claims** | `list-bills` (`--isClaimable false` for bills, `--isClaimable true` for claims, omit for both), `list-claims` (claims only), `stage-bill-attachment` (securely uploads invoice/payment-proof files before creation and returns attachment JSON), `create-bill` (`--payload`; set `isClaimable=false` for a bill, `isClaimable=true` for a claim; supplier bills require positive `extractedAmount` and `amount`, with `amount <= extractedAmount`; an already-paid supplier bill sets `alreadyPaid=true` and requires `paymentReference` plus a staged PDF in `paymentProofAttachments`, and is created pending finance approval; non-legacy supplier bills from 1 Jul 2026 00:00 SGT also require approved quotation coverage), `update-bill` (`--payload`), `delete-bill`, `create-bill-approval` (also sends approval request emails), `update-bill-status` (moving a bill or claim to `PAID` sends creator and supplier emails, CC `m@getout.sg` and BCC `noah@getout.sg`; a claim sends one email when both recipient addresses match), `patch-bill-payment` (PAID bills: `--paymentTrackingUrl`, `--paymentReference`, `--quickbooksBillId`, `--paymentDate` ISO; clearing a paid bill's QuickBooks link is not allowed), `patch-bill-invoice-number`, `get-bill-attachments`, `upload-bill-attachment` (`<billId>` + local path), `get-bill-details` |
-| **Quotations** | `list-quotations`, `get-quotation`, `upload-quotation-attachment` (`<projectId>` + local PDF path; returns attachment JSON for payload use), `create-quotation` (`--payload` for `quotation.createDraft`; include `amountWithoutGst` and `gstAmount`), `submit-quotation`, `approve-quotation`, `reject-quotation`, `download-quotation-pdf` (`original`, `staff`, or `final`) |
-| **Approvals** | `list-approvals` / `get-pending-approvals` (`--type budget\|supplier\|bill\|quotation\|all`), `approve-bill` / `reject-bill` (send reply email), `approve-budget` / `reject-budget` (send reply email), `approve-supplier` / `reject-supplier` (send reply email), `approve-quotation` / `reject-quotation` |
-| **Companies & projects** | `list-companies`, `get-company`, `create-company`, `update-company` (`--payload`), `delete-company`, `list-projects`, `get-project` (its budget overview returns `totalRevenue`, calculated only from Estimate Accepted and Estimate Closed budgets), `create-project` (required: `--name`, `--companyId`, `--contactPersonId`, `--insideSalesId`, `--businessDevelopmentId`, `--venue`, `--startDate` as ISO datetime for project/window start; when `--asanaTaskId` is omitted, the CLI searches open Asana lead tasks in the Deals project, prompts for one of the top five matches, and resolves Slack channel fields from the selected deal card; optional `--asanaSearch`, `--pax`, `--endDate`, `--description`, `--projectManagerId`; always requests QBO project import like the web app), `update-project` (`--payload` with `dateRange.from` / `dateRange.to` for the project window; optional `projectManagerId` and `requestQboAccountantNotification` in JSON), `delete-project`, `update-project-status` (`<id>` `<status>`: `PITCH` \| `WON` \| `COMPLETED` \| `RECONCILED` \| `LOST`; close-out follows `WON` → `RECONCILED` → `COMPLETED`, and reconciliation requires every accepted/closed budget line to have an Approved/Paid bill or claim or be explicitly Not Utilized; for `PITCH` → `WON` also pass a Budget Builder user `--projectManagerId` or `--projectManagerEmail`; when marking `WON` without an accepted/closed budget or proof, pass `--wonOverrideReason`) |
+| **Budgets** | `list-budgets` (full payload by default; `--summary` or `--includeDetails false` for slim list), `get-budget`, `get-budget-items`, `get-budget-details`, `get-budget-categories`, `get-budget-versions`, `rename-budget-version`, `restore-budget-version`, `update-budget-status` (`ESTIMATE_ACCEPTED` requires win proof, auto-marks `PITCH` or `LOST` projects `WON`, and auto-creates an Asana Event Ops section from Prompt 5 tasks when enabled; Prompt 5 skips quantity-zero items, combines matching non-GO-internal suppliers, keeps each GO internal item separate, removes generated work that repeats another line item or group, and schedules applicable subtasks relative to the project start date; `--projectStatusOnCommercialRejection PITCH\|LOST` is required when rejecting the only accepted/closed budget on a commercial project), `mark-budget-won` (`<budgetId>` + proof file path; `PITCH` or `LOST` projects become `WON` automatically), `create-budget` / `update-budget` (`--payload`), `delete-budget`, `create-budget-approval` (also sends approval request emails), `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` |
+| **Quotations** | `list-quotations` (supports project, budget, supplier, status, requester, and text-search filters), `get-quotation`, `upload-quotation-attachment` (`<projectId>` + PDF/JPEG/PNG path up to 20MB; returns attachment JSON for payload use), `cleanup-staged-quotation-attachments`, `create-quotation` (`--payload` for `quotation.createDraft`; include `amountWithoutGst` and `gstAmount`), `update-quotation` (`--payload`; updates a `DRAFT` or `REJECTED` quotation), `delete-quotation`, `submit-quotation`, `approve-quotation`, `reject-quotation`, `download-quotation-pdf` (`original`, `staff`, or `final`) |
+| **Customer invoices** | `check-customer-invoice-readiness`, `list-customer-invoices`, `get-customer-invoice`, `create-customer-invoice`, `discard-customer-invoice`, `delete-customer-invoice`, `void-customer-invoice`, `approve-customer-invoice`, `reject-customer-invoice`, `download-customer-invoice-pdf`, `sync-customer-invoice` |
+| **Approvals** | `list-approvals` / `get-pending-approvals` (`--type budget\|supplier\|bill\|quotation\|customer_invoice\|all`), `approve-bill` / `reject-bill` (send reply email), `approve-budget` / `reject-budget` (send reply email), `approve-supplier` / `reject-supplier` (send reply email), `approve-quotation` / `reject-quotation`, `approve-customer-invoice` / `reject-customer-invoice` |
+| **Companies & projects** | `list-companies`, `get-company`, `create-company`, `update-company` (`--payload`), `delete-company`, `list-projects`, `get-project` (its budget overview returns `totalRevenue`, calculated only from Estimate Accepted and Estimate Closed budgets), `create-project` (required: `--name`, `--companyId`, `--contactPersonId`, `--insideSalesId`, `--businessDevelopmentId`, `--venue`, `--startDate` as ISO datetime for project/window start; when `--asanaTaskId` is omitted, the CLI searches open Asana lead tasks in the Deals project, prompts for one of the top five matches, and resolves Slack channel fields from the selected deal card; optional `--asanaSearch`, `--pax`, `--endDate`, `--description`, `--projectManagerId`; always requests QBO project import like the web app), `update-project` (`--payload` with `dateRange.from` / `dateRange.to` for the project window; optional `projectManagerId` and `requestQboAccountantNotification` in JSON), `delete-project`, `check-project-reconciliation <id>` (runs the web app's live checks without changing status), `reconcile-project <id>` (reruns checks transactionally and marks an eligible project `RECONCILED`), `complete-project <id>` (reruns validation, marks a reconciled project `COMPLETED`, and queues QuickBooks placeholder cleanup), `import-qbo-project`, `update-project-status` (`<id>` `<status>`: `PITCH` \| `WON` \| `COMPLETED` \| `RECONCILED` \| `LOST`; close-out follows `WON` → `RECONCILED` → `COMPLETED`, and reconciliation requires every accepted/closed budget line to have an Approved/Paid bill or claim or be explicitly Not Utilized; marking `COMPLETED` queues deletion of every remaining project placeholder bill from QuickBooks; for `PITCH` → `WON` also pass a Budget Builder user `--projectManagerId` or `--projectManagerEmail`; when marking `WON` without an accepted/closed budget or proof, pass `--wonOverrideReason`) |
 | **Contacts** | `list-contacts`, `create-contact-person` (`--payload`), `update-contact-person` (`--payload`) |
 | **Suppliers & items** | `list-suppliers` (defaults to active suppliers, `--perPage 10`, sorted by `createdAt` desc; supports `--name`, `--sortBy` for scalar supplier fields, `--sortDir`, `--createdBy`, `--gstRegistered`, `--status`, `--supplierTags`, `--active false` for archived suppliers), `create-supplier` (`--payload`; when supplier status is `PENDING_APPROVAL`, also runs `supplier.createSupplierApproval` and `email.sendSupplierApprovalRequestEmail`), `update-supplier` (`--payload`; when supplier status is `PENDING_APPROVAL`, also runs `supplier.createSupplierApproval` and `email.sendSupplierApprovalRequestEmail`), `delete-suppliers` (`--ids` CSV; admin; archives/deactivates related items), `reactivate-suppliers` (`--ids` CSV; admin; reactivates related items), `create-certification` / `create-payment-method` / `create-supplier-role` / `create-supplier-tag` (`--name`), `get-supplier-details` (includes `supplierApprovalSummary` for pending approvers, superseded approvers, and the actual responder/respondedAt metadata), `get-supplier-analytics`, `list-items`, `create-item` (`--payload`), `update-item` (`--payload`), `delete-item`, `get-item`, `list-item-categories`, `create-item-category`, `update-item-category`, `delete-item-categories` (`--ids` CSV; admin) |
 | **Dashboard & users** | `list-users`, `create-user` (admin; provisions an API-only service identity with no Google sign-in; `--email`, optional `--name`, optional `--role` defaulting to `USER`), `create-api-key` (admin; `--userId`, `--name`; raw key shown once), `list-api-keys` (admin; optional `--userId`), `revoke-api-key` (admin; key ID plus `--userId` for another user's key), `get-user-performance`, `get-dashboard`, `get-monthly-metrics`, `get-system-overview`, `get-estimate-performance`, `get-financial-overview` |
 | **Errors** | `get-recent-errors`, `get-error-metrics` |
+| **Automation (admin)** | `list-integration-operations`, `retry-integration-operation` |
 | **Historical / benchmarks** | `get-approved-budgets`, `get-budget-category-benchmarks`, `get-item-pricing-history`, `get-supplier-pricing-history` |
 
+The CLI intentionally wraps low-level upload-request/confirm procedures into file-based commands and omits browser-only helpers such as navigation counts, combobox/facet data, recent-page bookkeeping, and live UI subscriptions. Operational workflows for bills, claims, quotations, customer invoices, project reconciliation/completion, and integration recovery are available directly.
+
 ## Output
 
 - **Stdout:** JSON (pretty-printed)

package/dist/api-client.js

@@ -1,6 +1,6 @@
 import { createTRPCProxyClient, httpBatchLink, loggerLink } from "@trpc/client";
 import SuperJSON from "superjson";
-import { shouldLogCliActions } from "./cli-trace.js";
+import { sanitizeValueForTrace, shouldLogCliActions } from "./cli-trace.js";
 const BASE_URL = "https://budget-builder.getout.events";
 function getAuthHeader() {
     const key = process.env.BB_API_KEY;
@@ -26,8 +26,8 @@ export const api = createTRPCProxyClient({
             withContext: false,
             // tRPC defaults use console.log for requests; stderr keeps stdout JSON-safe for pipes.
             console: {
-                log: (...args) => console.error(...args),
-                error: (...args) => console.error(...args),
+                log: (...args) => console.error(...args.map((arg) => sanitizeValueForTrace(arg))),
+                error: (...args) => console.error(...args.map((arg) => sanitizeValueForTrace(arg))),
             },
         }),
         httpBatchLink({

package/dist/cli-trace.js

@@ -17,9 +17,39 @@ const SENSITIVE_FLAG = new Set([
     "bb_api_key",
     "token",
     "password",
+    "payment-proof",
+    "paymentproof",
+    "paymentreference",
+    "receipt",
     "secret",
     "authorization",
 ]);
+const SENSITIVE_TRACE_FIELD = new Set([
+    "paymentproof",
+    "paymentproofattachments",
+    "paymentproofpath",
+    "paymentreference",
+    "receipt",
+]);
+export const sanitizeValueForTrace = (value, seen = new WeakSet()) => {
+    if (typeof value !== "object" || value === null)
+        return value;
+    if (seen.has(value))
+        return "[circular]";
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeValueForTrace(item, seen));
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, nestedValue]) => [
+        key,
+        SENSITIVE_TRACE_FIELD.has(key.toLowerCase())
+            ? "[redacted]"
+            : sanitizeValueForTrace(nestedValue, seen),
+    ]));
+};
 export const sanitizeFlagsForTrace = (flags) => {
     const out = {};
     for (const [k, v] of Object.entries(flags)) {

package/dist/commands.js

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