@go-labs-sg/bb 2.48.0 → 3.0.0

package/command-reference.md

@@ -51,12 +51,20 @@ Effects: none.
 
 ## `bb budget list`
 
-List budgets. Omit --active for active budgets only; use --active false or --active all for Admin-only historical reads.
+List one cursor page of budgets ({ items, pageInfo }; --limit/--cursor/--direction). Omit --active for active budgets only; use --active false or --active all for Admin-only historical reads.
 
 Legacy aliases: `list-budgets`, `list_budgets`.
 
 Effects: none.
 
+## `bb budget count`
+
+Count budgets matching filters: totalCount plus status and active facets. Omit --active for active budgets only.
+
+Legacy aliases: `count-budgets`, `count_budgets`.
+
+Effects: none.
+
 ## `bb budget get`
 
 Get a budget by ID. Omit --includeInactive for active budgets only; --includeInactive is an Admin-only historical read.
@@ -99,7 +107,7 @@ Effects: none.
 
 ## `bb budget category list`
 
-Get budget categories.
+List budget categories with cursor pagination. [--q] [--limit 1-100] [--cursor <token>] Active categories, name A–Z. Returns { items, pageInfo }; follow nextCursor with the same --q.
 
 Legacy aliases: `get-budget-categories`, `get_budget_categories`.
 
@@ -131,7 +139,7 @@ Effects: state-change, delete, external-write, financial-write.
 
 ## `bb budget status update`
 
-Update Budget Status.
+Update budget status. APPROVED requires a current Lead/Admin role; budget management permission alone is insufficient. Ordinary users must request approval. Status changes invalidate old pending requests.
 
 Legacy aliases: `update-budget-status`, `update_budget_status`.
 
@@ -139,7 +147,7 @@ Effects: state-change, external-write, financial-write.
 
 ## `bb budget approval create`
 
-Create Budget Approval.
+Request budget approval for the current content, superseding older pending requests. Existing Lead/Admin autoapproval remains available.
 
 Legacy aliases: `create-budget-approval`, `create_budget_approval`.
 
@@ -250,7 +258,7 @@ Effects: state-change.
 
 ## `bb budget item supplier update`
 
-Update Budget Item Supplier.
+Change a budget item's eligible supplier/GST snapshot as a material financial edit. Supersede pending approvals and apply the standard budget-to-DRAFT reset policy; inspect and request approval again. An unchanged supplier is a no-op.
 
 Legacy aliases: `update-budget-item-supplier`, `update_budget_item_supplier`.
 
@@ -348,7 +356,7 @@ Effects: state-change, external-write, financial-write.
 
 ## `bb bill list`
 
-List bills.
+List bills with cursor pagination. [--projectId] [--budgetId] [--status CSV] [--search <text>] [--isClaimable true|false] [--createdByIds <csv>] [--sortBy createdAt|amount|status] [--sortDir asc|desc] [--limit 1-100] [--cursor <token>] [--direction forward|backward] Returns { items, pageInfo }; pass nextCursor with --direction forward or previousCursor with --direction backward, keeping the same filters and sort. --page/--pageSize/--perPage are rejected.
 
 Legacy aliases: `list-bills`, `list_bills`.
 
@@ -356,12 +364,28 @@ Effects: none.
 
 ## `bb claim list`
 
-List claims.
+List reimbursable claims with cursor pagination. Same flags as list-bills (--limit 1-100, --cursor, --direction forward|backward); ignores --isClaimable. Returns { items, pageInfo }.
 
 Legacy aliases: `list-claims`, `list_claims`.
 
 Effects: none.
 
+## `bb bill count`
+
+Count Bills.
+
+Legacy aliases: `count-bills`, `count_bills`.
+
+Effects: none.
+
+## `bb claim count`
+
+Count Claims.
+
+Legacy aliases: `count-claims`, `count_claims`.
+
+Effects: none.
+
 ## `bb bill approval create`
 
 Create Bill Approval.
@@ -485,7 +509,7 @@ Effects: state-change.
 
 ## `bb bill attachment list`
 
-Get bill attachments.
+List bill attachments with cursor pagination. <billId> [--limit 1-50] [--cursor <token>] Newest first. Returns { items, pageInfo }; follow nextCursor.
 
 Legacy aliases: `get-bill-attachments`, `get_bill_attachments`.
 
