@go-labs-sg/bb 2.19.0 → 2.23.0

package/README.md

@@ -6,22 +6,49 @@ For AI agents: bills and claims are stored as the same underlying bill records.
 
 For AI agents using this CLI: always check whether a newer `@go-labs-sg/bb` version is available before running Budget Builder commands, then update the CLI if needed so command flags and API behavior stay current.
 
-For AI agents using this CLI: run `bb auth whoami` before reading or changing Budget Builder data. The CLI displays every command regardless of the authenticated user's role, but the API authorizes each request using the API-key owner's role, resource ownership or project assignment, current workflow state, and approval assignment. See the [role-aware agent guide](./role-aware-agent-guide.md) before choosing commands.
+For AI agents using this CLI: run `bb auth whoami` before reading or changing Budget Builder data. The CLI displays every command regardless of the authenticated user's role, but the API authorizes each request using the current browser-authorized CLI user or automation API-key owner, resource ownership or project assignment, current workflow state, and approval assignment. See the [role-aware agent guide](./role-aware-agent-guide.md) before choosing commands.
 
 For AI agents using this CLI: do not execute mutations until the user explicitly confirms the exact entity, target state, and side effects. Inspect the entity first, summarize what will change and whether emails, external systems, deletions, or financial records are involved, then wait for a clear confirmation from the user. Canonical v2 mutations print an effect-aware workflow preview before one interactive `CONFIRM` prompt. Non-interactive automation must supply every applicable granular `--allow-*` flag; the CLI rejects the command before its first API call when any flag is missing.
 
 **Registry:** [`@go-labs-sg/bb`](https://www.npmjs.com/package/@go-labs-sg/bb)
 
-## Requirements
+## Runtime and installation
 
-- **Node.js** 24+ (ESM; relative imports in `dist` use `.js` extensions)
-- A Budget Builder account with any active user role
-- A **Budget Builder API key** (the same key is used for the CLI and MCP server)
+The CLI requires [Bun](https://bun.com/docs/installation) 1.4.0 or newer and a Budget Builder account with any active user role.
 
-## Install
+Check whether a compatible Bun version is already available:
+
+```bash
+bun --version
+```
+
+If Bun is missing, install it for the current operating system:
+
+**macOS (Homebrew)**
+
+```bash
+brew install oven-sh/bun/bun
+```
+
+**Windows (PowerShell)**
+
+```powershell
+powershell -c "irm bun.sh/install.ps1|iex"
+```
+
+**Linux**
+
+```bash
+curl -fsSL https://bun.com/install | bash
+```
+
+If Bun is installed but older than 1.4.0, run `bun upgrade`. Open a new terminal if the installer changes `PATH`, then verify `bun --version` again. Installation agents should skip the platform installer when Bun 1.4.0 or newer is already available.
+
+Install and verify the CLI:
 
 ```bash
 bun add --global @go-labs-sg/bb
+bb version
 ```
 
 Or run without installing:
@@ -32,33 +59,37 @@ bunx @go-labs-sg/bb <command>
 
 ## Authentication
 
-Sign in to Budget Builder and create your first key under **API Keys**. Every
-active user can manage their own keys; an admin is only required to manage a key
-for someone else.
-
-Load the key from your shell's secret manager or environment before running
-commands:
+Interactive users authorize the CLI through Budget Builder's normal Google-backed
+browser session:
 
 ```bash
-export BB_API_KEY="<your-key>"
+bb auth login
+bb auth status
+bb auth whoami
 ```
 
-Do not put the raw key in a command argument, commit it to a repository, or paste
-it into logs. The CLI redacts API-key values from its request tracing. If you use
-a local `.env`, keep it out of version control and restrict its file permissions.
+The browser always requires an explicit **Authorize CLI** action, even when it is
+already signed in. The CLI polls automatically and stores only Budget Builder-issued
+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.
 
-Once authenticated, any user can rotate or manage their own keys from the CLI:
+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
+with the commands below:
 
 ```bash
-bb auth whoami
-bb user api-key create --name "My CLI"
+bb user api-key create --name "My automation"
 bb user api-key list
 bb user api-key revoke <api-key-id>
 ```
 
-The raw key is returned only by `bb user api-key create`; copy it immediately. Listing
-keys returns metadata only. Revoking the key currently stored in `BB_API_KEY`
-will cause subsequent commands to fail until it is replaced.
+The raw key is returned only by `bb user api-key create`; copy it immediately.
+Never put it in command arguments, source control, or logs. Listing returns metadata
+only. Revoking the key currently stored in `BB_API_KEY` causes that automation
+process to fail until the environment credential is replaced or removed so the
+interactive session can be used.
 
 Admins can provision API-only service identities and manage their keys from the
 CLI. These identities are not human web accounts: `create-user` does not create
@@ -75,14 +106,14 @@ The CLI talks to `https://budget-builder.getout.events` by default. For staging
 
 ## Role-aware agent startup
 
-Every agent session that uses an API key must begin with:
+Every agent session must begin with:
 
 ```bash
 bb version
 bb auth whoami
 ```
 
-`whoami` returns the identity and database role attached to the active key inside the v2 response envelope:
+`whoami` returns the identity and database role attached to the active browser session or automation key inside the v2 response envelope:
 
 ```json
 {
@@ -142,7 +173,7 @@ bb supplier list
 
 Global options and command flags use `--key=value` or `--key value`. Run `bb help` for the canonical command catalog and `bb help --legacy` for the transition-era detailed flat-command reference.
 
-Run `bb version` before agent-driven work to record the installed package version and production API target. This is read-only and does not require `BB_API_KEY`.
+Run `bb version` before agent-driven work to record the installed package version and production API target. This is read-only and does not require authentication.
 
 **Authoritative command list:** run `bb help` or inspect the generated `command-reference.md` / `command-manifest.json`. The catalog includes every canonical route, global option, and effect classification, but does not filter by the current `whoami` role. During the handler migration, command-specific arguments retain the compatibility dispatcher's validation and are explicitly marked `legacy-passthrough` in the manifest; use `bb help --legacy` for their detailed transition reference. Version 2 uses grouped, resource-first commands such as `bb budget list` and `bb bill attachment upload`. Flat commands such as `bb list-budgets` and their MCP-style `snake_case` aliases remain available during the v2 transition, with a deprecation notice and an equivalent grouped command in help. MCP exposes a subset of the same tRPC surface; the CLI additionally includes a few procedures mainly used by the web UI.
 
@@ -181,6 +212,10 @@ New sources are registered against an existing Typeform form ID and always start
 with processing disabled in `COLLECT_ONLY`; creating a source does not call any
 external provider.
 
+Deal-lifecycle retries require Slack and Asana to succeed. Google Calendar is
+attempted afterward; a Calendar failure is logged without failing the overall
+lifecycle operation.
+
 ### Mutation safety
 
 While an estimate email is `QUEUED`, `PROCESSING`, or awaiting provider
@@ -233,6 +268,8 @@ The table below is a behavior index keyed by the compatibility dispatcher's lega
 
 Project and budget query payloads keep the Asana identities explicit: `asanaTaskId` is the Deals task GID, while `asanaProjectGid` and `asanaProjectUrl` identify the operational project created for Won delivery work.
 
+Bill, claim, and quotation mutations accept only suppliers whose approval status is `APPROVED`. An active supplier that is `PENDING_APPROVAL`, `REJECTED`, or `SUPERSEDED` must be approved before it can be used.
+
 | Area | Legacy handler labels (reference only; non-exhaustive) |
 | --- | --- |
 | **Budgets** | `list-budgets` (full payload by default; `--summary` or `--includeDetails false` for slim list), `get-budget`, `get-budget-items`, `get-budget-details`, `get-budget-categories`, `get-budget-versions`, `rename-budget-version`, `restore-budget-version`, `update-budget-status` (`ESTIMATE_ACCEPTED` requires win proof, auto-marks `PITCH` or `LOST` projects `WON`, and auto-creates an Asana Event Ops section from Prompt 5 tasks when enabled; Prompt 5 skips quantity-zero items, combines matching non-GO-internal suppliers, keeps each GO internal item separate, removes generated work that repeats another line item or group, and schedules applicable subtasks relative to the project start date; `--projectStatusOnCommercialRejection PITCH\|LOST` is required when rejecting the only accepted/closed budget on a commercial project), `mark-budget-won` (`<budgetId>` + proof file path; `PITCH` or `LOST` projects become `WON` automatically), `create-budget` / `update-budget` (`--payload`; cloned unavailable lines require `unavailableItemReviewAcknowledged: true`), `delete-budget`, `create-budget-approval` (also sends approval request emails), `create-estimate`, `send-estimate-to-contact-person` (same contact-person email workflow as web), `add-budget-items`, `update-budget-item`, `replace-budget-item`, `approve-unavailable-item-exception` (Lead/Admin), `remove-budget-item`, `reorder-budget-items`, `update-budget-item-supplier`, `mark-budget-items-not-utilized`, `restore-budget-item`, `create-placeholder-bill` (admin recovery), `create-budget-category`, `update-budget-category`, `delete-budget-category`, `update-budget-commission`, `delete-budget-commission`, `update-budget-discount`, `delete-budget-discount` (`--payload` where noted), `upload-budget-attachment` (`<budgetId>` + local file path; uses `attachment.requestBudgetAttachmentUpload` + PUT + `attachment.confirmBudgetAttachment`) |
@@ -243,7 +280,7 @@ Project and budget query payloads keep the Asana identities explicit: `asanaTask
 | **Companies & projects** | `list-companies`, `get-company`, `create-company`, `update-company` (`--payload`), `delete-company`, `list-projects`, `get-project` (its budget overview returns `totalRevenue`, calculated only from Estimate Accepted and Estimate Closed budgets), `get-project-hub-status`, `setup-project-hub`, `sync-project-hub-commercial-documents`, `create-project` (required: `--name`, `--companyId`, `--contactPersonId`, `--insideSalesId`, `--businessDevelopmentId`, `--venue`, `--startDate` as ISO datetime for project/window start; when `--asanaTaskId` is omitted, the CLI searches open Asana lead tasks in the Deals project, prompts for one of the top five matches, and resolves Slack channel fields from the selected deal card; optional `--asanaSearch`, `--pax`, `--endDate`, `--description`, `--projectManagerId`; always requests QBO project import like the web app), `update-project` (`--payload` with `dateRange.from` / `dateRange.to` for the project window; optional `projectManagerId` and `requestQboAccountantNotification` in JSON), `delete-project`, `check-project-reconciliation <id>` (runs the web app's live checks without changing status), `reconcile-project <id>` (reruns checks transactionally and marks an eligible project `RECONCILED`), `complete-project <id>` (reruns validation, marks a reconciled project `COMPLETED`, and queues QuickBooks placeholder cleanup), `import-qbo-project`, `update-project-status` (`<id>` `<status>`: `PITCH` \| `WON` \| `COMPLETED` \| `RECONCILED` \| `LOST`; close-out follows `WON` → `RECONCILED` → `COMPLETED`, and reconciliation requires every accepted/closed budget line to have an Approved/Paid bill or claim or be explicitly Not Utilized; marking `COMPLETED` queues deletion of every remaining project placeholder bill from QuickBooks; for `PITCH` → `WON` also pass a Budget Builder user `--projectManagerId` or `--projectManagerEmail`; when marking `WON` without an accepted/closed budget or proof, pass `--wonOverrideReason`) |
 | **Contacts** | `list-contacts`, `create-contact-person` (`--payload`), `update-contact-person` (`--payload`) |
 | **Suppliers & items** | `list-suppliers` (defaults to active suppliers, `--perPage 10`, sorted by `createdAt` desc; supports `--name`, `--sortBy` for scalar supplier fields, `--sortDir`, `--createdBy`, `--gstRegistered`, `--status`, `--supplierTags`, `--active false` for archived suppliers), `create-supplier` (`--payload`; when supplier status is `PENDING_APPROVAL`, also runs `supplier.createSupplierApproval` and `email.sendSupplierApprovalRequestEmail`), `update-supplier` (`--payload`; when supplier status is `PENDING_APPROVAL`, also runs `supplier.createSupplierApproval` and `email.sendSupplierApprovalRequestEmail`), `delete-suppliers` (`--ids` CSV; admin; archives/deactivates related items), `reactivate-suppliers` (`--ids` CSV; admin; reactivates related items), `create-certification` / `create-payment-method` / `create-supplier-role` / `create-supplier-tag` (`--name`), `get-supplier-details` (includes `supplierApprovalSummary` for pending approvers, superseded approvers, and the actual responder/respondedAt metadata), `get-supplier-analytics` (admin), `list-items` (`--includeQuickBooksDeactivationPending true` discovers interrupted QuickBooks deactivations for Admin retry), `create-item` (`--payload`), `update-item` (`--payload`), `archive-items` (`--ids` CSV, max 100; Budget Builder-only; open estimates retain unavailable snapshot lines for resolution), `delete-item` (admin; archives in Budget Builder and makes the item inactive in QuickBooks; blocked while an open estimate references it), `get-item`, `list-item-categories`, `create-item-category` / `update-item-category` / `delete-item-categories` (admin; `--ids` CSV for delete) |
-| **Dashboard & users** | `whoami` (current API-key owner identity and role), `list-users`, `create-user` (admin; provisions an API-only service identity with no Google sign-in; `--email`, optional `--name`, optional `--role` defaulting to `USER`), `create-api-key` (`--name`; defaults to the caller; admin-only `--userId` for another user; raw key shown once), `list-api-keys` (defaults to the caller; admin-only `--userId` for another user), `revoke-api-key` (key ID; admin-only `--userId` for another user), `get-user-performance`, `get-dashboard`, `get-monthly-metrics`, `get-system-overview`, `get-estimate-performance`, `get-financial-overview` (performance/dashboard commands are admin-only) |
+| **Dashboard & users** | `whoami` (current authenticated identity and role), `list-users`, `create-user` (admin; provisions an API-only service identity with no Google sign-in; `--email`, optional `--name`, optional `--role` defaulting to `USER`), `create-api-key` (`--name`; defaults to the caller; admin-only `--userId` for another user; raw key shown once), `list-api-keys` (defaults to the caller; admin-only `--userId` for another user), `revoke-api-key` (key ID; admin-only `--userId` for another user), `get-user-performance`, `get-dashboard`, `get-monthly-metrics`, `get-system-overview`, `get-estimate-performance`, `get-financial-overview` (performance/dashboard commands are admin-only) |
 | **Errors (admin)** | `get-recent-errors`, `get-error-metrics` |
 | **Automation (admin)** | `list-integration-operations`, `retry-integration-operation` (Resend resolution requires `--confirmExternalStateReconciled true` plus `--outboundEmailResolution ACCEPTED\|NOT_ACCEPTED_RETRY`; include `--providerMessageId` when accepted) |
 | **Historical / benchmarks** | `get-approved-budgets`, `get-budget-category-benchmarks`, `get-item-pricing-history`, `get-supplier-pricing-history` |
@@ -258,7 +295,7 @@ The CLI intentionally wraps low-level upload-request/confirm procedures into fil
 - **Legacy compatibility:** flat aliases keep their raw success JSON, `{ "error": "..." }` failures, and default action tracing during the transition
 - **Exit codes:** `0` success, `2` usage/validation/confirmation failure, `1` API/auth/network/internal failure, `130` interruption
 
-A `.env` file in the **current working directory** is loaded automatically (for `BB_API_KEY`, etc.).
+A `.env` file in the **current working directory** is loaded automatically for automation settings such as `BB_API_KEY`. Interactive browser credentials remain exclusively in `Bun.secrets`.
 
 ## Developing in this repo