@go-labs-sg/bb 2.40.0 → 2.42.0

package/README.md

@@ -22,6 +22,18 @@ 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.
 
+## 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.
+
+If `create-budget` reports an uncertain outcome (including Prisma P2028 or a network interruption), **do not retry immediately**. Run `bb list-budgets --projectId <project-id>` and check for the budget name first; the write may have committed even though the CLI did not receive a successful response. This check is not an idempotency guarantee when another budget has the same name.
+
+A failed `create-supplier` request may likewise have committed. Inspect `bb list-suppliers --name <name>` and matching supplier details before retrying; names alone do not identify one attempt. If supplier creation succeeded but its separate approval request failed or returned no approval IDs, inspect that supplier's approvals by ID and retry only the approval step if needed. Do not create the supplier again. The CLI confirms the combined supplier-and-approval workflow before the first write.
+
+`create-budget-approval` and `create-estimate` accept `--companyPayload`, `--contactPayload`, and `--eventPayload` as JSON objects. The CLI rejects non-object JSON; the API validates required fields.
+
+`create-project` requires an existing Asana Deals lead task. In non-interactive runs pass `--asanaTaskId`; interactive runs can select a match with `--asanaSearch`. The Slack channel is resolved from the task unless all Slack channel flags are provided. For a new direct client, create the lead task in the website form first.
+
 ## 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.

package/command-manifest.json

@@ -790,6 +790,18 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--companyPayload <json>",
+				"description": "Company update JSON object with id, name, and website fields."
+			},
+			{
+				"name": "--contactPayload <json>",
+				"description": "Contact update JSON object with companyId, title, firstName, lastName, email, and mobile fields."
+			},
+			{
+				"name": "--eventPayload <json>",
+				"description": "Event timing JSON object with date, startTime, and endTime fields."
 			}
 		],
 		"argumentMode": "legacy-passthrough",
@@ -840,6 +852,18 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--companyPayload <json>",
+				"description": "Company update JSON object with id, name, and website fields."
+			},
+			{
+				"name": "--contactPayload <json>",
+				"description": "Contact update JSON object with companyId, title, firstName, lastName, email, and mobile fields."
+			},
+			{
+				"name": "--eventPayload <json>",
+				"description": "Event timing JSON object with date, startTime, and endTime fields."
 			}
 		],
 		"argumentMode": "legacy-passthrough",
