@go-labs-sg/bb 2.33.2 → 2.34.0

package/README.md

@@ -12,6 +12,16 @@ 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)
 
+## 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.
+
+After reviewing a result, `bb company use --companyId <bbId>` reuses BB and resolves its QBO customer. `bb company use --quickbooksId <qboId>` imports the existing QBO name/website when BB is missing. Supply both IDs to explicitly connect two unlinked records whose names differ; existing company details are preserved. If QBO has no website, add `--website <url>` for the BB import only.
+
+The shared API rechecks existing records at submission. Canonical matches reuse records; fuzzy matches require an explicit choice or `--confirmDistinct true` to confirm a separate legal entity. Inactive companies and conflicting links require review, never implicit reactivation. QBO project/sub-customers are not company-import candidates. Provider failures are not treated as missing records.
+
+`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.
+
 ## 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

@@ -4790,10 +4790,134 @@
 		"effects": [],
 		"legacyTarget": "get-company"
 	},
+	{
+		"path": ["company", "search"],
+		"legacyAliases": ["search-existing-companies", "search_existing_companies"],
+		"summary": "Search BB and QuickBooks companies without writes. --query <name> [--page <number>].",
+		"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": "--query",
+				"description": "Company name to search in BB and QuickBooks."
+			},
+			{
+				"name": "--page",
+				"description": "Results page (eight companies per page)."
+			}
+		],
+		"argumentMode": "legacy-passthrough",
+		"effects": [],
+		"legacyTarget": "search-existing-companies"
+	},
+	{
+		"path": ["company", "use"],
+		"legacyAliases": ["use-existing-company", "use_existing_company"],
+		"summary": "Reuse a company in BB and QuickBooks, creating only its missing counterpart. Supply --companyId <bbId> and/or --quickbooksId <qboId>; both explicitly connect records with different names. --website <url> fills a missing QBO import website only. --confirmDistinct true confirms no similar record represents this entity.",
+		"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": "--companyId",
+				"description": "Existing BB company ID; combine with quickbooksId to explicitly connect both records."
+			},
+			{
+				"name": "--quickbooksId",
+				"description": "Existing QBO customer ID; alone imports or reuses its BB company."
+			},
+			{
+				"name": "--website",
+				"description": "Website only when missing from a QBO-only import."
+			},
+			{
+				"name": "--confirmDistinct",
+				"description": "Set true only when similar records do not represent this legal entity."
+			}
+		],
+		"argumentMode": "legacy-passthrough",
+		"effects": ["state-change", "external-write"],
+		"legacyTarget": "use-existing-company"
+	},
 	{
 		"path": ["company", "create"],
 		"legacyAliases": ["create-company", "create_company"],
-		"summary": "Create Company.",
+		"summary": "Create or reuse a company in BB and QuickBooks. --name <name> --website <url>. Similar names require --confirmDistinct true; inactive companies are never reactivated.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -4834,6 +4958,10 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--confirmDistinct",
+				"description": "Set true to confirm a separate legal entity despite similar names."
 			}
 		],
 		"argumentMode": "legacy-passthrough",

package/command-reference.md

@@ -769,9 +769,25 @@ Legacy aliases: `get-company`, `get_company`.
 
 Effects: none.
 
+## `bb company search`
+
+Search BB and QuickBooks companies without writes. --query <name> [--page <number>].
+
+Legacy aliases: `search-existing-companies`, `search_existing_companies`.
+
+Effects: none.
+
+## `bb company use`
+
+Reuse a company in BB and QuickBooks, creating only its missing counterpart. Supply --companyId <bbId> and/or --quickbooksId <qboId>; both explicitly connect records with different names. --website <url> fills a missing QBO import website only. --confirmDistinct true confirms no similar record represents this entity.
+
+Legacy aliases: `use-existing-company`, `use_existing_company`.
+
+Effects: state-change, external-write.
+
 ## `bb company create`
 
-Create Company.
+Create or reuse a company in BB and QuickBooks. --name <name> --website <url>. Similar names require --confirmDistinct true; inactive companies are never reactivated.
 
 Legacy aliases: `create-company`, `create_company`.
 

package/dist/index.js

@@ -22818,6 +22818,12 @@ async function createCompany(opts) {
   const result = await api2.company.createCompany.mutate(opts);
   out(result);
 }
+var searchExistingCompanies = async (query, page = 1) => {
+  out(await api2.company.searchExistingCompanies.query({ query, page }));
+};
+var reuseExistingCompany = async (input2) => {
+  out(await api2.company.useExistingCompany.mutate(input2));
+};
 async function listProjects(opts) {
   const result = await api2.project.getAllProjects.query({
     companyId: opts.companyId,
@@ -23336,6 +23342,7 @@ var mutationPrefixes = [
   "submit-",
   "sync-",
   "update-",
+  "use-existing-",
   "upload-",
   "void-"
 ];
@@ -23366,6 +23373,7 @@ var externalWriteTargets = new Set([
   "complete-project",
   "create-bill",
   "create-company",
+  "use-existing-company",
   "create-estimate",
   "create-placeholder-bill",
   "create-customer-invoice",
@@ -23463,6 +23471,12 @@ var effectsFor = (legacyTarget) => {
 };
 var titleCase = (value) => value.split("-").map((word) => `${word.slice(0, 1).toUpperCase()}${word.slice(1)}`).join(" ");
 var summaryFor = (legacyTarget) => {
+  if (legacyTarget === "search-existing-companies")
+    return "Search BB and QuickBooks companies without writes. --query <name> [--page <number>].";
+  if (legacyTarget === "use-existing-company")
+    return "Reuse a company in BB and QuickBooks, creating only its missing counterpart. Supply --companyId <bbId> and/or --quickbooksId <qboId>; both explicitly connect records with different names. --website <url> fills a missing QBO import website only. --confirmDistinct true confirms no similar record represents this entity.";
+  if (legacyTarget === "create-company")
+    return "Create or reuse a company in BB and QuickBooks. --name <name> --website <url>. Similar names require --confirmDistinct true; inactive companies are never reactivated.";
   if (legacyTarget === "preview-qbo-customer-invoice") {
     return "Preview an existing QuickBooks invoice for a BB budget using read-only QBO access. Arguments: <budgetId> <qboInvoiceId>.";
   }
@@ -23726,7 +23740,40 @@ var registry2 = [
   legacyCommand("get-supplier-details", ["supplier", "detail", "get"]),
   legacyCommand("list-companies", ["company", "list"]),
   legacyCommand("get-company", ["company", "get"]),
-  legacyCommand("create-company", ["company", "create"]),
+  legacyCommand("search-existing-companies", ["company", "search"], [], [
+    {
+      name: "--query",
+      description: "Company name to search in BB and QuickBooks."
+    },
+    {
+      name: "--page",
+      description: "Results page (eight companies per page)."
+    }
+  ]),
+  legacyCommand("use-existing-company", ["company", "use"], [], [
+    {
+      name: "--companyId",
+      description: "Existing BB company ID; combine with quickbooksId to explicitly connect both records."
+    },
+    {
+      name: "--quickbooksId",
+      description: "Existing QBO customer ID; alone imports or reuses its BB company."
+    },
+    {
+      name: "--website",
+      description: "Website only when missing from a QBO-only import."
+    },
+    {
+      name: "--confirmDistinct",
+      description: "Set true only when similar records do not represent this legal entity."
+    }
+  ]),
+  legacyCommand("create-company", ["company", "create"], [], [
+    {
+      name: "--confirmDistinct",
+      description: "Set true to confirm a separate legal entity despite similar names."
+    }
+  ]),
   legacyCommand("update-company", ["company", "update"]),
   legacyCommand("delete-company", ["company", "delete"]),
   legacyCommand("list-projects", ["project", "list"]),
@@ -24263,7 +24310,12 @@ Companies & projects
   list-companies             [--name] [--createdBy] [--active true|false] [--page] [--perPage]
     Omit --active to include both active and inactive companies.
   get-company <id>
-  create-company             --name --website <url>
+  search-existing-companies  --query <name> [--page] (BB + QuickBooks, read-only)
+  use-existing-company      --companyId <bbId> and/or --quickbooksId <qboId> [--website <url>] [--confirmDistinct true]
+    Supply both IDs to explicitly connect existing records with different names.
+    Reuses both records, creating only the missing counterpart. Website is needed only for a QBO import without one.
+  create-company             --name --website <url> [--confirmDistinct true]
+    Exact existing companies are reused. Similar names require explicit separate-entity confirmation.
   update-company             --payload '<json>'  (company.updateCompany; must include id, name, website)
   delete-company <id>
   list-projects              [--companyId] [--name] [--status] [--active true|false] [--page] [--perPage]
@@ -25651,7 +25703,39 @@ Waiting for approval\u2026
         if (!name || !website) {
           throw new Error("create-company requires --name and --website <url>");
         }
-        await createCompany({ name, website });
+        await createCompany({
+          name,
+          website,
+          confirmDistinct: parseOptionalBoolFlag(flags, "confirmDistinct")
+        });
+        break;
+      }
+      case "search-existing-companies": {
+        const query = getFlag(flags, "query");
+        if (!query)
+          throw new Error("search-existing-companies requires --query <name>");
+        await searchExistingCompanies(query, parsePositiveIntFlag(getFlag(flags, "page"), "--page"));
+        break;
+      }
+      case "use-existing-company": {
+        const companyId = getFlag(flags, "companyId");
+        const quickbooksId = getFlag(flags, "quickbooksId");
+        if (!companyId && !quickbooksId)
+          throw new Error("Supply --companyId and/or --quickbooksId");
+        if (companyId)
+          await reuseExistingCompany({
+            source: "bb",
+            companyId,
+            quickbooksId,
+            confirmDistinct: parseOptionalBoolFlag(flags, "confirmDistinct")
+          });
+        else if (quickbooksId)
+          await reuseExistingCompany({
+            source: "qbo",
+            quickbooksId,
+            website: getFlag(flags, "website"),
+            confirmDistinct: parseOptionalBoolFlag(flags, "confirmDistinct")
+          });
         break;
       }
       case "update-company": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-labs-sg/bb",
-  "version": "2.33.2",
+  "version": "2.34.0",
   "description": "Budget Builder CLI for AI agents — manage budgets, bills, claims, quotations, and customer invoices with explicit workflow previews for sensitive changes.",
   "type": "module",
   "main": "./dist/index.js",