@go-labs-sg/bb 2.33.2 → 2.35.0

package/README.md

@@ -12,6 +12,16 @@ For AI agents using this CLI: do not execute mutations until the user explicitly
 
 **Registry:** [`@go-labs-sg/bb`](https://www.npmjs.com/package/@go-labs-sg/bb)
 
+## Company discovery and reuse
+
+`bb company search --query "a star" [--page 2]` searches stored BB companies and QuickBooks company customers, including inactive records. Results identify `bb`, `qbo`, or `both`; punctuation/spacing normalization is for suggestions only. Search does not write to either system.
+
+After reviewing a result, `bb company use --companyId <bbId>` reuses BB and resolves its QBO customer. `bb company use --quickbooksId <qboId>` imports the existing QBO name/website when BB is missing. Supply both IDs to explicitly connect two unlinked records whose names differ; existing company details are preserved. If QBO has no website, add `--website <url>` for the BB import only.
+
+The shared API rechecks existing records at submission. Canonical matches reuse records; fuzzy matches require an explicit choice or `--confirmDistinct true` to confirm a separate legal entity. Inactive companies and conflicting links require review, never implicit reactivation. QBO project/sub-customers are not company-import candidates. Provider failures are not treated as missing records.
+
+`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.
+
 ## Shared catalogue editing
 
 All active authenticated users can edit suppliers, inventory items and item categories. Normal-user supplier updates submit a revision for approval in the shared API; item/category edits apply immediately. Lead/Admin supplier edits bypass human review. `bb supplier update` returns the server-owned approval/synchronization result without issuing another approval request. New supplier usage stays on hold during review and linked QuickBooks synchronization; existing usage continues with the last approved details until the edit is approved. Creator identity and delete/archive permissions are unchanged.
@@ -286,6 +296,52 @@ Bill creation determines its required permissions from the parsed input, for bot
 
 **Contact-person estimate email:** `bb budget estimate send --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 durably queues worker delivery of the QuickBooks PDF, standard terms, and Budget Builder budget attachments, and returns the outbound-email and operation IDs immediately. Worker retries reuse one provider idempotency key; the budget becomes `ESTIMATE_SENT` only after Resend accepts the email. The command requires interactive `CONFIRM`; inspect the budget, recipients, and HTML first.
 
+### Acceptance invoice splits and grouped sending
+
+After `bb budget won mark` (or an accepted status update), the JSON result includes an `invoiceSetup` prompt for QuickBooks-backed estimates. Choose the split amounts and each split's contractual due date; invoice creation does not wait for those due dates. There is no separate split-approval request.
+
+1. `bb customer-invoice splits <budgetId>` returns the current revision, row IDs, billing defaults, and invoice approval/delivery states.
+2. `bb customer-invoice preview-splits --payload '<json>'` previews amounts including GST and due-date changes, without writes.
+3. `bb customer-invoice save-splits --payload '<json>'` saves that setup only. It does not create QBO invoices or request invoice approval. Re-read `splits` for the new revision and instalment IDs.
+4. `bb customer-invoice create-splits --payload '{"budgetId":"budget_1","expectedRevision":2,"instalmentIds":["row_1","row_2"]}'` creates selected ready invoices in QBO. Non-admin creation automatically requests admin approval **after creation**; admin creation auto-approves. No customer email is sent.
+5. An admin uses the existing `bb customer-invoice approve <batchId>` action for each pending invoice batch. Approval does not send the invoice to the customer.
+6. The user re-reads `splits`, then runs `bb customer-invoice send-group --payload '{"budgetId":"budget_1","expectedRevision":2,"instalmentIds":["row_1","row_2"]}'` to send approved invoices together in one email. Select one row for individual sending. Alternatively, use `--all-approved --payload '{"budgetId":"budget_1","expectedRevision":2}'` to select all approved, unsent invoices in that budget. Do not combine `--all-approved` with `instalmentIds`.
+
+Preview/save use this shape, populated from the current `splits` result and the signed terms (IDs, addresses, and dates below are examples only):
+
+```json
+{
+  "budgetId": "budget_1",
+  "expectedRevision": 1,
+  "scope": "BASE",
+  "changeReason": "Confirmed invoice split and due dates from signed estimate",
+  "definition": {
+    "rows": [
+      { "key": "deposit", "label": "Deposit", "amount": { "type": "PERCENTAGE", "value": 70 }, "due": { "type": "CONFIRMATION" }, "issue": { "type": "ACCEPTANCE" } },
+      { "key": "balance", "label": "Balance", "amount": { "type": "PERCENTAGE", "value": 30 }, "due": { "type": "FIXED_DATE", "date": "2026-12-01" }, "issue": { "type": "ACCEPTANCE" } }
+    ],
+    "reminderLeadDays": 7,
+    "billingRestriction": ""
+  },
+  "billing": {
+    "legalEntityName": "Customer legal entity",
+    "purchaseOrder": "PO-reference",
+    "billingAddress": "Customer billing address",
+    "to": "billing@example.invalid",
+    "cc": [],
+    "replyTo": "owner@example.invalid",
+    "deliveryMethod": "EMAIL",
+    "uploadUrl": null
+  }
+}
+```
+
+Use the exact current revision (or `null` only when no schedule exists). Fixed amounts use **pre-GST cents**; percentages use percentage points. Event-relative due rules are `EVENT_START` or `EVENT_END` with `offsetDays`. Preview and resolve missing dates, past-due review or unresolved amounts rather than inventing replacements.
+
+Non-interactive save requires `--allow-state-change`; creation requires `--allow-state-change --allow-financial-write --allow-external-write --allow-email` (approval-request email, not customer invoice delivery); grouped sending requires `--allow-state-change --allow-email --allow-external-write`. These flags acknowledge effects, not role permissions or user authorisation. Both ordinary users and admins still need server-granted project access. Pending/rejected invoices cannot be sent; a mixed selection is rejected rather than silently dropping invoices. Sending uses each issued invoice's original billing revision, not later edits. Invoices with different original billing instructions must be sent in separate groups. Do not blindly retry uncertain QBO or email outcomes.
+
+These commands require the matching API deployment and a new CLI release; changing this repository does not publish the CLI or deploy production.
+
 ### Quotation amounts and line allocations
 
 Quotation create and update payloads use `amountWithoutGst` for the supplier subtotal and `gstAmount` for GST. Keep GST separate; do not add it to `amountWithoutGst`. When a quotation covers more than one budget item, `lineAmounts` is required and must contain each selected item exactly once. The line amounts must sum to `amountWithoutGst`.

package/command-manifest.json

@@ -3829,6 +3829,275 @@
 		"effects": ["state-change", "financial-write"],
 		"legacyTarget": "import-qbo-customer-invoice"
 	},