@@ -541,12 +565,20 @@ Effects: none.
 
 ## `bb quotation list`
 
-List quotations.
+List quotations with cursor pagination. [--projectId] [--budgetId] [--supplierId] [--status CSV] [--createdBy CSV] [--search] [--limit 1-100] [--cursor <token>] [--direction forward|backward] Newest first; returns { items, pageInfo }. Follow nextCursor/previousCursor with the same filters. --page/--pageSize/--perPage are rejected; --requesterIds remains an alias for --createdBy.
 
 Legacy aliases: `list-quotations`, `list_quotations`.
 
 Effects: none.
 
+## `bb quotation count`
+
+Count Quotations.
+
+Legacy aliases: `count-quotations`, `count_quotations`.
+
+Effects: none.
+
 ## `bb quotation get`
 
 Get quotation.
@@ -565,7 +597,7 @@ Effects: state-change.
 
 ## `bb quotation attachment staged cleanup`
 
-Cleanup Staged Quotation Attachments.
+Queue independent cleanup operations for unattached staged quotation uploads; returns operation IDs and queued/skipped counts, not deletion confirmation. Arguments: <projectId> --keys <csv>.
 
 Legacy aliases: `cleanup-staged-quotation-attachments`, `cleanup_staged_quotation_attachments`.
 
@@ -607,7 +639,7 @@ Effects: state-change, delete.
 
 ## `bb quotation submit`
 
-Submit Quotation.
+Submit a quotation for signing and approval. Claim the captured revision and exact allocation selection; concurrent edits, budget-item deletion or restore cascades conflict instead of attaching old signed PDFs. Refresh and resubmit the current content.
 
 Legacy aliases: `submit-quotation`, `submit_quotation`.
 
@@ -615,7 +647,7 @@ Effects: state-change.
 
 ## `bb quotation approve`
 
-Approve Quotation.
+Approve your assigned pending quotation as a current Admin. Claim the captured revision and exact allocation selection after signing; concurrent changes conflict and roll back the decision, signed attachment and email/outbox. Refresh and review the current content before retrying.
 
 Legacy aliases: `approve-quotation`, `approve_quotation`.
 
@@ -671,12 +703,20 @@ Effects: none.
 
 ## `bb customer-invoice list`
 
-List customer invoices.
+List customer invoice batches with cursor pagination. [budgetId] [--projectId <id>] [--companyIds CSV] [--projectIds CSV] [--budgetIds CSV] [--createdByIds CSV] [--status CSV] [--search] [--sortBy createdAt|status|totalInvoiceAmount|approvalExpiresAt] [--sortDir asc|desc] [--limit 1-100] [--cursor <token>] [--direction forward|backward] Returns { items, pageInfo }; follow nextCursor/previousCursor with the same filters and sort. --page/--perPage are rejected. No scope flag lists invoices globally. --projectId uses the project scope. A positional budgetId is a backward-compatible shortcut for --budgetIds.
 
 Legacy aliases: `list-customer-invoices`, `list_customer_invoices`.
 
 Effects: none.
 
+## `bb customer-invoice count`
+
+Count Customer Invoices.
+
+Legacy aliases: `count-customer-invoices`, `count_customer_invoices`.
+
+Effects: none.
+
 ## `bb customer-invoice get`
 
 Get customer invoice.
@@ -817,7 +857,7 @@ Effects: state-change, email.
 
 ## `bb budget approve`
 
-Approve Budget.
+Decide your assigned pending budget approval as a current Lead/Admin. Material edits supersede old requests; inspect the latest content and use a fresh request after edits.
 
 Legacy aliases: `approve-budget`, `approve_budget`.
 
@@ -825,7 +865,7 @@ Effects: state-change, email.
 
 ## `bb budget reject`
 
-Reject Budget.
+Decide your assigned pending budget approval as a current Lead/Admin. Material edits supersede old requests; inspect the latest content and use a fresh request after edits.
 
 Legacy aliases: `reject-budget`, `reject_budget`.
 
@@ -857,12 +897,20 @@ Effects: none.
 
 ## `bb company list`
 
-List companies.
+List companies with cursor pagination. Returns { items, pageInfo }; default sort is createdAt descending with limit 20. Pass nextCursor forward or previousCursor backward unchanged. Legacy page/perPage flags are rejected.
 
 Legacy aliases: `list-companies`, `list_companies`.
 
 Effects: none.
 
