@go-labs-sg/bb 1.19.0 → 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, 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: 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, 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.
+**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,12 +80,14 @@ 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`, `rename-budget-version`, `restore-budget-version`, `update-budget-status` (`ESTIMATE_ACCEPTED` requires win proof, auto-marks `PITCH` or `LOST` projects `WON`, and auto-creates an Asana Event Ops section from Prompt 5 tasks when enabled; Prompt 5 skips quantity-zero items, combines matching non-GO-internal suppliers, keeps each GO internal item separate, removes generated work that repeats another line item or group, and schedules applicable subtasks relative to the project start date; `--projectStatusOnCommercialRejection PITCH\|LOST` is required when rejecting the only accepted/closed budget on a commercial project), `mark-budget-won` (`<budgetId>` + proof file path; `PITCH` or `LOST` projects become `WON` automatically), `create-budget` / `update-budget` (`--payload`), `delete-budget`, `create-budget-approval` (also sends approval request emails), `add-budget-items`, `update-budget-item`, `remove-budget-item`, `reorder-budget-items`, `update-budget-item-supplier`, `mark-budget-items-not-utilized`, `restore-budget-item`, `create-placeholder-bill` (admin recovery), `create-budget-category`, `update-budget-category`, `delete-budget-category`, `update-budget-commission`, `delete-budget-commission`, `update-budget-discount`, `delete-budget-discount` (`--payload` where noted), `upload-budget-attachment` (`<budgetId>` + local file path; uses `attachment.requestBudgetAttachmentUpload` + PUT + `attachment.confirmBudgetAttachment`) |
-| **Bills / claims** | `list-bills` (`--isClaimable false` for bills, `--isClaimable true` for claims, omit for both), `list-claims` (claims only), `validate-bill-selection` (`--payload`; runs the same supplier, line-item, and quotation-coverage checks as the web flow), `stage-bill-attachment` (securely uploads invoice/payment-proof files before creation and returns attachment JSON), `cleanup-staged-bill-attachments`, `create-bill` (`--payload`; set `isClaimable=false` for a bill, `isClaimable=true` for a claim; supplier bills require positive `extractedAmount` and `amount`, with `amount <= extractedAmount`; an already-paid supplier bill sets `alreadyPaid=true` and requires `paymentReference` plus a staged PDF in `paymentProofAttachments`, and is created pending finance approval; non-legacy supplier bills from 1 Jul 2026 00:00 SGT also require approved quotation coverage), `update-bill` (`--payload`), `update-bill-payment-evidence` (`--payload`; replaces the payment reference and payment-proof PDFs for an already-paid bill), `delete-bill`, `create-bill-approval` (also sends approval request emails), `update-bill-status` (moving a bill or claim to `PAID` sends creator and supplier emails, CC `m@getout.sg` and BCC `noah@getout.sg`; a claim sends one email when both recipient addresses match), `patch-bill-payment` (PAID bills: `--paymentTrackingUrl`, `--paymentReference`, `--quickbooksBillId`, `--paymentDate` ISO; clearing a paid bill's QuickBooks link is not allowed), `patch-bill-invoice-number`, `get-bill-attachments`, `upload-bill-attachment` (`<billId>` + local path), `get-bill-details` |
+| **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` |

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

@@ -6,8 +6,8 @@ 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, parseSupplierCreatePayload, parseSupplierUpdatePayload, parseUpdateBillPayload, parseUpdateBillPaymentEvidencePayload, parseUpdateBudgetCommissionPayload, parseUpdateBudgetPayload, parseUpdateProjectPayload, parseUpdateQuotationPayload, parseValidateBillSelectionPayload, } from "./parse-mutation-payload.js";
-import { BudgetStatus, ProjectStatus, } 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";
@@ -262,6 +262,7 @@ 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);
@@ -608,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 };
@@ -961,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);

package/dist/index.js