+	{
+		"path": ["customer-invoice", "splits"],
+		"legacyAliases": [
+			"get-customer-invoice-splits",
+			"get_customer_invoice_splits"
+		],
+		"summary": "Review acceptance invoice splits, due dates, approval states and saved billing details. Arguments: <budgetId>.",
+		"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": "get-customer-invoice-splits"
+	},
+	{
+		"path": ["customer-invoice", "preview-splits"],
+		"legacyAliases": [
+			"preview-customer-invoice-splits",
+			"preview_customer_invoice_splits"
+		],
+		"summary": "Preview splits, GST totals and due-date changes without writes. Requires --payload with the schedule save input.",
+		"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": "preview-customer-invoice-splits"
+	},
+	{
+		"path": ["customer-invoice", "save-splits"],
+		"legacyAliases": [
+			"save-customer-invoice-splits",
+			"save_customer_invoice_splits"
+		],
+		"summary": "Save split amounts and separate due dates after estimate acceptance. Requires --payload; does not create invoices or request approval.",
+		"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"],
+		"legacyTarget": "save-customer-invoice-splits"
+	},
+	{
+		"path": ["customer-invoice", "create-splits"],
+		"legacyAliases": [
+			"create-customer-invoice-splits",
+			"create_customer_invoice_splits"
+		],
+		"summary": "Create selected split invoices in QBO, then request admin approval for non-admin creators or auto-approve admin creators. Requires --payload with budgetId, expectedRevision, instalmentIds. Never sends customer invoices.",
+		"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", "financial-write", "external-write", "email"],
+		"legacyTarget": "create-customer-invoice-splits"
+	},
+	{
+		"path": ["customer-invoice", "send-group"],
+		"legacyAliases": [
+			"send-customer-invoice-group",
+			"send_customer_invoice_group"
+		],
+		"summary": "Send selected approved invoices together in one email. Requires --payload with budgetId, expectedRevision, instalmentIds, or --all-approved without instalmentIds. Pass one instalment for individual sending.",
+		"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."
+			},
+			{
+				"name": "--all-approved",
+				"description": "Select all approved unsent invoices; payload must contain only budgetId and expectedRevision."
+			}
+		],
+		"argumentMode": "legacy-passthrough",
+		"effects": ["state-change", "email", "external-write"],
+		"legacyTarget": "send-customer-invoice-group"
+	},
 	{
 		"path": ["customer-invoice", "create"],
 		"legacyAliases": ["create-customer-invoice", "create_customer_invoice"],
@@ -4790,10 +5059,134 @@
 		"effects": [],
 		"legacyTarget": "get-company"
 	},
