@go-labs-sg/bb 2.34.0 → 2.35.0

package/README.md

@@ -296,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"],

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.