+## `bb company count`
+
+Count companies independently from list pagination. Returns { totalCount, counts: { active: { true, false } } }; accepts filters only and rejects pagination/sorting flags.
+
+Legacy aliases: `count-companies`, `count_companies`.
+
+Effects: none.
+
 ## `bb company get`
 
 Get company.
@@ -873,7 +921,7 @@ Effects: none.
 
 ## `bb company search`
 
-Search BB and QuickBooks companies without writes. --query <name> [--page <number>].
+Search BB and QuickBooks companies without writes. --query <name> [--limit 1-50] [--cursor <token>]. Returns { items, totalCount, pageInfo }; follow pageInfo.nextCursor with the same --query. Legacy --page is rejected.
 
 Legacy aliases: `search-existing-companies`, `search_existing_companies`.
 
@@ -897,7 +945,7 @@ Effects: state-change, external-write.
 
 ## `bb company update`
 
-Update Company.
+Save company fields in BB and queue independent QuickBooks name/website synchronization; returns operation ID, not provider completion.
 
 Legacy aliases: `update-company`, `update_company`.
 
@@ -908,6 +956,14 @@ Payload fields (--payload JSON)
   Optional: confirmDistinct: boolean
   Example: bb update-company --payload '{"id":"<company-id>","name":"Example Co","website":"https://example.com"}'
 
+## `bb company sync status`
+
+Read saved company synchronization status without provider calls or polling; use companyId.
+
+Legacy aliases: `get-company-quickbooks-sync-status`, `get_company_quickbooks_sync_status`.
+
+Effects: none.
+
 ## `bb company delete`
 
 Delete Company.
@@ -918,12 +974,20 @@ Effects: state-change, delete, external-write.
 
 ## `bb project list`
 
-List projects.
+List projects with cursor pagination. Returns { items, pageInfo }; default sort is createdAt descending with limit 20. Supports legacy --status plus optional --statuses, WON-date filters (--wonFrom, --wonTo, --wonWithinDays) and --sortBy wonAt; pass nextCursor forward or previousCursor backward unchanged. Legacy page/perPage flags are rejected.
 
 Legacy aliases: `list-projects`, `list_projects`.
 
 Effects: none.
 
+## `bb project count`
+
+Count projects independently from list pagination. Returns { totalCount, counts: { status, active: { true, false } } }; accepts project filters only and rejects pagination/sorting flags.
+
+Legacy aliases: `count-projects`, `count_projects`.
+
+Effects: none.
+
 ## `bb project hub list`
 
 List project hubs.
@@ -932,6 +996,14 @@ Legacy aliases: `list-project-hubs`, `list_project_hubs`.
 
 Effects: none.
 
+## `bb project hub count`
+
+Count Project Hubs.
+
+Legacy aliases: `count-project-hubs`, `count_project_hubs`.
+
+Effects: none.
+
 ## `bb project get`
 
 Get project.
@@ -1075,9 +1147,17 @@ Legacy aliases: `list-suppliers`, `list_suppliers`.
 
 Effects: none.
 
+## `bb supplier count`
+
+Count Suppliers.
+
+Legacy aliases: `count-suppliers`, `count_suppliers`.
+
+Effects: none.
+
 ## `bb supplier create`
 
-Create Supplier.
+Create a supplier using --payload JSON; pending-approval suppliers also request approval and send emails. Reusing an archived name requires Admin; normal users and Leads must ask an Admin to reactivate it before editing. Recreation preserves the existing approval status and creator.
 
 Legacy aliases: `create-supplier`, `create_supplier`.
 
@@ -1151,20 +1231,36 @@ Effects: state-change.
 
 ## `bb supplier analytics get`
 
-Get supplier analytics.
+List supplier analytics rows with cursor pagination. [--name] [--status CSV] [--gstRegistered true|false] [--createdBy <text>] [--timeFrame ALL|LAST_YEAR|LAST_6_MONTHS|LAST_3_MONTHS|CUSTOM] [--startDate <ISO> --endDate <ISO>] [--sortBy name|gstRegistered|status|phone|email|updatedAt|createdAt] [--sortDir asc|desc] [--limit 1-100] [--cursor <token>] [--direction forward|backward] Admin. Returns { items, pageInfo }; follow nextCursor/previousCursor with the same filters and sort. --page/--perPage are rejected.
 
 Legacy aliases: `get-supplier-analytics`, `get_supplier_analytics`.
 
 Effects: none.
 
