@go-labs-sg/bb 2.42.0 → 2.44.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.
@@ -42,7 +63,7 @@ See the [supplier review and rollout policy](../api/docs/supplier-edit-review.md
 
 ## Runtime and installation
 
-The CLI requires [Bun](https://bun.com/docs/installation) 1.4.0 or newer and a Budget Builder account with any active user role.
+The same CLI package supports macOS and Windows. It requires [Bun](https://bun.com/docs/installation) 1.4.0 or newer and a Budget Builder account with any active user role. Windows users can run the commands below in native PowerShell; Bash and `export PATH=...` are not required.
 
 Check whether a compatible Bun version is already available:
 
@@ -85,6 +106,25 @@ Or run without installing:
 bunx @go-labs-sg/bb <command>
 ```
 
+### Historical budget reads (Admin only)
+
+Budget reads are active-only by default. The API enforces the historical-read permission; the CLI does not grant access based on the flag alone.
+
+```bash
+# Active budgets only (default)
+bb list-budgets
+bb get-budget <budget-id>
+
+# Include inactive budgets; each form requires an ADMIN identity
+bb list-budgets --active false
+bb list-budgets --active all
+bb get-budget <budget-id> --includeInactive
+bb get-budget-items <budget-id> --includeInactive
+bb get-budget-details <budget-id> --includeInactive
+```
+
+`--active false` lists inactive budgets only. `--active all` lists active and inactive budgets. `--includeInactive` allows the three budget/detail/item commands to read inactive history. If the authenticated identity is not an Admin, the API rejects the historical request before reading budget data. For `get-budget`, the CLI requests the budget and its line items concurrently; each API read independently enforces the same active-only default and Admin-only historical opt-in.
+
 ## Authentication
 
 Interactive users authorize the CLI through Budget Builder's normal Google-backed
@@ -102,6 +142,11 @@ credentials through `Bun.secrets`. It never stores Google credentials. Use
 `bb auth logout` to revoke the interactive session. For SSH or containers, pass
 `--no-browser` and open the printed URL on another device.
 
+Credentials use macOS Keychain or Windows Credential Manager, not plaintext files.
+The per-user lock directory contains only random ownership markers used to serialize
+login, refresh, and logout. macOS/Linux enforce owner-only POSIX permissions there;
+Windows uses its native filesystem access controls rather than POSIX mode checks.
+
 Budget Builder API keys remain supported for MCP, CI, and non-interactive
 automation. When `BB_API_KEY` is present it takes precedence over the interactive
 session for that process. Create and manage automation keys under **API Keys** or

package/command-manifest.json

@@ -199,7 +199,7 @@
 	{
 		"path": ["budget", "list"],
 		"legacyAliases": ["list-budgets", "list_budgets"],
-		"summary": "List budgets.",
+		"summary": "List budgets. Omit --active for active budgets only; use --active false or --active all for Admin-only historical reads.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -240,6 +240,10 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--active <true|false|all>",
+				"description": "Omit for active budgets only; false or all requires Admin access."
 			}
 		],
 		"argumentMode": "legacy-passthrough",
@@ -249,7 +253,7 @@
 	{
 		"path": ["budget", "get"],
 		"legacyAliases": ["get-budget", "get_budget"],
-		"summary": "Get budget.",
+		"summary": "Get a budget by ID. Omit --includeInactive for active budgets only; --includeInactive is an Admin-only historical read.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -290,6 +294,10 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--includeInactive",
+				"description": "Include inactive historical budgets; Admin only."
 			}
 		],
 		"argumentMode": "legacy-passthrough",
@@ -399,7 +407,7 @@
 	{
 		"path": ["budget", "item", "list"],
 		"legacyAliases": ["get-budget-items", "get_budget_items"],
-		"summary": "Get budget items.",
+		"summary": "Get line items for a budget. Omit --includeInactive for active budgets only; --includeInactive is an Admin-only historical read.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -440,6 +448,10 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--includeInactive",
+				"description": "Include inactive historical budgets; Admin only."
 			}
 		],
 		"argumentMode": "legacy-passthrough",
@@ -449,7 +461,7 @@
 	{
 		"path": ["budget", "detail", "get"],
 		"legacyAliases": ["get-budget-details", "get_budget_details"],
-		"summary": "Get budget details.",
+		"summary": "Get budget details. Omit --includeInactive for active budgets only; --includeInactive is an Admin-only historical read.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -490,6 +502,10 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--includeInactive",
+				"description": "Include inactive historical budgets; Admin only."
 			}
 		],
 		"argumentMode": "legacy-passthrough",
@@ -2261,7 +2277,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 +2477,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

@@ -51,7 +51,7 @@ Effects: none.
 
 ## `bb budget list`
 
-List budgets.
+List budgets. Omit --active for active budgets only; use --active false or --active all for Admin-only historical reads.
 
 Legacy aliases: `list-budgets`, `list_budgets`.
 
@@ -59,7 +59,7 @@ Effects: none.
 
 ## `bb budget get`
 
-Get budget.
+Get a budget by ID. Omit --includeInactive for active budgets only; --includeInactive is an Admin-only historical read.
 
 Legacy aliases: `get-budget`, `get_budget`.
 
@@ -83,7 +83,7 @@ Effects: state-change, external-write, financial-write.
 
 ## `bb budget item list`
 
-Get budget items.
+Get line items for a budget. Omit --includeInactive for active budgets only; --includeInactive is an Admin-only historical read.
 
 Legacy aliases: `get-budget-items`, `get_budget_items`.
 
@@ -91,7 +91,7 @@ Effects: none.
 
 ## `bb budget detail get`
 
-Get budget details.
+Get budget details. Omit --includeInactive for active budgets only; --includeInactive is an Admin-only historical read.
 
 Legacy aliases: `get-budget-details`, `get_budget_details`.
 
@@ -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

@@ -6071,7 +6071,7 @@ var ensurePrivateCredentialLockDirectory = async () => {
     return directoryStat;
   };
   const directoryStat = await inspectDirectory();
-  if ((directoryStat.mode & 63) !== 0) {
+  if (process.platform !== "win32" && (directoryStat.mode & 63) !== 0) {
     await chmod(directory, 448);
     const securedDirectoryStat = await inspectDirectory();
     if ((securedDirectoryStat.mode & 63) !== 0) {
@@ -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");
@@ -8508,6 +8604,7 @@ async function listBudgets(opts) {
     createdBy: opts.createdBy,
     dateFrom: opts.dateFrom,
     dateTo: opts.dateTo,
+    active: opts.active,
     sortBy: opts.sortBy,
     sortDir: opts.sortDir,
     page: opts.page ?? 1,
@@ -8517,10 +8614,16 @@ async function listBudgets(opts) {
   const result = await api2.budget.getAllBudgets.query(input);
   out(result);
 }
-async function getBudget(id) {
+async function getBudget(id, opts) {
   const [budget, items] = await Promise.all([
-    api2.budget.getBudget.query({ id }),
-    api2.budget.getBudgetItems.query({ budgetId: id })
+    api2.budget.getBudget.query({
+      id,
+      includeInactive: opts?.includeInactive ?? false
+    }),
+    api2.budget.getBudgetItems.query({
+      budgetId: id,
+      includeInactive: opts?.includeInactive ?? false
+    })
   ]);
   out({ budget, items });
 }
@@ -8836,6 +8939,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)
@@ -9091,8 +9230,11 @@ async function getBillDetails(id) {
   const result = await api2.bill.getById.query({ id });
   out(result);
 }
-async function getBudgetItemsOnly(budgetId) {
-  const items = await api2.budget.getBudgetItems.query({ budgetId });
+async function getBudgetItemsOnly(budgetId, opts) {
+  const items = await api2.budget.getBudgetItems.query({
+    budgetId,
+    includeInactive: opts?.includeInactive ?? false
+  });
   out(items);
 }
 async function addBudgetItems(opts) {
@@ -9193,8 +9335,11 @@ var sendEstimateToContactPersonFromPayload = async (raw) => {
   const result = await api2.email.sendEstimateToContactPerson.mutate(input);
   out(result);
 };
-async function getBudgetDetails(budgetId) {
-  const detail = await api2.budget.getBudgetDetail.query({ id: budgetId });
+async function getBudgetDetails(budgetId, opts) {
+  const detail = await api2.budget.getBudgetDetail.query({
+    id: budgetId,
+    includeInactive: opts?.includeInactive ?? false
+  });
   out(detail);
 }
 async function createBudgetFromPayload(raw) {
@@ -10602,6 +10747,7 @@ var mutationPrefixes = [
   "patch-",
   "reactivate-",
   "reconcile-",
+  "record-",
   "reject-",
   "remove-",
   "replace-",
@@ -10642,6 +10788,7 @@ var emailTargets = new Set([
   "update-supplier"
 ]);
 var externalWriteTargets = new Set([
+  "record-external-bill-payment",
   "approve-bill",
   "approve-customer-invoice",
   "approve-supplier",
@@ -10687,6 +10834,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",
@@ -10768,11 +10916,27 @@ var summaryFor = (legacyTarget) => {
   }
   if (legacyTarget === "whoami")
     return "Show the active API-key identity.";
+  if (legacyTarget === "list-budgets") {
+    return "List budgets. Omit --active for active budgets only; use --active false or --active all for Admin-only historical reads.";
+  }
+  if (legacyTarget === "get-budget") {
+    return "Get a budget by ID. Omit --includeInactive for active budgets only; --includeInactive is an Admin-only historical read.";
+  }
+  if (legacyTarget === "get-budget-items") {
+    return "Get line items for a budget. Omit --includeInactive for active budgets only; --includeInactive is an Admin-only historical read.";
+  }
+  if (legacyTarget === "get-budget-details") {
+    return "Get budget details. Omit --includeInactive for active budgets only; --includeInactive is an Admin-only historical read.";
+  }
   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.";
@@ -10838,12 +11002,32 @@ var registry2 = [
   authCommand("status", "Show the active CLI authentication method and session status."),
   authCommand("logout", "Revoke the interactive CLI session and remove its local credential."),
   legacyCommand("whoami", ["auth", "whoami"]),
-  legacyCommand("list-budgets", ["budget", "list"]),
-  legacyCommand("get-budget", ["budget", "get"]),
+  legacyCommand("list-budgets", ["budget", "list"], [], [
+    {
+      name: "--active <true|false|all>",
+      description: "Omit for active budgets only; false or all requires Admin access."
+    }
+  ]),
+  legacyCommand("get-budget", ["budget", "get"], [], [
+    {
+      name: "--includeInactive",
+      description: "Include inactive historical budgets; Admin only."
+    }
+  ]),
   legacyCommand("upload-budget-attachment", ["budget", "attachment", "upload"]),
   legacyCommand("mark-budget-won", ["budget", "won", "mark"]),
-  legacyCommand("get-budget-items", ["budget", "item", "list"]),
-  legacyCommand("get-budget-details", ["budget", "detail", "get"]),
+  legacyCommand("get-budget-items", ["budget", "item", "list"], [], [
+    {
+      name: "--includeInactive",
+      description: "Include inactive historical budgets; Admin only."
+    }
+  ]),
+  legacyCommand("get-budget-details", ["budget", "detail", "get"], [], [
+    {
+      name: "--includeInactive",
+      description: "Include inactive historical budgets; Admin only."
+    }
+  ]),
   legacyCommand("get-budget-categories", ["budget", "category", "list"]),
   legacyCommand("get-budget-versions", ["budget", "version", "list"]),
   legacyCommand("rename-budget-version", ["budget", "version", "rename"]),
@@ -10932,6 +11116,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",
@@ -11377,6 +11571,22 @@ function parseOptionalBoolFlag(flags, key) {
     return false;
   throw new Error(`--${key} must be true or false.`);
 }
+function parseBudgetActiveFlag(flags) {
+  const raw = flags.active;
+  if (raw === undefined)
+    return;
+  if (raw === true) {
+    throw new Error("--active requires true, false, or all.");
+  }
+  const value = String(raw).toLowerCase();
+  if (value === "all")
+    return "all";
+  if (value === "true" || value === "1")
+    return true;
+  if (value === "false" || value === "0")
+    return false;
+  throw new Error("--active must be true, false, or all.");
+}
 var CUSTOMER_INVOICE_SORT_FIELDS = [
   "createdAt",
   "status",
@@ -12070,6 +12280,7 @@ Waiting for approval\u2026
           createdBy: getFlag(flags, "createdBy"),
           dateFrom: getFlag(flags, "dateFrom"),
           dateTo: getFlag(flags, "dateTo"),
+          active: parseBudgetActiveFlag(flags),
           sortBy: getFlag(flags, "sortBy"),
           sortDir: getFlag(flags, "sortDir"),
           page: parsePositiveIntFlag(getFlag(flags, "page"), "--page"),
@@ -12082,7 +12293,9 @@ Waiting for approval\u2026
         const id = positional[0];
         if (!id)
           throw new Error("get-budget requires <id>");
-        await getBudget(id);
+        await getBudget(id, {
+          includeInactive: flags.includeInactive === true ? true : parseOptionalBoolFlag(flags, "includeInactive") ?? false
+        });
         break;
       }
       case "upload-budget-attachment": {
@@ -12109,14 +12322,18 @@ Waiting for approval\u2026
         const id = positional[0];
         if (!id)
           throw new Error("get-budget-items requires <budgetId>");
-        await getBudgetItemsOnly(id);
+        await getBudgetItemsOnly(id, {
+          includeInactive: flags.includeInactive === true ? true : parseOptionalBoolFlag(flags, "includeInactive") ?? false
+        });
         break;
       }
       case "get-budget-details": {
         const id = positional[0];
         if (!id)
           throw new Error("get-budget-details requires <budgetId>");
-        await getBudgetDetails(id);
+        await getBudgetDetails(id, {
+          includeInactive: flags.includeInactive === true ? true : parseOptionalBoolFlag(flags, "includeInactive") ?? false
+        });
         break;
       }
       case "get-budget-categories": {
@@ -12508,6 +12725,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.44.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",