@go-labs-sg/bb 2.42.0 → 2.43.0

package/README.md

@@ -22,6 +22,27 @@ The shared API rechecks existing records at submission. Canonical matches reuse
 
 `bb company use` and `bb company create` are state-changing, potentially external-writing commands. In non-interactive mode their existing permission gates require `--allow-state-change --allow-external-write`. Deploy the backend before publishing this CLI change. See [company discovery details](../api/docs/company-discovery.md) for limits and retry behaviour.
 
+## Record a payment made outside Budget Builder
+
+Admins can record an already-made payment on an APPROVED bill or claim without transferring money or emailing the supplier/claimant:
+
+```bash
+bb bill payment accounts
+bb bill payment record-external <billId> \
+  --paymentReference 2343190532 \
+  --paymentDate 2026-09-01 \
+  --paymentAccount <quickbooks-account-id> \
+  --paymentProof receipt.pdf
+```
+
+Choose the bank or card account actually used (including `Events Requisitions`); no account or date is defaulted. Omit `--paymentProof` if a payment-proof PDF is already attached. In non-interactive use, add `--allow-state-change --allow-external-write --allow-financial-write`; no `--allow-email` is needed. The UI offers the same **Record external payment** action next to ordinary **Mark paid**.
+
+BB marks the bill PAID immediately and queues durable QuickBooks reconciliation. A settled zero-balance QBO bill reuses its existing BillPayment IDs. Otherwise reconciliation creates a payment with the specified date/account and a stable provider request ID. Partially settled or inconsistent QBO bills require manual reconciliation; BB never guesses. Inspect failed/pending work in Integration Queue and **do not pay the bill again**. Exact retries with the same reference/date/account return the recorded settlement; changed details conflict. Ordinary Mark paid keeps its existing payment-advice workflow.
+
+`bb update-bill --payload '{"id":"<billId>","comment":"Already paid; do not pay again"}'` now accepts a partial payload. Omitted fields are preserved; comment-only updates do not change financial data or sync QBO, and are allowed on approved/paid bills for the creator or an admin. Financial edits retain their draft/rejected restrictions.
+
+Deployment prerequisite: apply the Budget Builder Prisma schema additions (`Bill.externalPayment` JSON and `EXTERNAL_PAYMENT` operation enum) before deploying the API/web/workers; deploy the backend before publishing the CLI. This feature does not modify existing paid bills or repair historical QBO entries automatically.
+
 ## Payload help and uncertain writes
 
 Run `bb <command> --help` (for example, `bb create-item --help`) to see required and optional `--payload` fields and an example JSON object. Item creation and updates accept a finite numeric `cost` and convert it to the API's decimal-string input. Validation errors identify the affected field; unsupported QuickBooks name characters are listed explicitly.

package/command-manifest.json

@@ -2261,7 +2261,7 @@
 	{
 		"path": ["bill", "update"],
 		"legacyAliases": ["update-bill", "update_bill"],
-		"summary": "Update a bill or claim; payload must include id. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. Re-read and verify both amount fields and allocations after correcting a gross/net mistake.",
+		"summary": "Update a bill or claim with a partial payload including id; omitted fields are preserved. Comment-only updates are allowed on approved/paid bills without altering financial data or QuickBooks. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. Re-read and verify both amount fields and allocations after correcting a gross/net mistake.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -2461,6 +2461,112 @@
 		"effects": ["state-change", "email", "financial-write"],
 		"legacyTarget": "update-bill-status"
 	},