+## `bb supplier analytics count`
+
+Count Supplier Analytics.
+
+Legacy aliases: `count-supplier-analytics`, `count_supplier_analytics`.
+
+Effects: none.
+
 ## `bb item list`
 
-List items.
+List one cursor page of catalogue items ({ items, pageInfo }; --limit/--cursor/--direction, optional --sortBy/--sortDir). --page/--perPage are rejected.
 
 Legacy aliases: `list-items`, `list_items`.
 
 Effects: none.
 
+## `bb item count`
+
+Count catalogue items matching filters: total plus category and supplier facets (each ignores its own filter).
+
+Legacy aliases: `count-items`, `count_items`.
+
+Effects: none.
+
 ## `bb item get`
 
 Get item.
@@ -1173,6 +1269,14 @@ Legacy aliases: `get-item`, `get_item`.
 
 Effects: none.
 
+## `bb item sync status`
+
+Read saved item QuickBooks synchronization status without provider calls or polling; use itemId.
+
+Legacy aliases: `get-item-quickbooks-sync-status`, `get_item_quickbooks_sync_status`.
+
+Effects: none.
+
 ## `bb item create`
 
 Create Item.
@@ -1217,12 +1321,20 @@ Effects: state-change, delete, external-write.
 
 ## `bb item category list`
 
-List item categories.
+List one cursor page of active item categories ({ items, pageInfo }; --limit/--cursor/--direction, optional --name/--sortBy/--sortDir). --page/--perPage are rejected.
 
 Legacy aliases: `list-item-categories`, `list_item_categories`.
 
 Effects: none.
 
+## `bb item category count`
+
+Count active item categories matching --name: { totalCount }.
+
+Legacy aliases: `count-item-categories`, `count_item_categories`.
+
+Effects: none.
+
 ## `bb item category create`
 
 Create Item Category.
@@ -1249,12 +1361,20 @@ Effects: state-change, delete.
 
 ## `bb user list`
 
-List users.
+List users with cursor pagination. [--q] [--limit 1-100] [--cursor <token>] Name A–Z. Returns { items, pageInfo }; follow nextCursor with the same --q. --page/--perPage are rejected.
 
 Legacy aliases: `list-users`, `list_users`.
 
 Effects: none.
 
+## `bb user count`
+
+Count Users.
+
+Legacy aliases: `count-users`, `count_users`.
+
+Effects: none.
+
 ## `bb user create`
 
 Create User.
@@ -1273,7 +1393,7 @@ Effects: state-change.
 
 ## `bb user api-key list`
 
-List api keys.
+List API keys with cursor pagination. [--userId <userId>] [--limit 1-100] [--cursor <token>] (newest first, { items, pageInfo }; defaults to the caller; admin required for another user)
 
 Legacy aliases: `list-api-keys`, `list_api_keys`.
 
@@ -1343,6 +1463,14 @@ Legacy aliases: `get-recent-errors`, `get_recent_errors`.
 
 Effects: none.
 
+## `bb error recent count`
+
+Count Errors.
+
+Legacy aliases: `count-errors`, `count_errors`.
+
+Effects: none.
+
 ## `bb error metrics get`
 
 Get error metrics.
@@ -1353,20 +1481,132 @@ Effects: none.
 
 ## `bb integration operation list`
 
-List integration operations.
+List one cursor page of integration operations, newest first ({ items, pageInfo }; --limit/--cursor/--direction). --page/--perPage are rejected. Admin only.
 
 Legacy aliases: `list-integration-operations`, `list_integration_operations`.
 
 Effects: none.
 
+## `bb integration operation count`
+
+Count integration operations matching filters: { totalCount, filterOptions }. Admin only.
+
+Legacy aliases: `count-integration-operations`, `count_integration_operations`.
+
+Effects: none.
+
+## `bb integration operation get`
+
+Admin-only read of one integration job: who queued it, the records it is for with app links, saved QuickBooks progress, admin actions and Retry state. No provider calls. Argument: <operationId>.
+
+Legacy aliases: `get-integration-operation`, `get_integration_operation`.
+
+Effects: none.
+
 ## `bb integration operation retry`
 
