@go-labs-sg/bb 2.45.0 → 2.46.0

package/README.md

@@ -12,6 +12,14 @@ 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)
 
+## Bill and claim list summaries
+
+`bb bill list` / `bb claim list` (legacy `list-bills` / `list-claims`) now use `bill.getList`. Lists return summary fields, `isClaimable`, `lineItemCount` and `hasPendingApproval`, plus the existing pagination, counts and metrics envelope. Filters and sorting are unchanged. They no longer return attachment, detailed line-item or approval arrays, full supplier/budget/project/company records, or detail-only payment/integration/verification metadata.
+
+**Output migration:** scripts reading those removed fields must fetch the selected bill/claim with `bb get-bill-details <billId>`. Do not fetch details for every list row unless the task actually needs them. No rich-list flag or automatic detail expansion is added. Older clients can still call the existing `bill.getAll` API.
+
+Deploy the API containing `bill.getList` before publishing this CLI; there is no automatic fallback to the old rich list. Budget-list options are unchanged by this bill/claim migration.
+
 ## 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.
@@ -63,7 +71,7 @@ See the [supplier review and rollout policy](../api/docs/supplier-edit-review.md
 
 ## Runtime and installation
 
-The same CLI package supports macOS and Windows. It requires [Bun](https://bun.com/docs/installation) 1.4.0 or newer and a Budget Builder account with any active user role. Windows users can run the commands below in native PowerShell; Bash and `export PATH=...` are not required.
+The same CLI package targets macOS, Windows, and Linux; authentication depends on the secure backend described below. It requires [Bun](https://bun.com/docs/installation) 1.4.0 or newer and a Budget Builder account with any active user role. Windows users can run the commands below in native PowerShell; Bash and `export PATH=...` are not required.
 
 Check whether a compatible Bun version is already available:
 
@@ -125,6 +133,16 @@ bb get-budget-details <budget-id> --includeInactive
 
 `--active false` lists inactive budgets only. `--active all` lists active and inactive budgets. `--includeInactive` allows the three budget/detail/item commands to read inactive history. If the authenticated identity is not an Admin, the API rejects the historical request before reading budget data. For `get-budget`, the CLI requests the budget and its line items concurrently; each API read independently enforces the same active-only default and Admin-only historical opt-in.
 
+## Secure credential storage
+
+`GO_LABS_CLI_CREDENTIAL_ACCOUNT` selects the native credential-store account for this CLI. The default is `default`, preserving existing production logins. The downloadable staging launcher sets it to `staging` so a staging login does not replace the production login; keep the same account value for login and subsequent commands. The launcher also sets `GO_LABS_CLI_SKIP_DOTENV=1`, which skips the CLI's explicit current-directory `.env` load while leaving normal production behavior unchanged.
+
+Browser sessions use `Bun.secrets`: macOS Keychain, Windows Credential Manager, or Linux Secret Service. Linux requires libsecret, a reachable user D-Bus session, and an unlocked Secret Service collection. SSH and containers must provide those native prerequisites themselves; `--no-browser` only lets approval happen on another device. Denied D-Bus access is a host permissions/session issue, not something the CLI bypasses.
+
+Before requesting approval, login verifies write/read/delete capability with a unique non-secret probe. Native operations have a 10-second process deadline and sanitized errors. Issued credentials are read back and verified; failed persistence attempts remote revocation and reports local and remote cleanup separately. There is no plaintext fallback or external credential-helper configuration.
+
+See the [shared authentication contract](../../cli-auth/README.md) for recovery and verification limits.
+
 ## Authentication
 
 Interactive users authorize the CLI through Budget Builder's normal Google-backed
@@ -142,7 +160,7 @@ 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.
 
-Credentials use macOS Keychain or Windows Credential Manager, not plaintext files.
+Credentials use macOS Keychain, Windows Credential Manager, or Linux Secret Service, not plaintext files.
 The per-user lock directory contains only random ownership markers used to serialize
 login, refresh, and logout. macOS/Linux enforce owner-only POSIX permissions there;
 Windows uses its native filesystem access controls rather than POSIX mode checks.
@@ -164,6 +182,16 @@ 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.
 
+`bb user api-key list` and the `mcpApiKey.list` API retain the nullable
+`lastUsedAt` field for compatibility (an ISO timestamp in CLI JSON). Interpret
+only its calendar date in `Asia/Singapore` (UTC+08:00): it records the first
+successful usage touch of that day, **not the most recent request time**.
+Null means no use has been recorded; pre-rollout values may represent any use
+on their recorded day. Do not use the time portion for inactivity timeouts,
+minute-level mutation attribution, or request auditing. Authentication still
+reads the key and current user ban status on every request; revocation does
+not cancel requests already in flight.
+
 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
 or link a Google OAuth account, so the resulting user cannot sign in with Google.
@@ -440,6 +468,23 @@ bb quotation create --payload '{
 Use the same fields for `bb quotation update --payload`, adding the existing quotation `"id": "<quotation-id>"`. Read the quotation and its budget before updating so the IDs and current status are confirmed. The example's subtotal is S$1,200, GST is S$0, and total is S$1,200; those values are illustrative only and contain no live resource IDs.
 
 
+### Budget version history (pagination contract change)
+
+`bb budget version list <budgetId>` now returns **one page**, not the full history array. The normal CLI envelope contains `data: { versions, nextCursor }`; legacy aliases `get-budget-versions` and `get_budget_versions` return that page object directly. Update scripts that previously iterated the top-level array to iterate `versions` and explicitly request older pages when needed.
+
+```bash
+bb budget version list <budgetId>
+bb budget version list <budgetId> --limit 20 --cursor <nextCursor>
+bb budget version list <budgetId> --all
+```
+
+- Default page size: 20; `--limit` accepts integers from 1 to 50.
+- `nextCursor: null` means no older visible versions. Otherwise pass it as `--cursor` for the next page; do not automatically drain history for ordinary browsing.
+- `--all` explicitly collects all visible history through sequential bounded requests. It cannot be combined with `--cursor`; `--limit` controls each request's size. It can still be expensive and retains the complete result in memory. A failed page aborts without emitting a successful partial export.
+- Pages preserve newest-first `createdAt`/`id` ordering, role visibility, and creator/version-group metadata. They are not a point-in-time database snapshot; versions added after traversal starts require a fresh first-page read, and concurrent changes to visibility can affect traversal.
+
+The backend must expose `budgetVersion.getBudgetVersionsPage`. The legacy unbounded tRPC `getBudgetVersions` remains available but deprecated for external compatibility; unknown external clients are not silently capped. Removing that endpoint requires a separate usage/compatibility review. This change does not publish the CLI, deploy the backend/MCP server, delete audit snapshots, or establish measured RU savings.
+
 ### Link an existing QuickBooks invoice
 
 **Release status:** these CLI commands are pending release. The repository package version remains `2.31.0`; that version number alone does not establish that a published CLI contains them. Check `bb help` for `customer-invoice preview-qbo` and `customer-invoice import-qbo` after the normal CLI release. This code delivery does not publish the CLI, deploy the API, or perform a production import. The backend must expose `customerInvoice.previewExistingInvoice` and `customerInvoice.linkExistingInvoice` (implemented in PR #1067).

package/command-manifest.json

@@ -606,6 +606,18 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--limit <1-50>",
+				"description": "Versions per page (default 20). Returns versions and nextCursor, not a full-history array."
+			},
+			{
+				"name": "--cursor <versionId>",
+				"description": "Load the next page using the previous nextCursor; null means complete."
+			},
+			{
+				"name": "--all",
+				"description": "Explicitly fetch all visible history in bounded pages; cannot combine with --cursor. May be expensive."
 			}
 		],
 		"argumentMode": "legacy-passthrough",