+	{
+		"path": ["bill", "payment", "record-external"],
+		"legacyAliases": [
+			"record-external-bill-payment",
+			"record_external_bill_payment"
+		],
+		"summary": "Record an already-made payment on an APPROVED bill or claim, with no email and no money transfer. Requires <billId> --paymentReference --paymentDate YYYY-MM-DD --paymentAccount <QBO account ID> [--paymentProof receipt.pdf]. Reuses settled QBO payment links or queues one dated payment from the selected account. Exact retries are safe; do not pay again while reconciliation is pending.",
+		"globalOptions": [
+			{
+				"name": "--help",
+				"description": "Show help for this command."
+			},
+			{
+				"name": "--quiet",
+				"description": "Suppress non-error diagnostics."
+			},
+			{
+				"name": "--debug",
+				"description": "Emit sanitized diagnostic traces."
+			},
+			{
+				"name": "--api-url",
+				"description": "Override the Budget Builder API base URL."
+			},
+			{
+				"name": "--no-browser",
+				"description": "Print the authorization URL without opening a browser."
+			},
+			{
+				"name": "--allow-state-change",
+				"description": "Allow a Budget Builder state change in non-interactive use."
+			},
+			{
+				"name": "--allow-email",
+				"description": "Allow sending email in non-interactive use."
+			},
+			{
+				"name": "--allow-external-write",
+				"description": "Allow writes to external systems in non-interactive use."
+			},
+			{
+				"name": "--allow-delete",
+				"description": "Allow deleting data in non-interactive use."
+			},
+			{
+				"name": "--allow-financial-write",
+				"description": "Allow financial-record changes in non-interactive use."
+			}
+		],
+		"argumentMode": "legacy-passthrough",
+		"effects": ["state-change", "external-write", "financial-write"],
+		"legacyTarget": "record-external-bill-payment"
+	},
+	{
+		"path": ["bill", "payment", "accounts"],
+		"legacyAliases": [
+			"list-external-payment-accounts",
+			"list_external_payment_accounts"
+		],
+		"summary": "List active QuickBooks bank and credit-card account IDs for recording external payments (admin only).",
+		"globalOptions": [
+			{
+				"name": "--help",
+				"description": "Show help for this command."
+			},
+			{
+				"name": "--quiet",
+				"description": "Suppress non-error diagnostics."
+			},
+			{
+				"name": "--debug",
+				"description": "Emit sanitized diagnostic traces."
+			},
+			{
+				"name": "--api-url",
+				"description": "Override the Budget Builder API base URL."
+			},
+			{
+				"name": "--no-browser",
+				"description": "Print the authorization URL without opening a browser."
+			},
+			{
+				"name": "--allow-state-change",
+				"description": "Allow a Budget Builder state change in non-interactive use."
+			},
+			{
+				"name": "--allow-email",
+				"description": "Allow sending email in non-interactive use."
+			},
+			{
+				"name": "--allow-external-write",
+				"description": "Allow writes to external systems in non-interactive use."
+			},
+			{
+				"name": "--allow-delete",
+				"description": "Allow deleting data in non-interactive use."
+			},
+			{
+				"name": "--allow-financial-write",
+				"description": "Allow financial-record changes in non-interactive use."
+			}
+		],
+		"argumentMode": "legacy-passthrough",
+		"effects": [],
+		"legacyTarget": "list-external-payment-accounts"
+	},
 	{
 		"path": ["bill", "payment", "patch"],
 		"legacyAliases": ["patch-bill-payment", "patch_bill_payment"],

package/command-reference.md

@@ -411,7 +411,7 @@ Payload fields (--payload JSON)
 
 ## `bb bill update`
 
-Update a bill or claim; payload must include id. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. Re-read and verify both amount fields and allocations after correcting a gross/net mistake.
+Update a bill or claim with a partial payload including id; omitted fields are preserved. Comment-only updates are allowed on approved/paid bills without altering financial data or QuickBooks. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. Re-read and verify both amount fields and allocations after correcting a gross/net mistake.
 
 Legacy aliases: `update-bill`, `update_bill`.
 
@@ -451,6 +451,22 @@ Legacy aliases: `update-bill-status`, `update_bill_status`.
 
 Effects: state-change, email, financial-write.
 
+## `bb bill payment record-external`
+
+Record an already-made payment on an APPROVED bill or claim, with no email and no money transfer. Requires <billId> --paymentReference --paymentDate YYYY-MM-DD --paymentAccount <QBO account ID> [--paymentProof receipt.pdf]. Reuses settled QBO payment links or queues one dated payment from the selected account. Exact retries are safe; do not pay again while reconciliation is pending.
+
+Legacy aliases: `record-external-bill-payment`, `record_external_bill_payment`.
+
+Effects: state-change, external-write, financial-write.
+
+## `bb bill payment accounts`
+
+List active QuickBooks bank and credit-card account IDs for recording external payments (admin only).
+
+Legacy aliases: `list-external-payment-accounts`, `list_external_payment_accounts`.
+
+Effects: none.
+
 ## `bb bill payment patch`
 
 Patch Bill Payment.

package/dist/index.js

@@ -7665,14 +7665,110 @@ function parseCreateBillPayload(raw, draftOnlyFlag, quotationExempt = false, req
 }
 function parseUpdateBillPayload(raw) {
   const o = requireObject(raw, "update-bill payload");
-  const { draftOnly, ...input } = parseCreateBillPayload(raw, undefined, false, false);
-  if (draftOnly !== undefined) {
+  if (o.draftOnly !== undefined) {
     throw validationError("draftOnly is only supported when creating a bill.");
   }
-  return {
-    ...input,
+  const input = {
     id: requiredString(o.id, "update-bill payload.id")
   };
+  const knownFields = new Set([
+    "id",
+    "budgetId",
+    "projectId",
+    "supplierId",
+    "quotationId",
+    "quotationIds",
+    "quotationAllocations",
+    "overBudgetOverrideReason",
+    "amount",
+    "budgetItemIds",
+    "lineAmounts",
+    "comment",
+    "isClaimable",
+    "attachments",
+    "alreadyPaid",
+    "paymentReference",
+    "paymentProofAttachments",
+    "extractedSupplierName",
+    "extractedAmount",
+    "invoiceNumber",
+    "invoiceDate",
+    "verificationStatus",
+    "verificationResults"
+  ]);
+  for (const key of Object.keys(o))
+    if (!knownFields.has(key))
+      throw validationError(`Unknown update-bill payload field: ${key}`);
+  for (const key of [
+    "budgetId",
+    "projectId",
+    "supplierId",
+    "comment",
+    "paymentReference",
+    "extractedSupplierName",
+    "invoiceNumber",
+    "overBudgetOverrideReason"
+  ]) {
+    if (o[key] === undefined)
+      continue;
+    if (typeof o[key] !== "string")
+      throw validationError(`update-bill payload.${key} must be a string.`);
+    input[key] = o[key];
+  }
+  for (const key of ["amount", "extractedAmount"]) {
+    if (o[key] === undefined)
+      continue;
+    const amount = Number(o[key]);
+    if (!Number.isFinite(amount) || amount < 0)
+      throw validationError(`update-bill payload.${key} must be a number >= 0.`);
+    input[key] = amount;
+  }
+  for (const key of ["isClaimable", "alreadyPaid"]) {
+    if (o[key] === undefined)
+      continue;
+    if (typeof o[key] !== "boolean")
+      throw validationError(`update-bill payload.${key} must be boolean.`);
+    input[key] = o[key];
+  }
+  for (const key of ["attachments", "paymentProofAttachments"]) {
+    const attachments = o[key];
+    if (attachments === undefined)
+      continue;
+    if (!Array.isArray(attachments))
+      throw validationError(`update-bill payload.${key} must be an array.`);
+    input[key] = attachments.map((value, index) => billAttachment(value, index, key));
+  }
+  if (o.budgetItemIds !== undefined) {
+    if (!Array.isArray(o.budgetItemIds) || !o.budgetItemIds.length)
+      throw validationError("update-bill payload.budgetItemIds must be a non-empty array.");
+    input.budgetItemIds = o.budgetItemIds.map((id, index) => requiredString(id, `update-bill payload.budgetItemIds[${index}]`));
+  }
+  Object.assign(input, parseQuotationReferences(o, "update-bill"));
+  if (o.lineAmounts !== undefined)
+    input.lineAmounts = parseBillLineAmounts(o, "update-bill");
+  if (o.invoiceDate !== undefined)
+    input.invoiceDate = toDate(o.invoiceDate, "invoiceDate");
+  if (o.verificationStatus !== undefined) {
+    if (!Object.values(BillVerificationStatus).includes(o.verificationStatus))
+      throw validationError("Invalid bill verification status.");
+    input.verificationStatus = o.verificationStatus;
+  }
+  if (o.verificationResults !== undefined) {
+    const value = requireObject(o.verificationResults, "verificationResults");
+    const status = value.status;
+    if (status !== BillVerificationStatus.PENDING && status !== BillVerificationStatus.PASS && status !== BillVerificationStatus.FAIL && status !== BillVerificationStatus.MANUAL_REVIEW)
+      throw validationError("Invalid verificationResults.status.");
+    input.verificationResults = {
+      status,
+      extractedAmount: value.extractedAmount == null ? null : Number(value.extractedAmount),
+      difference: value.difference == null ? null : Number(value.difference),
+      confidence: value.confidence == null ? null : Number(value.confidence),
+      failureReason: value.failureReason == null ? null : String(value.failureReason)
+    };
+  }
+  if (Object.keys(input).length === 1)
+    throw validationError("Supply at least one field to update.");
+  return input;
 }
 function parseValidateBillSelectionPayload(raw, quotationFlags = {}) {
   const input = requireObject(raw, "validate-bill-selection payload");
@@ -8836,6 +8932,42 @@ async function updateBillStatus(opts) {
     } : undefined);
   }
 }
+var listExternalBillPaymentAccounts = async () => {
+  out(await api2.bill.getExternalPaymentAccounts.query());
+};
+var recordExternalBillPayment = async (opts) => {
+  if (!opts.paymentReference.trim() || !opts.paymentAccount.trim() || !/^\d{4}-\d{2}-\d{2}$/.test(opts.paymentDate) || new Date(`${opts.paymentDate}T00:00:00Z`).toISOString().slice(0, 10) !== opts.paymentDate)
+    throw new Error("Supply --paymentReference, --paymentDate YYYY-MM-DD, and --paymentAccount <QBO account ID>.");
+  await assertSensitiveWorkflowConfirmed({
+    action: "Record external payment (no email)",
+    entity: `bill ${opts.id}`,
+    details: `already paid on ${opts.paymentDate}; reference ${opts.paymentReference}; QBO account ${opts.paymentAccount}. No money is transferred.`
+  });
+  const bill = await api2.bill.getById.query({ id: opts.id });
+  const proof = !bill.externalPayment && opts.paymentProofPath ? await stageBillPaymentProof(bill.projectId, opts.paymentProofPath) : undefined;
+  try {
+    out(await api2.bill.recordExternalPayment.mutate({
+      id: opts.id,
+      paymentReference: opts.paymentReference,
+      paymentDate: opts.paymentDate,
+      paymentAccount: opts.paymentAccount,
+      paymentProofAttachments: proof ? [proof] : undefined
+    }));
+  } catch (error) {
+    try {
+      const latest = await api2.bill.getById.query({ id: opts.id });
+      if (latest.externalPayment?.paymentAccount === opts.paymentAccount && latest.paymentReference === opts.paymentReference.trim() && latest.paymentDate?.toISOString().slice(0, 10) === opts.paymentDate) {
+        out({
+          ...latest,
+          supplierNotified: false,
+          quickbooksReconciliationPending: !latest.externalPayment.quickbooksBillPaymentIds.length
+        });
+        return;
+      }
+    } catch {}
+    throw new Error("External payment result could not be confirmed. Inspect the bill, then retry the same reference/date/account; do not pay again. Any uploaded proof is retained.", { cause: error });
+  }
+};
 async function patchBillPayment(opts) {
   const input = { id: opts.id };
   if (opts.paymentTrackingUrl !== undefined)
@@ -10602,6 +10734,7 @@ var mutationPrefixes = [
   "patch-",
   "reactivate-",
   "reconcile-",
+  "record-",
   "reject-",
   "remove-",
   "replace-",
@@ -10642,6 +10775,7 @@ var emailTargets = new Set([
   "update-supplier"
 ]);
 var externalWriteTargets = new Set([
+  "record-external-bill-payment",
   "approve-bill",
   "approve-customer-invoice",
   "approve-supplier",
@@ -10687,6 +10821,7 @@ var externalWriteTargets = new Set([
   "void-customer-invoice"
 ]);
 var financialWriteTargets = new Set([
+  "record-external-bill-payment",
   "import-qbo-customer-invoice",
   "link-bill-quotations",
   "approve-bill",
@@ -10771,8 +10906,12 @@ var summaryFor = (legacyTarget) => {
   if (legacyTarget === "create-bill") {
     return "Create a bill or claim with an approved supplier. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. --draft-only guarantees DRAFT without email or external writes; otherwise unpaid creation skips email permission but keeps external-write permission.";
   }
+  if (legacyTarget === "record-external-bill-payment")
+    return "Record an already-made payment on an APPROVED bill or claim, with no email and no money transfer. Requires <billId> --paymentReference --paymentDate YYYY-MM-DD --paymentAccount <QBO account ID> [--paymentProof receipt.pdf]. Reuses settled QBO payment links or queues one dated payment from the selected account. Exact retries are safe; do not pay again while reconciliation is pending.";
+  if (legacyTarget === "list-external-payment-accounts")
+    return "List active QuickBooks bank and credit-card account IDs for recording external payments (admin only).";
   if (legacyTarget === "update-bill") {
-    return "Update a bill or claim; payload must include id. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. Re-read and verify both amount fields and allocations after correcting a gross/net mistake.";
+    return "Update a bill or claim with a partial payload including id; omitted fields are preserved. Comment-only updates are allowed on approved/paid bills without altering financial data or QuickBooks. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. Re-read and verify both amount fields and allocations after correcting a gross/net mistake.";
   }
   if (legacyTarget === "validate-bill-selection") {
     return "Validate the approved supplier and selected bill line items.";
@@ -10932,6 +11071,16 @@ var registry2 = [
   ]),
   legacyCommand("delete-bill", ["bill", "delete"]),
   legacyCommand("update-bill-status", ["bill", "status", "update"]),
+  legacyCommand("record-external-bill-payment", [
+    "bill",
+    "payment",
+    "record-external"
+  ]),
+  legacyCommand("list-external-payment-accounts", [
+    "bill",
+    "payment",
+    "accounts"
+  ]),
   legacyCommand("patch-bill-payment", ["bill", "payment", "patch"]),
   legacyCommand("patch-bill-invoice-number", [
     "bill",
@@ -12508,6 +12657,27 @@ Waiting for approval\u2026
         });
         break;
       }
+      case "list-external-payment-accounts": {
+        await listExternalBillPaymentAccounts();
+        break;
+      }
+      case "record-external-bill-payment": {
+        const id = positional[0];
+        const paymentReference = getFlag(flags, "paymentReference");
+        const paymentDate = getFlag(flags, "paymentDate");
+        const paymentAccount = getFlag(flags, "paymentAccount");
+        const paymentProofPath = getFlag(flags, "paymentProof");
+        if (!id || !paymentReference || !paymentDate || !paymentAccount)
+          throw new Error("record-external-bill-payment requires <billId> --paymentReference --paymentDate YYYY-MM-DD --paymentAccount <QBO account ID> [--paymentProof receipt.pdf]");
+        await recordExternalBillPayment({
+          id,
+          paymentReference,
+          paymentDate,
+          paymentAccount,
+          paymentProofPath
+        });
+        break;
+      }
       case "patch-bill-payment": {
         const id = positional[0];
         if (!id)

package/package.json

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