-Retry Integration Operation.
+Admin-only retry of a failed integration job. QuickBooks jobs with a saved attempt check QuickBooks first: applied changes finish without resending, provably unapplied ones are sent again, unprovable ones stay stopped with the reason. Argument: <operationId>.
 
 Legacy aliases: `retry-integration-operation`, `retry_integration_operation`.
 
 Effects: state-change, external-write.
 
+## `bb integration operation reconcile-resource`
+
+Admin-only check of a saved QuickBooks invoice/company/item job outcome; reads the provider only when uncertain. Applied changes are finished locally without repeating the provider mutation; provably unapplied ones are queued again. Argument: <operationId>.
+
+Legacy aliases: `reconcile-resource-operation`, `reconcile_resource_operation`.
+
+Effects: state-change.
+
+## `bb webhook event-type list`
+
+List the outbound webhook event catalogue with group and live/planned status.
+
+Legacy aliases: `list-webhook-event-types`, `list_webhook_event_types`.
+
+Effects: none.
+
+## `bb webhook endpoint list`
+
+List webhook endpoints.
+
+Legacy aliases: `list-webhook-endpoints`, `list_webhook_endpoints`.
+
+Effects: none.
+
+## `bb webhook endpoint get`
+
+Get webhook endpoint.
+
+Legacy aliases: `get-webhook-endpoint`, `get_webhook_endpoint`.
+
+Effects: none.
+
+## `bb webhook endpoint create`
+
+Admin-only: subscribe an HTTPS endpoint to BB events. --name --url --events <type|prefix.*|*,...>. Prints the whsec_ signing secret once; deliveries use Standard Webhooks headers.
+
+Legacy aliases: `create-webhook-endpoint`, `create_webhook_endpoint`.
+
+Effects: state-change.
+
+## `bb webhook endpoint update`
+
+Update Webhook Endpoint.
+
+Legacy aliases: `update-webhook-endpoint`, `update_webhook_endpoint`.
+
+Effects: state-change.
+
+## `bb webhook endpoint delete`
+
+Delete Webhook Endpoint.
+
+Legacy aliases: `delete-webhook-endpoint`, `delete_webhook_endpoint`.
+
+Effects: state-change, delete.
+
+## `bb webhook secret rotate`
+
+Admin-only: issue a new signing secret; older secrets keep signing for --previousSecretTtlHours (default 24). Prints the new secret once. Argument: <endpointId>.
+
+Legacy aliases: `rotate-webhook-secret`, `rotate_webhook_secret`.
+
+Effects: state-change.
+
+## `bb webhook endpoint test`
+
+Admin-only: send a signed webhook.test event to one endpoint. Argument: <endpointId>.
+
+Legacy aliases: `send-webhook-test-event`, `send_webhook_test_event`.
+
+Effects: state-change.
+
+## `bb webhook delivery list`
+
+List webhook deliveries.
+
+Legacy aliases: `list-webhook-deliveries`, `list_webhook_deliveries`.
+
+Effects: none.
+
+## `bb webhook delivery get`
+
+Admin-only: one webhook delivery with payload and attempts (status codes, errors, durations). Argument: <deliveryId>.
+
+Legacy aliases: `get-webhook-delivery`, `get_webhook_delivery`.
+
+Effects: none.
+
+## `bb webhook delivery replay`
+
+Admin-only: resend a finished webhook delivery with the same eventId on a fresh attempt chain. Argument: <deliveryId>.
+
+Legacy aliases: `replay-webhook-delivery`, `replay_webhook_delivery`.
+
+Effects: state-change, external-write.
+
 ## `bb inbound source list`
 
 List inbound sources.
@@ -1375,6 +1615,14 @@ Legacy aliases: `list-inbound-sources`, `list_inbound_sources`.
 
 Effects: none.
 
+## `bb inbound source count`
+
+Count Inbound Sources.
+
+Legacy aliases: `count-inbound-sources`, `count_inbound_sources`.
+
+Effects: none.
+
 ## `bb inbound source create`
 
 Create Inbound Source.
@@ -1407,6 +1655,14 @@ Legacy aliases: `list-inbound-submissions`, `list_inbound_submissions`.
 
 Effects: none.
 
+## `bb inbound submission count`
+
+Count Inbound Submissions.
+
+Legacy aliases: `count-inbound-submissions`, `count_inbound_submissions`.
+
+Effects: none.
+
 ## `bb inbound submission get`
 
 Get inbound submission.