@go-labs-sg/bb 1.15.0 → 1.17.0

package/README.md

@@ -37,6 +37,20 @@ export BB_API_KEY=<your-key>
 
 Create or revoke keys in the web app: **Goracle → API Keys** (MCP API keys).
 
+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.
+
+```bash
+bb create-user --email agent@example.com --name "Budget Agent" --role USER
+bb create-api-key --userId <user-id> --name "Budget Agent CLI"
+bb list-api-keys --userId <user-id>
+bb revoke-api-key <api-key-id> --userId <user-id>
+```
+
+The raw key is returned only by `create-api-key`; copy it immediately. Listing
+keys returns metadata only.
+
 The CLI talks to the production API: `https://budget-builder.getout.events`.
 
 ## Usage
@@ -72,10 +86,10 @@ Global options and flags use `--key=value` or `--key value` (see `bb help`).
 | **Bills / claims** | `list-bills` (`--isClaimable false` for bills, `--isClaimable true` for claims, omit for both), `list-claims` (claims only), `create-bill` (`--payload`; set `isClaimable=false` for a bill or `isClaimable=true` for a claim; non-legacy supplier bills from 1 Jul 2026 00:00 SGT require approved quotation coverage), `update-bill` (`--payload`), `delete-bill`, `create-bill-approval` (also sends approval request emails), `update-bill-status`, `patch-bill-payment` (PAID bills: `--paymentTrackingUrl`, `--paymentReference`, `--quickbooksBillId`, `--paymentDate` ISO; clear with `--clearPaymentTrackingUrl` / `--clearPaymentReference` / `--clearQuickbooksBillId` / `--clearPaymentDate` `true`), `patch-bill-invoice-number`, `get-bill-attachments`, `upload-bill-attachment` (`<billId>` + local path), `get-bill-details` |
 | **Quotations** | `list-quotations`, `get-quotation`, `upload-quotation-attachment` (`<projectId>` + local PDF path; returns attachment JSON for payload use), `create-quotation` (`--payload` for `quotation.createDraft`), `submit-quotation`, `approve-quotation`, `reject-quotation`, `download-quotation-pdf` (`original`, `staff`, or `final`) |
 | **Approvals** | `list-approvals` / `get-pending-approvals` (`--type budget\|supplier\|bill\|quotation\|all`), `approve-bill` / `reject-bill` (send reply email), `approve-budget` / `reject-budget` (send reply email), `approve-supplier` / `reject-supplier` (send reply email), `approve-quotation` / `reject-quotation` |