@@ -5504,7 +5528,7 @@
 	{
 		"path": ["project", "create"],
 		"legacyAliases": ["create-project", "create_project"],
-		"summary": "Create Project.",
+		"summary": "Create a project linked to an existing Asana Deals lead task. Supply --asanaTaskId in non-interactive use; interactive use searches for and selects a lead task (optionally --asanaSearch). The Slack channel is resolved from the selected Asana task unless all three Slack channel flags are supplied. For a new direct client, create the lead task using the website form first.",
 		"globalOptions": [
 			{
 				"name": "--help",

package/command-reference.md

@@ -161,6 +161,11 @@ Legacy aliases: `send-estimate-to-contact-person`, `send_estimate_to_contact_per
 
 Effects: state-change, email.
 
+Payload fields (--payload JSON)
+  Required: estimateId: string; budgetId: string; to: email; cc: email[]; replyTo: email; subject: string; content: HTML string; signature: HTML string
+  Optional: estimateDocNumber: string
+  Example: bb send-estimate-to-contact-person --payload '{"estimateId":"<estimate-id>","budgetId":"<budget-id>","to":"client@example.com","cc":[],"replyTo":"team@example.com","subject":"Estimate","content":"<p>Attached estimate</p>","signature":"<p>Team</p>"}'
+
 ## `bb budget create`
 
 Create Budget.
@@ -169,6 +174,11 @@ Legacy aliases: `create-budget`, `create_budget`.
 
 Effects: state-change.
 
+Payload fields (--payload JSON)
+  Required: name: string; budget: decimal string; paymentTerm: string; categoryId: string; projectId: string
+  Optional: sourceBudgetId: string; unavailableItemReviewAcknowledged: boolean (only after review); pipedriveDealId: string
+  Example: bb create-budget --payload '{"name":"Event budget","budget":"1500","paymentTerm":"Net 30","categoryId":"<category-id>","projectId":"<project-id>"}'
+
 ## `bb budget update`
 
 Update Budget.
@@ -177,6 +187,11 @@ Legacy aliases: `update-budget`, `update_budget`.
 
 Effects: state-change.
 
+Payload fields (--payload JSON)
+  Required: id: string; name: string; budget: decimal string; paymentTerm: string; categoryId: string; projectId: string
+  Optional: sourceBudgetId: string; pipedriveDealId: string
+  Example: bb update-budget --payload '{"id":"<budget-id>","name":"Event budget","budget":"1500","paymentTerm":"Net 30","categoryId":"<category-id>","projectId":"<project-id>"}'
+
 ## `bb budget delete`
 
 Delete Budget.
@@ -273,6 +288,11 @@ Legacy aliases: `update-budget-commission`, `update_budget_commission`.
 
 Effects: state-change, financial-write.
 
+Payload fields (--payload JSON)
+  Required: budgetId: string; name: string; percentage: decimal string; totalSellingAfterDiscount: number
+  Optional: none
+  Example: bb update-budget-commission --payload '{"budgetId":"<budget-id>","name":"Sales commission","percentage":"10","totalSellingAfterDiscount":1500}'
+
 ## `bb budget discount update`
 
 Update Budget Discount.
@@ -281,6 +301,11 @@ Legacy aliases: `update-budget-discount`, `update_budget_discount`.
 
 Effects: state-change, financial-write.
 
+Payload fields (--payload JSON)
+  Required: budgetId: string; name: string; type: percentage|amount; value: decimal string; totalSellingBeforeDiscount: number
+  Optional: none
+  Example: bb update-budget-discount --payload '{"budgetId":"<budget-id>","name":"Discount","type":"amount","value":"100","totalSellingBeforeDiscount":1500}'
+
 ## `bb budget commission delete`
 
 Delete Budget Commission.
@@ -353,6 +378,11 @@ Legacy aliases: `create-bill`, `create_bill`.
 
 Effects: state-change, email, external-write, financial-write.
 
+Payload fields (--payload JSON)
+  Required: budgetId: string; projectId: string; supplierId: string; amount: number (ex-GST); budgetItemIds: string[]; isClaimable: boolean; supplier bills: quotationIds: string[] or quotationAllocations: {budgetItemId, quotationId, amount}[] (unless --quotation-exempt)
+  Optional: lineAmounts: {budgetItemId, amount}[] (required with quotationAllocations); attachments: {id,name,key,size}[]; invoiceNumber: string; invoiceDate: ISO date; draftOnly: boolean; alreadyPaid: boolean; extractedAmount: number
+  Example: bb create-bill --payload '{"budgetId":"<budget-id>","projectId":"<project-id>","supplierId":"<supplier-id>","amount":1800,"budgetItemIds":["<budget-item-id>"],"isClaimable":false,"quotationIds":["<quotation-id>"],"attachments":[]}'
+
 ## `bb bill selection validate`
 
 Validate the approved supplier and selected bill line items.
@@ -361,6 +391,11 @@ Legacy aliases: `validate-bill-selection`, `validate_bill_selection`.
 
 Effects: none.
 
+Payload fields (--payload JSON)
+  Required: projectId: string; supplierId: string; budgetItemIds: string[]
+  Optional: quotationIds: string[] for supplier bills; isClaimable: boolean; amount: number; lineAmounts: {budgetItemId, amount}[]; quotationAllocations: {budgetItemId, quotationId, amount}[] (requires amount and lineAmounts)
+  Example: bb validate-bill-selection --payload '{"projectId":"<project-id>","supplierId":"<supplier-id>","budgetItemIds":["<budget-item-id>"],"quotationIds":["<quotation-id>"]}'
+
 ## `bb bill quotation link`
 
 Link Bill Quotations.
@@ -369,6 +404,11 @@ Legacy aliases: `link-bill-quotations`, `link_bill_quotations`, `billId`.
 
 Effects: state-change, financial-write.
 
+Payload fields (--payload JSON)
+  Required: positional <billId>; quotationIds: string[] or quotationAllocations: {budgetItemId, quotationId, amount}[]
+  Optional: none (legacy quotationId is not supported)
+  Example: bb link-bill-quotations <billId> --payload '{"quotationIds":["<quotation-id>"]}'
+
 ## `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.
@@ -377,6 +417,11 @@ Legacy aliases: `update-bill`, `update_bill`.
 
 Effects: state-change, external-write, financial-write.
 
+Payload fields (--payload JSON)
+  Required: id: string; budgetId: string; projectId: string; supplierId: string; amount: number (ex-GST); budgetItemIds: string[]; isClaimable: boolean
+  Optional: quotationIds: string[]; quotationAllocations: {budgetItemId, quotationId, amount}[]; lineAmounts: {budgetItemId, amount}[]; attachments: {id,name,key,size}[]; invoiceNumber: string; invoiceDate: ISO date
+  Example: bb update-bill --payload '{"id":"<bill-id>","budgetId":"<budget-id>","projectId":"<project-id>","supplierId":"<supplier-id>","amount":1800,"budgetItemIds":["<budget-item-id>"],"isClaimable":false,"quotationIds":["<quotation-id>"],"attachments":[]}'
+
 ## `bb bill payment-evidence update`
 
 Update Bill Payment Evidence.
@@ -385,6 +430,11 @@ Legacy aliases: `update-bill-payment-evidence`, `update_bill_payment_evidence`.
 
 Effects: state-change, financial-write.
 
+Payload fields (--payload JSON)
+  Required: id: string; paymentReference: string; paymentProofAttachments: {id,name (PDF),key,size}[] (at least one)
+  Optional: none
+  Example: bb update-bill-payment-evidence --payload '{"id":"<bill-id>","paymentReference":"TRANSFER-123","paymentProofAttachments":[{"id":"<attachment-id>","name":"receipt.pdf","key":"<staged-key>","size":1000}]}'
+
 ## `bb bill delete`
 
 Delete Bill.
@@ -513,6 +563,11 @@ Legacy aliases: `create-quotation`, `create_quotation`.
 
 Effects: state-change.
 
+Payload fields (--payload JSON)
+  Required: projectId: string; budgetId: string; supplierId: string; budgetItemIds: string[]; amountWithoutGst: number; gstAmount: number; attachments: array (uploaded attachment)
+  Optional: lineAmounts: {budgetItemId, amount}[] (required for multiple budget items)
+  Example: bb create-quotation --payload '{"projectId":"<project-id>","budgetId":"<budget-id>","supplierId":"<supplier-id>","budgetItemIds":["<budget-item-id>"],"amountWithoutGst":1200,"gstAmount":0,"attachments":[{"id":"<attachment-id>","name":"quote.pdf","key":"<staged-key>","size":1000}]}'
+
 ## `bb quotation update`
 
 Update a DRAFT or REJECTED quotation using --payload JSON with id and the complete creation payload. Multiple budget items require lineAmounts: [{"budgetItemId":"<first-id>","amount":750},{"budgetItemId":"<second-id>","amount":450}], covering every budgetItemIds entry exactly once and summing to amountWithoutGst. Amounts exclude GST; use gstAmount: 0 for no GST.
@@ -521,6 +576,11 @@ Legacy aliases: `update-quotation`, `update_quotation`.
 
 Effects: state-change.
 
+Payload fields (--payload JSON)
+  Required: id: string; projectId: string; budgetId: string; supplierId: string; budgetItemIds: string[]; amountWithoutGst: number; gstAmount: number; attachments: array
+  Optional: lineAmounts: {budgetItemId, amount}[] (required for multiple budget items)
+  Example: bb update-quotation --payload '{"id":"<quotation-id>","projectId":"<project-id>","budgetId":"<budget-id>","supplierId":"<supplier-id>","budgetItemIds":["<budget-item-id>"],"amountWithoutGst":1200,"gstAmount":0,"attachments":[{"id":"<attachment-id>","name":"quote.pdf","key":"<staged-key>","size":1000}]}'
+
 ## `bb quotation delete`
 
 Delete Quotation.
@@ -641,6 +701,11 @@ Legacy aliases: `create-customer-invoice`, `create_customer_invoice`.
 
 Effects: state-change, email, external-write, financial-write.
 
+Payload fields (--payload JSON)
+  Required: budgetId: string; splits: [{label: string, percentage: number, dueDate: ISO date}] (exactly one)
+  Optional: requestId: UUID string (recommended); invoiceDate: ISO date; details: {billingAddress: string, customerMemo: string}; isCustomPercentage: boolean
+  Example: bb create-customer-invoice --payload '{"budgetId":"<budget-id>","splits":[{"label":"Deposit","percentage":50,"dueDate":"2026-10-15"}],"details":{"billingAddress":"1 Example St","customerMemo":"Thanks"}}'
+
 ## `bb customer-invoice discard`
 
 Discard Customer Invoice.
@@ -689,6 +754,11 @@ Legacy aliases: `send-customer-invoice-to-contact-person`, `send_customer_invoic
 
 Effects: state-change, email.
 
+Payload fields (--payload JSON)
+  Required: invoiceId: string; to: email; cc: email[]; replyTo: email; subject: string; content: HTML string; signature: HTML string
+  Optional: none
+  Example: bb send-customer-invoice-to-contact-person --payload '{"invoiceId":"<invoice-id>","to":"client@example.com","cc":[],"replyTo":"team@example.com","subject":"Invoice","content":"<p>Attached invoice</p>","signature":"<p>Team</p>"}'
+
 ## `bb customer-invoice pdf download`
 
 Download a customer invoice PDF when permitted.
@@ -817,6 +887,11 @@ Legacy aliases: `update-company`, `update_company`.
 
 Effects: state-change, external-write.
 
+Payload fields (--payload JSON)
+  Required: id: string; name: string; website: URL string
+  Optional: confirmDistinct: boolean
+  Example: bb update-company --payload '{"id":"<company-id>","name":"Example Co","website":"https://example.com"}'
+
 ## `bb company delete`
 
 Delete Company.
@@ -875,7 +950,7 @@ Effects: state-change, external-write.
 
 ## `bb project create`
 
-Create Project.
+Create a project linked to an existing Asana Deals lead task. Supply --asanaTaskId in non-interactive use; interactive use searches for and selects a lead task (optionally --asanaSearch). The Slack channel is resolved from the selected Asana task unless all three Slack channel flags are supplied. For a new direct client, create the lead task using the website form first.
 
 Legacy aliases: `create-project`, `create_project`.
 
@@ -889,6 +964,11 @@ Legacy aliases: `update-project`, `update_project`.
 
 Effects: state-change, external-write.
 
+Payload fields (--payload JSON)
+  Required: id: string; name: string; companyId: string; contactPersonId: string; asanaTaskId: string; insideSalesId: string; businessDevelopmentId: string; venue: string; dateRange: {from: ISO date}
+  Optional: dateRange.to: ISO date; projectManagerId: string; pax: string; description: string; slackChannelId/slackChannelUrl/slackChannelName: strings (supply all three); requestQboAccountantNotification: boolean; confirmEstimateInvalidation: boolean
+  Example: bb update-project --payload '{"id":"<project-id>","name":"Launch","companyId":"<company-id>","contactPersonId":"<contact-id>","asanaTaskId":"<asana-task-id>","insideSalesId":"<user-id>","businessDevelopmentId":"<user-id>","venue":"Hall","dateRange":{"from":"2026-10-01T09:00:00Z"}}'
+
 ## `bb project delete`
 
 Delete Project.
@@ -953,6 +1033,11 @@ Legacy aliases: `create-contact-person`, `create_contact_person`.
 
 Effects: state-change.
 
+Payload fields (--payload JSON)
+  Required: companyId: string; title: MR|MRS|MS|DR; firstName: string; lastName: string|null; email: string; mobile: string
+  Optional: address: {streetAddress1?, city?, state?, postalCode?, country?}
+  Example: bb create-contact-person --payload '{"companyId":"<company-id>","title":"MS","firstName":"Jane","lastName":"Tan","email":"jane@example.com","mobile":"+65 9123 4567"}'
+
 ## `bb contact update`
 
 Update Contact Person.
@@ -961,6 +1046,11 @@ Legacy aliases: `update-contact-person`, `update_contact_person`.
 
 Effects: state-change.
 
+Payload fields (--payload JSON)
+  Required: id: string; companyId: string; title: MR|MRS|MS|DR; firstName: string; lastName: string|null; email: string; mobile: string
+  Optional: address: object
+  Example: bb update-contact-person --payload '{"id":"<contact-id>","companyId":"<company-id>","title":"MS","firstName":"Jane","lastName":"Tan","email":"jane@example.com","mobile":"+65 9123 4567"}'
+
 ## `bb supplier list`
 
 List suppliers.
@@ -977,6 +1067,11 @@ Legacy aliases: `create-supplier`, `create_supplier`.
 
 Effects: state-change, email, external-write.
 
+Payload fields (--payload JSON)
+  Required: name: string; primaryContactPerson: string; email: string; phone: string; paymentMethodId: string; paymentTerm: string; roleId: string
+  Optional: gstRegistered: boolean; tags: string[]; website: URL string; address: object; attachments: array; bank and PayNow fields
+  Example: bb create-supplier --payload '{"name":"Example Supplier","primaryContactPerson":"Jane Tan","email":"jane@example.com","phone":"91234567","paymentMethodId":"<method-id>","paymentTerm":"Net 30","roleId":"<role-id>"}'
+
 ## `bb supplier update`
 
 Update Supplier.
@@ -985,6 +1080,11 @@ Legacy aliases: `update-supplier`, `update_supplier`.
 
 Effects: state-change, email, external-write.
 
+Payload fields (--payload JSON)
+  Required: id: string; name: string; primaryContactPerson: string; email: string; phone: string; paymentMethodId: string; paymentTerm: string; roleId: string
+  Optional: gstRegistered: boolean; tags: string[]; website: URL string; address: object; attachments: array; bank and PayNow fields
+  Example: bb update-supplier --payload '{"id":"<supplier-id>","name":"Example Supplier","primaryContactPerson":"Jane Tan","email":"jane@example.com","phone":"91234567","paymentMethodId":"<method-id>","paymentTerm":"Net 30","roleId":"<role-id>"}'
+
 ## `bb supplier delete`
 
 Delete Suppliers.
@@ -1065,6 +1165,11 @@ Legacy aliases: `create-item`, `create_item`.
 
 Effects: state-change, external-write.
 
+Payload fields (--payload JSON)
+  Required: name: string (QuickBooks-safe characters); categoryId: string; supplierId: string; cost: decimal string or number
+  Optional: description: string; gstInclusive: boolean; gstOutOfScope: boolean; goLabsProduct: boolean; attachments: array
+  Example: bb create-item --payload '{"name":"Event Crew per hour","categoryId":"<category-id>","supplierId":"<supplier-id>","cost":19}'
+
 ## `bb item update`
 
 Update Item.
@@ -1073,6 +1178,11 @@ Legacy aliases: `update-item`, `update_item`.
 
 Effects: state-change, external-write.
 
+Payload fields (--payload JSON)
+  Required: id: string; name: string; categoryId: string; supplierId: string; cost: decimal string or number
+  Optional: description: string; gstInclusive: boolean; gstOutOfScope: boolean; goLabsProduct: boolean; attachments: array
+  Example: bb update-item --payload '{"id":"<item-id>","name":"Event Crew per hour","categoryId":"<category-id>","supplierId":"<supplier-id>","cost":"19"}'
+
 ## `bb item archive`
 
 Archive Items.
@@ -1297,6 +1407,11 @@ Legacy aliases: `save-inbound-mapping`, `save_inbound_mapping`.
 
 Effects: state-change.
 
+Payload fields (--payload JSON)
+  Required: positional <sourceId>; payload: [{canonicalField: enum, typeformFieldId: string, required?: boolean, typeformFieldRef?: string|null}] (1-50 entries)
+  Optional: required defaults false; typeformFieldRef may be omitted
+  Example: bb save-inbound-mapping <sourceId> --payload '[{"canonicalField":"CONTACT_FIRST_NAME","typeformFieldId":"<typeform-field-id>"}]'
+
 ## `bb inbound automation save`
 
 Save Inbound Automation Config.
@@ -1305,6 +1420,11 @@ Legacy aliases: `save-inbound-automation-config`, `save_inbound_automation_confi
 
 Effects: state-change.
 
+Payload fields (--payload JSON)
+  Required: positional <sourceId>; asanaCustomFields: object; asanaDefaultAssigneeId: string|null; asanaDefaultAssigneeName: string|null; asanaFollowerIds: string[]; asanaProjectId: string; asanaSectionId: string; asanaWonSectionId: string; asanaLostSectionId: string; googleCalendarId: string; googleCalendarTimeZone: string; goshBriefBaseUrl: URL; slackDefaultAssigneeId: string|null; slackInboundChannelId: string; slackInviteUserIds: string[]; slackPitchChannelPrefix: string
+  Optional: asanaDiscussionSectionId, asanaFirstContactSectionId, asanaFirstProposalSentSectionId, asanaProposalWipSectionId: string|null; asanaCustomFields.*: mapped IDs
+  Example: bb save-inbound-automation-config <sourceId> --payload '{"asanaCustomFields":{},"asanaDefaultAssigneeId":null,"asanaDefaultAssigneeName":null,"asanaFollowerIds":[],"asanaProjectId":"<asana-project-id>","asanaSectionId":"<asana-section-id>","asanaWonSectionId":"<asana-won-id>","asanaLostSectionId":"<asana-lost-id>","googleCalendarId":"team@example.com","googleCalendarTimeZone":"Asia/Singapore","goshBriefBaseUrl":"https://example.com/brief","slackDefaultAssigneeId":null,"slackInboundChannelId":"<slack-channel-id>","slackInviteUserIds":[],"slackPitchChannelPrefix":"pitch"}'
+
 ## `bb inbound processing update`
 
 Update Inbound Processing.