+	{
+		"path": ["company", "search"],
+		"legacyAliases": ["search-existing-companies", "search_existing_companies"],
+		"summary": "Search BB and QuickBooks companies without writes. --query <name> [--page <number>].",
+		"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."
+			},
+			{
+				"name": "--query",
+				"description": "Company name to search in BB and QuickBooks."
+			},
+			{
+				"name": "--page",
+				"description": "Results page (eight companies per page)."
+			}
+		],
+		"argumentMode": "legacy-passthrough",
+		"effects": [],
+		"legacyTarget": "search-existing-companies"
+	},
+	{
+		"path": ["company", "use"],
+		"legacyAliases": ["use-existing-company", "use_existing_company"],
+		"summary": "Reuse a company in BB and QuickBooks, creating only its missing counterpart. Supply --companyId <bbId> and/or --quickbooksId <qboId>; both explicitly connect records with different names. --website <url> fills a missing QBO import website only. --confirmDistinct true confirms no similar record represents this entity.",
+		"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."
+			},
+			{
+				"name": "--companyId",
+				"description": "Existing BB company ID; combine with quickbooksId to explicitly connect both records."
+			},
+			{
+				"name": "--quickbooksId",
+				"description": "Existing QBO customer ID; alone imports or reuses its BB company."
+			},
+			{
+				"name": "--website",
+				"description": "Website only when missing from a QBO-only import."
+			},
+			{
+				"name": "--confirmDistinct",
+				"description": "Set true only when similar records do not represent this legal entity."
+			}
+		],
+		"argumentMode": "legacy-passthrough",
+		"effects": ["state-change", "external-write"],
+		"legacyTarget": "use-existing-company"
+	},
 	{
 		"path": ["company", "create"],
 		"legacyAliases": ["create-company", "create_company"],
-		"summary": "Create Company.",
+		"summary": "Create or reuse a company in BB and QuickBooks. --name <name> --website <url>. Similar names require --confirmDistinct true; inactive companies are never reactivated.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -4834,6 +5227,10 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--confirmDistinct",
+				"description": "Set true to confirm a separate legal entity despite similar names."
 			}
 		],
 		"argumentMode": "legacy-passthrough",

package/command-reference.md

@@ -617,6 +617,46 @@ Legacy aliases: `import-qbo-customer-invoice`, `import_qbo_customer_invoice`.
 
 Effects: state-change, financial-write.
 
+## `bb customer-invoice splits`
+
+Review acceptance invoice splits, due dates, approval states and saved billing details. Arguments: <budgetId>.
+
+Legacy aliases: `get-customer-invoice-splits`, `get_customer_invoice_splits`.
+
+Effects: none.
+
+## `bb customer-invoice preview-splits`
+
+Preview splits, GST totals and due-date changes without writes. Requires --payload with the schedule save input.
+
+Legacy aliases: `preview-customer-invoice-splits`, `preview_customer_invoice_splits`.
+
+Effects: none.
+
+## `bb customer-invoice save-splits`
+
+Save split amounts and separate due dates after estimate acceptance. Requires --payload; does not create invoices or request approval.
+
+Legacy aliases: `save-customer-invoice-splits`, `save_customer_invoice_splits`.
+
+Effects: state-change.
+
+## `bb customer-invoice create-splits`
+
+Create selected split invoices in QBO, then request admin approval for non-admin creators or auto-approve admin creators. Requires --payload with budgetId, expectedRevision, instalmentIds. Never sends customer invoices.
+
+Legacy aliases: `create-customer-invoice-splits`, `create_customer_invoice_splits`.
+
+Effects: state-change, financial-write, external-write, email.
+
+## `bb customer-invoice send-group`
+
+Send selected approved invoices together in one email. Requires --payload with budgetId, expectedRevision, instalmentIds, or --all-approved without instalmentIds. Pass one instalment for individual sending.
+
+Legacy aliases: `send-customer-invoice-group`, `send_customer_invoice_group`.
+
+Effects: state-change, email, external-write.
+
 ## `bb customer-invoice create`
 
 Create Customer Invoice.
@@ -769,9 +809,25 @@ Legacy aliases: `get-company`, `get_company`.
 
 Effects: none.
 
+## `bb company search`
+
+Search BB and QuickBooks companies without writes. --query <name> [--page <number>].
+
+Legacy aliases: `search-existing-companies`, `search_existing_companies`.
+
+Effects: none.
+
+## `bb company use`
+
+Reuse a company in BB and QuickBooks, creating only its missing counterpart. Supply --companyId <bbId> and/or --quickbooksId <qboId>; both explicitly connect records with different names. --website <url> fills a missing QBO import website only. --confirmDistinct true confirms no similar record represents this entity.
+
+Legacy aliases: `use-existing-company`, `use_existing_company`.
+
+Effects: state-change, external-write.
+
 ## `bb company create`
 
-Create Company.
+Create or reuse a company in BB and QuickBooks. --name <name> --website <url>. Similar names require --confirmDistinct true; inactive companies are never reactivated.
 
 Legacy aliases: `create-company`, `create_company`.