-| **Companies & projects** | `list-companies`, `get-company`, `create-company`, `update-company` (`--payload`), `delete-company`, `list-projects`, `get-project`, `create-project` (required: `--name`, `--companyId`, `--contactPersonId`, `--insideSalesId`, `--businessDevelopmentId`, `--venue`, `--asanaTaskId`, `--slackChannelId`, `--slackChannelUrl`, `--slackChannelName`, `--startDate` as ISO datetime for project/window start; optional `--pax`; optional `--endDate`; optional `--description`; always requests QBO project import like the web app), `update-project` (`--payload` with `dateRange.from` / `dateRange.to` for the project window; optional `requestQboAccountantNotification` in JSON), `delete-project`, `update-project-status` (`<id>` `<status>`: `PITCH` \| `WON` \| `COMPLETED` \| `LOST`; for `PITCH` → `WON` also pass `--projectManagerId` or `--projectManagerName`; when marking `WON` without an accepted/closed budget or proof, pass `--wonOverrideReason`) |
+| **Companies & projects** | `list-companies`, `get-company`, `create-company`, `update-company` (`--payload`), `delete-company`, `list-projects`, `get-project`, `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`; always requests QBO project import like the web app), `update-project` (`--payload` with `dateRange.from` / `dateRange.to` for the project window; optional `requestQboAccountantNotification` in JSON), `delete-project`, `update-project-status` (`<id>` `<status>`: `PITCH` \| `WON` \| `COMPLETED` \| `LOST`; for `PITCH` → `WON` also pass `--projectManagerId` or `--projectManagerName`; 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`, `list-items`, `create-item` (`--payload`), `update-item` (`--payload`), `delete-item`, `get-item`, `list-item-categories`, `create-item-category`, `update-item-category`, `delete-item-categories` (`--ids` CSV; admin) |
-| **Dashboard & users** | `list-users`, `get-user-performance`, `get-dashboard`, `get-monthly-metrics`, `get-system-overview`, `get-estimate-performance`, `get-financial-overview` |
+| **Dashboard & users** | `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` (admin; `--userId`, `--name`; raw key shown once), `list-api-keys` (admin; optional `--userId`), `revoke-api-key` (admin; key ID plus `--userId` for another user's key), `get-user-performance`, `get-dashboard`, `get-monthly-metrics`, `get-system-overview`, `get-estimate-performance`, `get-financial-overview` |
 | **Errors** | `get-recent-errors`, `get-error-metrics` |
 | **Historical / benchmarks** | `get-approved-budgets`, `get-budget-category-benchmarks`, `get-item-pricing-history`, `get-supplier-pricing-history` |
 

package/dist/api-client.js

@@ -8,10 +8,20 @@ function getAuthHeader() {
         return undefined;
     return `Bearer ${key.trim()}`;
 }
+const containsRawApiKey = (value, seen = new WeakSet()) => {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if (seen.has(value))
+        return false;
+    seen.add(value);
+    return Object.entries(value).some(([key, nestedValue]) => (key.toLowerCase() === "apikey" && typeof nestedValue === "string") ||
+        containsRawApiKey(nestedValue, seen));
+};
 export const api = createTRPCProxyClient({
     links: [
         loggerLink({
-            enabled: () => shouldLogCliActions(),
+            enabled: (opts) => shouldLogCliActions() &&
+                !(opts.direction === "down" && containsRawApiKey(opts.result)),
             colorMode: "ansi",
             withContext: false,
             // tRPC defaults use console.log for requests; stderr keeps stdout JSON-safe for pipes.

package/dist/commands.js

@@ -13,17 +13,200 @@ const BUDGET = "BUDGET";
 const BILL = "BILL";
 const SUPPLIER = "SUPPLIER";
 const QUOTATION = "QUOTATION";
+const ASANA_WON_LOST_SECTION_GIDS = new Set([
+    "1211678338364908",
+    "1211678338364907",
+]);
+const MAX_ASANA_LEAD_CANDIDATES = 5;
+const ASANA_SEARCH_DETAIL_LIMIT = 15;
 function isPendingRequest(n) {
     return n.notificationType === "request" && n.status === "PENDING_APPROVAL";
 }
 const out = (data) => {
     console.log(JSON.stringify(data, null, 2));
 };
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const stringField = (record, key) => {
+    const value = record[key];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+};
+const asanaSectionsForTask = (task) => {
+    if (!isRecord(task) || !Array.isArray(task.memberships))
+        return [];
+    return task.memberships.flatMap((membership) => {
+        if (!isRecord(membership) || !isRecord(membership.section))
+            return [];
+        return [
+            {
+                gid: stringField(membership.section, "gid"),
+                name: stringField(membership.section, "name"),
+            },
+        ];
+    });
+};
+const isWonOrLostAsanaTask = (task) => asanaSectionsForTask(task).some((section) => {
+    if (section.gid && ASANA_WON_LOST_SECTION_GIDS.has(section.gid)) {
+        return true;
+    }
+    const name = section.name?.trim().toLowerCase();
+    return Boolean(name && /\b(won|lost)\b/.test(name));
+});
+const asanaCandidateFromTask = (task, details) => {
+    const source = details ?? task;
+    const sourceRecord = isRecord(source) ? source : undefined;
+    const gid = (sourceRecord ? stringField(sourceRecord, "gid") : undefined) ?? task.gid;
+    const name = (sourceRecord ? stringField(sourceRecord, "name") : undefined) ??
+        task.name ??
+        gid;
+    if (!gid || isWonOrLostAsanaTask(source))
+        return null;
+    return {
+        gid,
+        name,
+        modifiedAt: (sourceRecord ? stringField(sourceRecord, "modified_at") : undefined) ??
+            task.modified_at,
+        createdAt: (sourceRecord ? stringField(sourceRecord, "created_at") : undefined) ??
+            task.created_at,
+        sections: asanaSectionsForTask(source),
+    };
+};
+const uniqueSearchQueries = (...queries) => {
+    const seen = new Set();
+    const unique = [];
+    for (const query of queries) {
+        const normalized = query?.trim() ?? "";
+        if (!normalized)
+            continue;
+        const key = normalized.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        unique.push(normalized);
+    }
+    return unique;
+};
+const searchOpenAsanaLeadCandidates = async ({ projectName, searchQuery, }) => {
+    const queries = uniqueSearchQueries(projectName, searchQuery);
+    const candidates = [];
+    const seenTaskIds = new Set();
+    for (const query of queries) {
+        const results = await api.asana.searchTasks.query({ query });
+        const tasks = results.data.slice(0, ASANA_SEARCH_DETAIL_LIMIT);
+        const detailsByTaskId = new Map();
+        await Promise.all(tasks.map(async (task) => {
+            if (!task.gid)
+                return;
+            try {
+                const details = await api.asana.getTaskById.query({ id: task.gid });
+                detailsByTaskId.set(task.gid, details.data);
+            }
+            catch {
+                // Keep the compact search result if detail lookup fails for one task.
+            }
+        }));
+        for (const task of tasks) {
+            if (!task.gid || seenTaskIds.has(task.gid))
+                continue;
+            const candidate = asanaCandidateFromTask(task, detailsByTaskId.get(task.gid));
+            if (!candidate)
+                continue;
+            seenTaskIds.add(candidate.gid);
+            candidates.push(candidate);
+            if (candidates.length >= MAX_ASANA_LEAD_CANDIDATES)
+                return candidates;
+        }
+    }
+    return candidates;
+};
+const formatAsanaCandidateMetadata = (candidate) => {
+    const sectionText = candidate.sections
+        .map((section) => section.name ?? section.gid)
+        .filter(Boolean)
+        .join(", ") || "stage unavailable";
+    const dateText = candidate.modifiedAt
+        ? `modified ${new Date(candidate.modifiedAt).toISOString()}`
+        : candidate.createdAt
+            ? `created ${new Date(candidate.createdAt).toISOString()}`
+            : "date unavailable";
+    return `${sectionText}; ${dateText}; ${candidate.gid}`;
+};
+const promptForAsanaLeadCandidate = async (candidates) => {
+    if (candidates.length === 0) {
+        throw new Error("No open Asana lead tasks were found in the Deals project. Pass --asanaTaskId explicitly or update the Deals project first.");
+    }
+    if (!process.stdin.isTTY || !process.stderr.isTTY) {
+        throw new Error("create-project requires --asanaTaskId in non-interactive runs. Interactive runs can omit it to choose from the top Asana lead task matches.");
+    }
+    console.error("Select the Asana lead task to link to this project:");
+    candidates.forEach((candidate, index) => {
+        console.error(`${index + 1}. ${candidate.name} (${formatAsanaCandidateMetadata(candidate)})`);
+    });
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    try {
+        while (true) {
+            const answer = await rl.question(`Choose 1-${candidates.length}, or q to abort: `);
+            const trimmed = answer.trim().toLowerCase();
+            if (trimmed === "q" || trimmed === "quit") {
+                throw new Error("Aborted.");
+            }
+            const selected = Number.parseInt(trimmed, 10);
+            if (Number.isInteger(selected) &&
+                selected >= 1 &&
+                selected <= candidates.length) {
+                const candidate = candidates[selected - 1];
+                if (candidate)
+                    return candidate;
+            }
+            console.error(`Enter a number from 1 to ${candidates.length}.`);
+        }
+    }
+    finally {
+        rl.close();
+    }
+};
+const resolveAsanaDealSlackChannel = async (asanaTaskId) => {
+    const result = await api.asana.getDealSlackChannel.query({ id: asanaTaskId });
+    if (result.status !== "resolved") {
+        throw new Error(result.message);
+    }
+    console.error(`Resolved Slack channel from Asana deal: #${result.channel.slackChannelName} (${result.channel.slackChannelId})`);
+    return result.channel;
+};
+const resolveCreateProjectLinks = async (opts) => {
+    const asanaTaskId = opts.asanaTaskId?.trim() ||
+        (await promptForAsanaLeadCandidate(await searchOpenAsanaLeadCandidates({
+            projectName: opts.name,
+            searchQuery: opts.asanaSearch,
+        }))).gid;
+    const hasCompleteManualSlackChannel = Boolean(opts.slackChannelId && opts.slackChannelUrl && opts.slackChannelName);
+    if (hasCompleteManualSlackChannel) {
+        return {
+            asanaTaskId,
+            slackChannelId: opts.slackChannelId,
+            slackChannelUrl: opts.slackChannelUrl,
+            slackChannelName: opts.slackChannelName,
+        };
+    }
+    const slackChannel = await resolveAsanaDealSlackChannel(asanaTaskId);
+    return {
+        asanaTaskId,
+        ...slackChannel,
+    };
+};
 const combineDateAndTime = (day, time) => {
     const d = new Date(day);
     d.setHours(time.getHours(), time.getMinutes(), time.getSeconds(), 0);
     return d;
 };