@@ -2,7 +2,7 @@
 import "./load-env.js";
 import { 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, 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, 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 { 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";
@@ -149,9 +149,9 @@ Global: --quiet | -q | BB_CLI_QUIET=1 — hide action logs (default: log command
 Auth: Set BB_API_KEY in the environment (same API key as MCP / Goracle).
 
 Sensitive workflow changes: approval decisions/requests, entity status updates,
-customer invoices, integration retries, mark-budget-won, submit-quotation, and
-supplier approval request side effects require an interactive CONFIRM prompt
-and abort in non-interactive shells.
+estimate emails, customer invoices, integration retries, mark-budget-won,
+submit-quotation, and supplier approval request side effects require an
+interactive CONFIRM prompt and abort in non-interactive shells.
 AI agents must inspect the entity first, summarize the exact entity, target
 state, and side effects, then wait for explicit user confirmation before running
 the sensitive command.
@@ -176,6 +176,7 @@ Budgets
   delete-budget <budgetId>
   create-budget-approval <budgetId>   (also sends approval request emails)
   create-estimate <budgetId>          (creates QuickBooks estimate; supports preflight updates)
+  send-estimate-to-contact-person --payload '<json>'   Send using the web contact-person workflow; payload includes recipient fields plus HTML content/signature.
   add-budget-items           --budgetId --items '[{"itemId":"…","quantity":1,"markup":30},…]'
   update-budget-item         --id <budgetItemId> [--description plain-text] [--note plain-text] [--quantity] [--markup] [--cost] [--unitPrice] [--isFreeOfCharge true|false] [--gstInclusive true|false] [--gstOutOfScope true|false]
   remove-budget-item <budgetItemId>
@@ -206,9 +207,10 @@ Bills
   update-bill                --payload '<json>'  (bill.update; must include id)
   update-bill-payment-evidence --payload '<json>'  Replace paymentReference/paymentProofAttachments for an already-paid bill.
   delete-bill <billId>
-  update-bill-status <id> <status> [--rejectionReason] [--paymentTrackingUrl] [--paymentReference]
+  update-bill-status <id> <status> [--rejectionReason] [--paymentTrackingUrl] [--paymentReference] [--paymentProof <receipt.pdf>]
     status (${billStatusesForUpdateHelp.join(", ")}) — not PENDING_APPROVAL; use create-bill-approval
-    Moving a bill or claim to PAID sends creator and supplier emails, CC m@getout.sg and BCC noah@getout.sg; duplicate claim recipients receive one email.
+    PAID requires --paymentReference and a payment-proof PDF. Use --paymentProof to stage and submit the PDF atomically, or omit it only when BB already has a BILL_PAYMENT_PROOF attachment.
+    Moving a bill or claim to PAID runs the server's paid-bill notification workflow.
   patch-bill-payment <billId> [--paymentTrackingUrl] [--paymentReference] [--quickbooksBillId] [--paymentDate <ISO>]
     Clear a field: --clearPaymentTrackingUrl true | --clearPaymentReference true | --clearQuickbooksBillId true | --clearPaymentDate true
   patch-bill-invoice-number <billId> <invoiceNumber>
@@ -515,6 +517,16 @@ async function main() {
                 });
                 break;
             }
+            case "send-estimate-email":
+            case "send-estimate-to-contact-person": {
+                const payloadRaw = getFlag(flags, "payload");
+                if (!payloadRaw) {
+                    throw new Error("send-estimate-to-contact-person requires --payload '<json>'");
+                }
+                const raw = parseJsonFlag(String(payloadRaw), "--payload");
+                await sendEstimateToContactPersonFromPayload(raw);
+                break;
+            }
             case "create-budget": {
                 const payloadRaw = getFlag(flags, "payload");
                 if (!payloadRaw) {
@@ -745,7 +757,11 @@ async function main() {
             case "update-bill-status": {
                 const [id, statusRaw] = positional;
                 if (!id || !statusRaw) {
-                    throw new Error("update-bill-status requires <billId> <status> [--rejectionReason] [--paymentTrackingUrl] [--paymentReference]");
+                    throw new Error("update-bill-status requires <billId> <status> [--rejectionReason] [--paymentTrackingUrl] [--paymentReference] [--paymentProof <receipt.pdf>]");
+                }
+                const paymentProofFlag = flags.paymentProof ?? flags["payment-proof"] ?? flags.receipt;
+                if (paymentProofFlag === true) {
+                    throw new Error("--paymentProof requires a PDF file path.");
                 }
                 const status = parseBillStatusForUpdate(statusRaw);
                 await updateBillStatus({
@@ -754,6 +770,7 @@ async function main() {
                     rejectionReason: getFlag(flags, "rejectionReason"),
                     paymentTrackingUrl: getFlag(flags, "paymentTrackingUrl"),
                     paymentReference: getFlag(flags, "paymentReference"),
+                    paymentProofPath: paymentProofFlag,
                 });
                 break;
             }

package/dist/parse-mutation-payload.js

@@ -34,6 +34,32 @@ function requiredString(value, fieldLabel) {
     }
     return t;
 }
+const EMAIL_ADDRESS_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const requiredEmail = (value, fieldLabel) => {
+    const email = requiredString(value, fieldLabel);
+    if (!EMAIL_ADDRESS_PATTERN.test(email)) {
+        throw new Error(`${fieldLabel} must be a valid email address.`);
+    }
+    return email;
+};
+/** 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"),
+        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 budget.createBudget — optional pipedriveDealId; Asana deal is project.asanaTaskId. */
 export function parseCreateBudgetPayload(raw) {
     const o = requireObject(raw, "create-budget payload");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-labs-sg/bb",
-  "version": "1.19.0",
+  "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.",
   "type": "module",
   "main": "./dist/index.js",