+const formatOptionalProjectPaxInput = (pax) => {
+    if (typeof pax !== "number" || !Number.isFinite(pax) || pax <= 0) {
+        return "";
+    }
+    return String(pax);
+};
 /** Extension-based MIME, like browser `File.type` when the OS provides it */
 const contentTypeHeaderForFileName = (fileName) => {
     const ct = contentType(fileName);
@@ -139,6 +322,9 @@ export async function updateBudgetStatus(budgetId, status, opts) {
     const result = await api.budget.updateBudgetStatus.mutate({
         id: budgetId,
         status,
+        ...(opts?.projectManagerId !== undefined && {
+            projectManagerId: opts.projectManagerId,
+        }),
         ...(opts?.markProjectWon !== undefined && {
             markProjectWon: opts.markProjectWon,
         }),
@@ -200,7 +386,7 @@ const runBudgetPreflight = async (budgetId, preflight) => {
             insideSalesId: project.insideSalesId ?? "",
             businessDevelopmentId: project.businessDevelopmentId ?? "",
             venue: project.venue ?? "",
-            pax: String(project.pax ?? ""),
+            pax: formatOptionalProjectPaxInput(project.pax),
             ...(project.slackChannelId &&
                 project.slackChannelUrl &&
                 project.slackChannelName
@@ -403,7 +589,11 @@ export async function getBillAttachments(id) {
     const result = await api.bill.getAttachments.query({ id });
     out(result);
 }
-export async function uploadBillAttachmentFromPath(billId, filePath) {
+export async function uploadBillAttachmentFromPath(billId, filePath, type = "BILL") {
+    const confirmed = await uploadSingleBillAttachmentFromPath(billId, filePath, type);
+    out(confirmed);
+}
+const uploadSingleBillAttachmentFromPath = async (billId, filePath, type = "BILL") => {
     const buf = await readFile(filePath);
     const fileName = basename(filePath);
     const size = buf.byteLength;
@@ -420,13 +610,51 @@ export async function uploadBillAttachmentFromPath(billId, filePath) {
     if (!res.ok) {
         throw new Error(`S3 upload failed: HTTP ${res.status} ${(await res.text()).slice(0, 500)}`);
     }
-    const confirmed = await api.attachment.confirmBillAttachment.mutate({
+    return await api.attachment.confirmBillAttachment.mutate({
         billId,
         key,
         name: fileName,
         size,
+        type,
+    });
+};
+export async function uploadBillAttachmentsFromPaths(billId, filePaths, type = "BILL") {
+    if (filePaths.length === 0) {
+        throw new Error("At least one bill attachment file path is required");
+    }
+    const results = [];
+    for (const filePath of filePaths) {
+        results.push(await uploadSingleBillAttachmentFromPath(billId, filePath, type));
+    }
+    out({
+        success: true,
+        billId,
+        type,
+        count: results.length,
+        attachments: results.map((result) => result.attachment),
+        results,
+    });
+}
+export async function uploadBillDocumentsFromPaths({ billId, invoicePaths = [], paymentProofPaths = [], }) {
+    if (invoicePaths.length === 0 && paymentProofPaths.length === 0) {
+        throw new Error("At least one invoice or payment proof file path is required");
+    }
+    const invoiceResults = [];
+    for (const filePath of invoicePaths) {
+        invoiceResults.push(await uploadSingleBillAttachmentFromPath(billId, filePath, "BILL"));
+    }
+    const paymentProofResults = [];
+    for (const filePath of paymentProofPaths) {
+        paymentProofResults.push(await uploadSingleBillAttachmentFromPath(billId, filePath, "BILL_PAYMENT_PROOF"));
+    }
+    out({
+        success: true,
+        billId,
+        count: invoiceResults.length + paymentProofResults.length,
+        invoiceAttachments: invoiceResults.map((result) => result.attachment),
+        paymentProofAttachments: paymentProofResults.map((result) => result.attachment),
+        results: [...invoiceResults, ...paymentProofResults],
     });
-    out(confirmed);
 }
 export async function uploadQuotationAttachmentFromPath(projectId, filePath) {
     const buf = await readFile(filePath);
@@ -513,6 +741,9 @@ export async function uploadBudgetWinProofFromPath(budgetId, filePath, opts) {
     const result = await api.budget.updateBudgetStatus.mutate({
         id: budgetId,
         status: "ESTIMATE_ACCEPTED",
+        ...(opts?.projectManagerId !== undefined && {
+            projectManagerId: opts.projectManagerId,
+        }),
         ...(opts?.markProjectWon !== undefined && {
             markProjectWon: opts.markProjectWon,
         }),
@@ -1220,6 +1451,14 @@ export async function getProject(id) {
     out({ project, budgetsOverview, billsOverview });
 }
 export async function createProject(opts) {
+    const links = await resolveCreateProjectLinks({
+        name: opts.name,
+        asanaTaskId: opts.asanaTaskId,
+        asanaSearch: opts.asanaSearch,
+        slackChannelId: opts.slackChannelId,
+        slackChannelUrl: opts.slackChannelUrl,
+        slackChannelName: opts.slackChannelName,
+    });
     const result = await api.project.createProject.mutate({
         name: opts.name,
         description: opts.description,
@@ -1229,10 +1468,10 @@ export async function createProject(opts) {
         businessDevelopmentId: opts.businessDevelopmentId,
         venue: opts.venue,
         pax: opts.pax,
-        asanaTaskId: opts.asanaTaskId,
-        slackChannelId: opts.slackChannelId,
-        slackChannelUrl: opts.slackChannelUrl,
-        slackChannelName: opts.slackChannelName,
+        asanaTaskId: links.asanaTaskId,
+        slackChannelId: links.slackChannelId,
+        slackChannelUrl: links.slackChannelUrl,
+        slackChannelName: links.slackChannelName,
         dateRange: {
             from: new Date(opts.startDate),
             to: opts.endDate ? new Date(opts.endDate) : undefined,
@@ -1298,6 +1537,22 @@ export async function getSupplierAnalytics(opts) {
     out(result);
 }
 // --- Dashboard / analytics ---
+export async function createUser(input) {
+    const user = await api.user.create.mutate(input);
+    out(user);
+}
+export async function createApiKeyForUser(input) {
+    const apiKey = await api.mcpApiKey.create.mutate(input);
+    out(apiKey);
+}
+export async function listApiKeysForUser(input) {
+    const apiKeys = await api.mcpApiKey.list.query(input);
+    out(apiKeys);
+}
+export async function revokeApiKeyForUser(input) {
+    const result = await api.mcpApiKey.revoke.mutate(input);
+    out(result);
+}
 export async function listUsers() {
     const users = await api.user.getAllUsers.query();
     out(users);

package/dist/index.js

@@ -2,9 +2,9 @@
 import "./load-env.js";
 import { requireApiKey } from "./api-client.js";
 import { consumeCliQuietFlags, logCliAction, sanitizeFlagsForTrace, setCliQuiet, shouldLogCliActions, } from "./cli-trace.js";
-import { addBudgetItems, approveBill, approveBudget, approveQuotation, approveSupplier, createBillApproval, createBillFromPayload, createBudgetApproval, createBudgetCategory, createBudgetFromPayload, createCompany, createContactPersonFromPayload, createEstimate, createItemCategory, createItemFromPayload, createProject, createQuotationFromPayload, createSupplierCertification, createSupplierFromPayload, createSupplierPaymentMethod, createSupplierRoleOption, createSupplierTagOption, deleteBillById, deleteBudgetById, deleteBudgetCategory, deleteCompanyById, deleteItemById, deleteItemCategoriesByIds, deleteProjectById, deleteSuppliersByIds, downloadQuotationPdf, getApprovedBudgets, getBillAttachments, getBillDetails, getBudget, getBudgetCategories, getBudgetCategoryBenchmarks, getBudgetDetails, getBudgetItemsOnly, getBudgetVersions, getCompany, getDashboard, getErrorMetrics, getEstimatePerformance, getFinancialOverview, getItem, getItemPricingHistory, getMonthlyMetrics, getProject, getQuotationDetails, getRecentErrors, getSupplierAnalytics, getSupplierDetails, getSupplierPricingHistory, getSystemOverview, getUserPerformance, listApprovals, listBills, listBudgets, listCompanies, listContacts, listItemCategories, listItems, listProjects, listQuotations, listSuppliers, listUsers, markBudgetWonWithProof, patchBillInvoiceNumber, patchBillPayment, reactivateSuppliersByIds, rejectBill, rejectBudget, rejectQuotation, rejectSupplier, removeBudgetItem, reorderBudgetItemsCli, submitQuotation, updateBillFromPayload, updateBillStatus, updateBudgetCategory, updateBudgetCommissionFromPayload, updateBudgetDiscountFromPayload, updateBudgetFromPayload, updateBudgetItem, updateBudgetItemSupplierCli, updateBudgetStatus, updateCompanyFromPayload, updateContactPersonFromPayload, updateItemCategory, updateItemFromPayload, updateProjectFromPayload, updateProjectStatus, updateSupplierFromPayload, uploadBillAttachmentFromPath, uploadBudgetAttachmentFromPath, uploadQuotationAttachmentFromPath, } from "./commands.js";
+import { addBudgetItems, approveBill, approveBudget, approveQuotation, approveSupplier, createApiKeyForUser, createBillApproval, createBillFromPayload, createBudgetApproval, createBudgetCategory, createBudgetFromPayload, createCompany, createContactPersonFromPayload, createEstimate, createItemCategory, createItemFromPayload, createProject, createQuotationFromPayload, createSupplierCertification, createSupplierFromPayload, createSupplierPaymentMethod, createSupplierRoleOption, createSupplierTagOption, createUser, deleteBillById, deleteBudgetById, deleteBudgetCategory, deleteCompanyById, deleteItemById, deleteItemCategoriesByIds, deleteProjectById, deleteSuppliersByIds, downloadQuotationPdf, getApprovedBudgets, getBillAttachments, getBillDetails, getBudget, getBudgetCategories, getBudgetCategoryBenchmarks, getBudgetDetails, getBudgetItemsOnly, getBudgetVersions, getCompany, getDashboard, getErrorMetrics, getEstimatePerformance, getFinancialOverview, getItem, getItemPricingHistory, getMonthlyMetrics, getProject, getQuotationDetails, getRecentErrors, getSupplierAnalytics, getSupplierDetails, getSupplierPricingHistory, getSystemOverview, getUserPerformance, listApiKeysForUser, listApprovals, listBills, listBudgets, listCompanies, listContacts, listItemCategories, listItems, listProjects, listQuotations, listSuppliers, listUsers, markBudgetWonWithProof, patchBillInvoiceNumber, patchBillPayment, reactivateSuppliersByIds, rejectBill, rejectBudget, rejectQuotation, rejectSupplier, removeBudgetItem, reorderBudgetItemsCli, revokeApiKeyForUser, submitQuotation, updateBillFromPayload, updateBillStatus, updateBudgetCategory, updateBudgetCommissionFromPayload, updateBudgetDiscountFromPayload, updateBudgetFromPayload, updateBudgetItem, updateBudgetItemSupplierCli, updateBudgetStatus, updateCompanyFromPayload, updateContactPersonFromPayload, updateItemCategory, updateItemFromPayload, updateProjectFromPayload, updateProjectStatus, updateSupplierFromPayload, uploadBillAttachmentFromPath, uploadBillAttachmentsFromPaths, uploadBillDocumentsFromPaths, uploadBudgetAttachmentFromPath, uploadQuotationAttachmentFromPath, } from "./commands.js";
 import { getFlag, parseArgs } from "./parse-args.js";
-import { billStatusesForUpdateHelp, budgetStatusesForHelp, isBudgetStatusUpdate, parseApprovalTypeFlag, parseBillStatusForUpdate, parseCommaSeparatedBillStatuses, parseCommaSeparatedBudgetStatuses, parseCommaSeparatedIds, parseCommaSeparatedSupplierStatuses, parseOptionalBillListSortBy, parseOptionalBillListSortDir, parseOptionalDashboardRole, parseOptionalDeals, parseOptionalErrorSeverity, parseOptionalErrorStatus, parseOptionalExtendedProjectStatus, parseOptionalFinancialRole, parseOptionalSupplierAnalyticsTimeFrame, parseOptionalTimeFrame, parseProjectStatusForUpdate, projectStatusesForHelp, } from "./parse-cli-enums.js";
+import { billStatusesForUpdateHelp, budgetStatusesForHelp, isBudgetStatusUpdate, parseApprovalTypeFlag, parseBillStatusForUpdate, parseCommaSeparatedBillStatuses, parseCommaSeparatedBudgetStatuses, parseCommaSeparatedIds, parseCommaSeparatedSupplierStatuses, parseOptionalBillListSortBy, parseOptionalBillListSortDir, parseOptionalDashboardRole, parseOptionalDeals, parseOptionalErrorSeverity, parseOptionalErrorStatus, parseOptionalExtendedProjectStatus, parseOptionalFinancialRole, parseOptionalSupplierAnalyticsTimeFrame, parseOptionalTimeFrame, parseProjectStatusForUpdate, parseUserRole, projectStatusesForHelp, userRolesForHelp, } from "./parse-cli-enums.js";
 import { parseJsonFlag, parseOptionalNumber as parseOptNum, } from "./parse-json-flag.js";
 function parsePositiveIntFlag(value, flagName) {
     if (value === undefined)
@@ -133,12 +133,12 @@ Budgets
   get-budget-details <id>    Full detail (margins, suppliers, etc.)
   get-budget-categories
   get-budget-versions <budgetId>
-  update-budget-status <id> <status> [--markProjectWon true|false] [--projectStatusOnCommercialRejection PITCH|LOST]
+  update-budget-status <id> <status> [--projectManagerId <id>] [--markProjectWon true|false] [--projectStatusOnCommercialRejection PITCH|LOST]
     Budget-changing commands require interactive "yes" confirmation when the current budget is ESTIMATE_CREATED, ESTIMATE_SENT, ESTIMATE_ACCEPTED, ESTIMATE_REJECTED, or ESTIMATE_CLOSED.
-    ESTIMATE_ACCEPTED requires win proof, auto-marks PITCH or LOST projects WON, and auto-creates the Asana project/section when enabled.
+    ESTIMATE_ACCEPTED requires win proof, auto-marks PITCH or LOST projects WON, requires --projectManagerId when the project has no PM, and auto-creates the Asana project/section when enabled.
     ESTIMATE_REJECTED requires --projectStatusOnCommercialRejection when rejecting the only accepted/closed budget on a commercial project.
     status: ${budgetStatusesForHelp.join(", ")}
-  mark-budget-won <budgetId> <filePath> [--markProjectWon true|false]   Upload signed quote/PO proof and set status to ESTIMATE_ACCEPTED; PITCH or LOST projects become WON automatically
+  mark-budget-won <budgetId> <filePath> [--projectManagerId <id>] [--markProjectWon true|false]   Upload signed quote/PO proof and set status to ESTIMATE_ACCEPTED; PITCH or LOST projects become WON automatically and require PM when none is assigned
   create-budget              --payload '<json>'  (budget.createBudget; Asana deal card is on the project)
   update-budget              --payload '<json>'  (budget.updateBudget; must include id)
   delete-budget <budgetId>
@@ -171,7 +171,9 @@ Bills
     Clear a field: --clearPaymentTrackingUrl true | --clearPaymentReference true | --clearQuickbooksBillId true | --clearPaymentDate true
   patch-bill-invoice-number <billId> <invoiceNumber>
   get-bill-attachments <billId>
-  upload-bill-attachment <billId> <filePath>   Presigned S3 upload + confirm (same flow as web UI)
+  upload-bill-attachment <billId> <filePath...> [--file <path>] [--files <csv>]   Attach invoice/supporting files as BILL attachments to any bill status, including PAID bills
+  attach-bill-payment-receipt <billId> <filePath...> [--file <path>] [--files <csv>]   Attach Wise/payment-proof PDFs as BILL_PAYMENT_PROOF attachments
+  attach-bill-documents <billId> [--invoice <path>] [--invoices <csv>] [--paymentProof|--payment-proof|--proof <path>] [--paymentProofs|--payment-proofs|--proofs <csv>]   Attach invoice and/or payment proof files with separate BB attachment types
   get-bill-details <billId>
 
 Quotations
@@ -203,7 +205,7 @@ Companies & projects
   list-projects              [--companyId] [--name] [--status] [--active true|false] [--page] [--perPage]
     Omit --active to include both active and inactive projects.
   get-project <id>
-  create-project             --name --companyId --contactPersonId --insideSalesId --businessDevelopmentId --venue --asanaTaskId --slackChannelId --slackChannelUrl --slackChannelName --startDate <ISO> [--pax] [--endDate <ISO>] [--description]
+  create-project             --name --companyId --contactPersonId --insideSalesId --businessDevelopmentId --venue --startDate <ISO> [--asanaTaskId] [--asanaSearch <text>] [--slackChannelId --slackChannelUrl --slackChannelName] [--pax] [--endDate <ISO>] [--description]
   update-project             --payload '<json>'  (project.updateProject; optional requestQboAccountantNotification; default notify like web)
   delete-project <id>
   update-project-status <id> <status> [--projectManagerId <id>] [--projectManagerName <name>] [--wonOverrideReason <text>]
@@ -241,6 +243,10 @@ Suppliers & items
 
 Dashboard & users
   list-users
+  create-user                --email <email> [--name <name>] [--role ${userRolesForHelp.join("|")}]  (admin; API-only service identity with no Google sign-in)
+  create-api-key             --userId <userId> --name <label>  (admin; raw key is shown once)
+  list-api-keys              [--userId <userId>]  (admin; defaults to the caller)
+  revoke-api-key <apiKeyId>  [--userId <userId>]  (admin; --userId is required for another user's key)
   get-user-performance       [--userId]
   get-dashboard              [--userId] [--role BD|CREATOR|INSIDE_SALES|ALL] [--deals ALL|SUCCESSFUL|LOST] [--timeFrame] [--startDate] [--endDate]
   get-monthly-metrics        [same optional flags as get-dashboard]  (dashboard.getMonthlyMetrics)
@@ -336,6 +342,9 @@ async function main() {
                     throw new Error("mark-budget-won requires <budgetId> <filePath>");
                 }
                 await markBudgetWonWithProof(budgetId, filePath, {
+                    projectManagerId: getFlag(flags, "projectManagerId") !== undefined
+                        ? String(getFlag(flags, "projectManagerId"))
+                        : undefined,
                     markProjectWon: parseOptionalBoolFlag(flags, "markProjectWon"),
                 });
                 break;
@@ -374,6 +383,9 @@ async function main() {
                     throw new Error(`Invalid status. Use one of: ${budgetStatusesForHelp.join(", ")}`);
                 }
                 await updateBudgetStatus(id, status, {
+                    projectManagerId: getFlag(flags, "projectManagerId") !== undefined
+                        ? String(getFlag(flags, "projectManagerId"))
+                        : undefined,
                     markProjectWon: parseOptionalBoolFlag(flags, "markProjectWon"),
                     projectStatusOnCommercialRejection: parseCommercialRejectionProjectStatus(flags),
                 });
@@ -678,12 +690,71 @@ async function main() {
                 await getBillAttachments(id);
                 break;
             }
-            case "upload-bill-attachment": {
-                const [billId, filePath] = positional;
-                if (!billId || !filePath) {
-                    throw new Error("upload-bill-attachment requires <billId> <filePath>");
+            case "upload-bill-attachment":
+            case "attach-bill-attachment":
+            case "attach-bill-payment-receipt": {
+                const [billId, ...positionalFilePaths] = positional;
+                const fileFlag = getFlag(flags, "file");
+                const filesFlag = getFlag(flags, "files");
+                const filePaths = [
+                    ...positionalFilePaths,
+                    ...(fileFlag !== undefined ? [String(fileFlag)] : []),
+                    ...(filesFlag !== undefined
+                        ? String(filesFlag)
+                            .split(",")
+                            .map((value) => value.trim())
+                            .filter(Boolean)
+                        : []),
+                ];
+                if (!billId || filePaths.length === 0) {
+                    throw new Error(`${cmd} requires <billId> <filePath...> or --file/--files`);
+                }
+                const attachmentType = cmd === "attach-bill-payment-receipt" ? "BILL_PAYMENT_PROOF" : "BILL";
+                const [firstFilePath] = filePaths;
+                if (filePaths.length === 1 && firstFilePath !== undefined) {
+                    await uploadBillAttachmentFromPath(billId, firstFilePath, attachmentType);
+                }
+                else {
+                    await uploadBillAttachmentsFromPaths(billId, filePaths, attachmentType);
                 }
-                await uploadBillAttachmentFromPath(billId, filePath);
+                break;
+            }
+            case "attach-bill-documents": {
+                const billId = positional[0];
+                if (!billId)
+                    throw new Error("attach-bill-documents requires <billId>");
+                const getFlagAlias = (...flagNames) => {
+                    for (const flagName of flagNames) {
+                        const value = getFlag(flags, flagName);
+                        if (value !== undefined)
+                            return value;
+                    }
+                    return undefined;
+                };
+                const parseFilesFlag = (...flagNames) => {
+                    const raw = getFlagAlias(...flagNames);
+                    if (raw === undefined)
+                        return [];
+                    return String(raw)
+                        .split(",")
+                        .map((value) => value.trim())
+                        .filter(Boolean);
+                };
+                const invoicePath = getFlagAlias("invoice", "invoice-file");
+                const paymentProofPath = getFlagAlias("paymentProof", "payment-proof", "proof", "receipt");
+                const invoicePaths = [
+                    ...(invoicePath !== undefined ? [String(invoicePath)] : []),
+                    ...parseFilesFlag("invoices", "invoice-files"),
+                ];
+                const paymentProofPaths = [
+                    ...(paymentProofPath !== undefined ? [String(paymentProofPath)] : []),
+                    ...parseFilesFlag("paymentProofs", "payment-proofs", "proofs", "receipts"),
+                ];
+                await uploadBillDocumentsFromPaths({
+                    billId,
+                    invoicePaths,
+                    paymentProofPaths,
+                });
                 break;
             }
             case "get-bill-details": {
@@ -908,6 +979,7 @@ async function main() {
                 const venue = getFlag(flags, "venue");
                 const pax = getFlag(flags, "pax");
                 const asanaTaskId = getFlag(flags, "asanaTaskId");
+                const asanaSearch = getFlag(flags, "asanaSearch");
                 const slackChannelId = getFlag(flags, "slackChannelId");
                 const slackChannelUrl = getFlag(flags, "slackChannelUrl");
                 const slackChannelName = getFlag(flags, "slackChannelName");
@@ -921,12 +993,8 @@ async function main() {
                     !insideSalesId ||
                     !businessDevelopmentId ||
                     !venue ||
-                    !asanaTaskId ||
-                    !slackChannelId ||
-                    !slackChannelUrl ||
-                    !slackChannelName ||
                     !startDate) {
-                    throw new Error("create-project requires --name --companyId --contactPersonId --insideSalesId --businessDevelopmentId --venue --asanaTaskId --slackChannelId --slackChannelUrl --slackChannelName --startDate (ISO/datetime flags as appropriate); optional --pax and --endDate");
+                    throw new Error("create-project requires --name --companyId --contactPersonId --insideSalesId --businessDevelopmentId --venue --startDate (ISO/datetime flags as appropriate); optional --asanaTaskId, --asanaSearch, --pax and --endDate");
                 }
                 await createProject({
                     name,
@@ -937,6 +1005,7 @@ async function main() {
                     venue,
                     pax,
                     asanaTaskId,
+                    asanaSearch,
                     slackChannelId,
                     slackChannelUrl,
                     slackChannelName,
@@ -1167,6 +1236,42 @@ async function main() {
                 await listUsers();
                 break;
             }
+            case "create-user": {
+                const email = getFlag(flags, "email");
+                if (!email) {
+                    throw new Error(`create-user requires --email <email> [--name <name>] [--role ${userRolesForHelp.join("|")}]`);
+                }
+                await createUser({
+                    email,
+                    name: getFlag(flags, "name"),
+                    role: parseUserRole(getFlag(flags, "role")),
+                });
+                break;
+            }
+            case "create-api-key": {
+                const userId = getFlag(flags, "userId");
+                const name = getFlag(flags, "name");
+                if (!userId || !name) {
+                    throw new Error("create-api-key requires --userId <userId> --name <label>");
+                }
+                await createApiKeyForUser({ userId, name });
+                break;
+            }
+            case "list-api-keys": {
+                await listApiKeysForUser({ userId: getFlag(flags, "userId") });
+                break;
+            }
+            case "revoke-api-key": {
+                const id = positional[0];
+                if (!id) {
+                    throw new Error("revoke-api-key requires <apiKeyId> [--userId <userId>]");
+                }
+                await revokeApiKeyForUser({
+                    id,
+                    userId: getFlag(flags, "userId"),
+                });
+                break;
+            }
             case "get-user-performance": {
                 await getUserPerformance(getFlag(flags, "userId"));
                 break;

package/dist/parse-cli-enums.js

@@ -1,8 +1,9 @@
 import { BudgetRole, Deals, ExtendedApprovalStatus, ExtendedBillStatus, ExtendedErrorSeverity, ExtendedErrorStatus, ExtendedProjectStatus, TimeFrame, } from "./filter-enums.js";
-import { BillStatus, BudgetStatus, ProjectStatus } from "./prisma-enums.js";
+import { BillStatus, BudgetStatus, ProjectStatus, UserRole, } from "./prisma-enums.js";
 const BUDGET_STATUS_VALUES = new Set(Object.values(BudgetStatus));
 const BILL_STATUS_VALUES = new Set(Object.values(BillStatus));
 const PROJECT_STATUS_VALUES = new Set(Object.values(ProjectStatus));
+const USER_ROLE_VALUES = new Set(Object.values(UserRole));
 const EXTENDED_PROJECT_STATUS_VALUES = new Set(Object.values(ExtendedProjectStatus));
 const DASHBOARD_ROLE_VALUES = new Set([
     "BD",
@@ -52,6 +53,15 @@ export function parseProjectStatusForUpdate(raw) {
     }
     return raw;
 }
+export function parseUserRole(raw) {
+    if (raw === undefined || raw === "")
+        return UserRole.USER;
+    const normalizedRole = raw.trim().toUpperCase();
+    if (!USER_ROLE_VALUES.has(normalizedRole)) {
+        throw new Error(`Invalid user role "${raw}". Use one of: ${[...USER_ROLE_VALUES].join(", ")}.`);
+    }
+    return normalizedRole;
+}
 export function parseOptionalExtendedProjectStatus(raw) {
     if (raw === undefined || raw === "")
         return undefined;
@@ -233,3 +243,4 @@ export const budgetStatusesForHelp = Object.values(BudgetStatus);
 export const billStatusesForHelp = Object.values(BillStatus);
 export const billStatusesForUpdateHelp = Object.values(BillStatus).filter((s) => s !== BillStatus.PENDING_APPROVAL);
 export const projectStatusesForHelp = Object.values(ProjectStatus);
+export const userRolesForHelp = Object.values(UserRole);

package/dist/prisma-enums.js

@@ -36,6 +36,13 @@ export const ApprovalType = {
     CUSTOMER_INVOICE: "CUSTOMER_INVOICE",
     QUOTATION: "QUOTATION",
 };
+export const UserRole = {
+    USER: "USER",
+    LEAD: "LEAD",
+    ADMIN: "ADMIN",
+    INSIDE_SALES: "INSIDE_SALES",
+    ACCOUNTING_TEAM: "ACCOUNTING_TEAM",
+};
 export const ErrorSeverity = {
     LOW: "LOW",
     MEDIUM: "MEDIUM",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-labs-sg/bb",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "description": "Budget Builder CLI for AI agents — manage budgets, bills, and claims; bill records use isClaimable=false for bills and isClaimable=true for claims.",
   "type": "module",
   "main": "./dist/index.js",