@go-labs-sg/bb 1.16.0 → 1.18.1

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
@@ -56,10 +70,12 @@ Global options and flags use `--key=value` or `--key value` (see `bb help`).
 
 **Authoritative command list:** run `bb help` — it includes every command, positional args, and flags. MCP exposes a subset of the same tRPC surface; the CLI additionally includes a few procedures mainly used by the web UI (e.g. `reorder-budget-items`, `update-budget-item-supplier`). You can also use MCP-style `snake_case` (e.g. `bb list_bills`); it is normalized to kebab-case.
 
-**Budget status automation:** Setting a budget to `ESTIMATE_ACCEPTED` requires a confirmed win-proof attachment. If the parent project is `PITCH` or `LOST`, the API now marks it `WON` automatically and, when the `asana-tasks` feature flag is enabled, creates the Asana project/section/tasks automatically. When rejecting the only accepted/closed budget on a commercial project, pass `--projectStatusOnCommercialRejection PITCH|LOST`.
+**Budget status automation:** Setting a budget to `ESTIMATE_ACCEPTED` requires a confirmed win-proof attachment. If the parent project is `PITCH` or `LOST`, the API now marks it `WON` automatically and, when the `asana-tasks` feature flag is enabled, creates an Asana Event Ops section from Prompt 5 tasks. 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. When rejecting the only accepted/closed budget on a commercial project, pass `--projectStatusOnCommercialRejection PITCH|LOST`.
 
 **Sensitive workflow changes:** Approval decisions/requests, entity status updates, `mark-budget-won`, `submit-quotation`, and supplier approval request side effects require an interactive `CONFIRM` prompt. Non-interactive runs abort before the guarded workflow mutation. Agents must get user confirmation in chat before attempting the command; the prompt is a final runtime guard, not a replacement for user approval.
 
+**Approval email exclusions:** Approval requests create pending database records for every eligible approver, including configured non-recipient admin accounts. Automated approval-request emails skip those accounts.
+
 **Locked estimate budget changes:** Budget-changing CLI commands require an interactive `yes` confirmation when the current budget status is `ESTIMATE_CREATED`, `ESTIMATE_SENT`, `ESTIMATE_ACCEPTED`, `ESTIMATE_REJECTED`, or `ESTIMATE_CLOSED`. There is no force/override flag; non-interactive runs abort before mutating locked budgets.
 
 **Mutations with `--payload`:** Commands such as `create-budget`, `create-bill`, `update-supplier`, etc. take a single JSON object (`--payload '<json>'`) matching the corresponding tRPC procedure input. Use ISO strings for date/datetime fields; the CLI coerces them where needed. The API still validates the full shape. Plain `description` fields for item create/update are converted to `descriptionRichText`; pass `descriptionRichText` directly when formatted Tiptap JSON is required. For **`update-project`**, the project window is `dateRange.from` and `dateRange.to` (optional end); there are no separate event-date fields on the project payload. **`create-budget` / `update-budget`** do not accept `asanaTaskId`; configure the deal card on the project (`update-project` / project settings).
@@ -68,14 +84,14 @@ Global options and flags use `--key=value` or `--key value` (see `bb help`).
 
 | Area | Commands (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`, `update-budget-status` (`ESTIMATE_ACCEPTED` requires win proof, auto-marks `PITCH` or `LOST` projects `WON`, and auto-creates Asana project/section/tasks when enabled; `--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`), `delete-budget`, `create-budget-approval` (also sends approval request emails), `add-budget-items`, `update-budget-item`, `remove-budget-item`, `reorder-budget-items`, `update-budget-item-supplier`, `create-budget-category`, `update-budget-category`, `delete-budget-category`, `update-budget-commission`, `update-budget-discount` (`--payload` where noted), `upload-budget-attachment` (`<budgetId>` + local file path; uses `attachment.requestBudgetAttachmentUpload` + PUT + `attachment.confirmBudgetAttachment`) |
-| **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`) |
+| **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`, `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`), `delete-budget`, `create-budget-approval` (also sends approval request emails), `add-budget-items`, `update-budget-item`, `remove-budget-item`, `reorder-budget-items`, `update-budget-item-supplier`, `create-budget-category`, `update-budget-category`, `delete-budget-category`, `update-budget-commission`, `update-budget-discount` (`--payload` where noted), `upload-budget-attachment` (`<budgetId>` + local file path; uses `attachment.requestBudgetAttachmentUpload` + PUT + `attachment.confirmBudgetAttachment`) |
+| **Bills / claims** | `list-bills` (`--isClaimable false` for bills, `--isClaimable true` for claims, omit for both), `list-claims` (claims only), `stage-bill-attachment` (securely uploads invoice/payment-proof files before creation and returns attachment JSON), `create-bill` (`--payload`; set `isClaimable=false` for a bill, `isClaimable=true` for a claim; supplier bills require positive `extractedAmount` and `amount`, with `amount <= extractedAmount`; an already-paid supplier bill sets `alreadyPaid=true` and requires `paymentReference` plus a staged PDF in `paymentProofAttachments`, and is created pending finance approval; non-legacy supplier bills from 1 Jul 2026 00:00 SGT also require approved quotation coverage), `update-bill` (`--payload`), `delete-bill`, `create-bill-approval` (also sends approval request emails), `update-bill-status` (moving a bill or claim to `PAID` sends creator and supplier emails, CC `m@getout.sg` and BCC `noah@getout.sg`; a claim sends one email when both recipient addresses match), `patch-bill-payment` (PAID bills: `--paymentTrackingUrl`, `--paymentReference`, `--quickbooksBillId`, `--paymentDate` ISO; clearing a paid bill's QuickBooks link is not allowed), `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`; include `amountWithoutGst` and `gstAmount`), `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`, `--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`) |
+| **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), `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`, `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; 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`, `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

@@ -19,6 +19,34 @@ const ASANA_WON_LOST_SECTION_GIDS = new Set([
 ]);
 const MAX_ASANA_LEAD_CANDIDATES = 5;
 const ASANA_SEARCH_DETAIL_LIMIT = 15;
+const NOTIFICATION_PAGE_LIMIT = 50;
+const getAllNotifications = async () => {
+    const notifications = [];
+    let cursor;
+    do {
+        const page = await api.budget.getNotifications.query({
+            cursor,
+            limit: NOTIFICATION_PAGE_LIMIT,
+        });
+        notifications.push(...page.notifications);
+        cursor = page.nextCursor;
+    } while (cursor);
+    return notifications;
+};
+const createApprovalEmailDeliveryReport = ({ sentCount, skippedCount, message, }) => ({
+    sent: sentCount > 0,
+    count: sentCount,
+    sentCount,
+    skippedCount,
+    message,
+});
+const createApprovalEmailDeliveryFailure = (error) => ({
+    sent: false,
+    count: 0,
+    sentCount: 0,
+    skippedCount: 0,
+    error,
+});
 function isPendingRequest(n) {
     return n.notificationType === "request" && n.status === "PENDING_APPROVAL";
 }
@@ -212,6 +240,27 @@ const contentTypeHeaderForFileName = (fileName) => {
     const ct = contentType(fileName);
     return typeof ct === "string" ? ct : "application/octet-stream";
 };
+const supportedAttachmentContentTypes = [
+    "application/pdf",
+    "image/gif",
+    "image/jpeg",
+    "image/png",
+    "image/webp",
+];
+const attachmentContentTypeForFileName = (fileName) => {
+    const resolvedContentType = contentTypeHeaderForFileName(fileName);
+    const supportedContentType = supportedAttachmentContentTypes.find((contentTypeValue) => contentTypeValue === resolvedContentType);
+    if (supportedContentType)
+        return supportedContentType;
+    throw new Error(`Unsupported attachment type: ${fileName}`);
+};
+const billAttachmentContentTypeForFileName = (fileName) => {
+    const resolvedContentType = attachmentContentTypeForFileName(fileName);
+    if (resolvedContentType === "image/webp") {
+        throw new Error(`Unsupported QuickBooks bill attachment type: ${fileName}. Use PDF, GIF, JPEG, or PNG.`);
+    }
+    return resolvedContentType;
+};
 const LOCKED_BUDGET_STATUSES_REQUIRING_CONFIRMATION = new Set([
     BudgetStatus.ESTIMATE_CREATED,
     BudgetStatus.ESTIMATE_SENT,
@@ -424,7 +473,7 @@ export async function approveBill(billId) {
         entity: `bill ${billId}`,
         details: "and send requester reply email",
     });
-    const notifications = await api.budget.getNotifications.query();
+    const notifications = await getAllNotifications();
     const pending = notifications.filter((n) => isPendingRequest(n) &&
         n.type === BILL &&
         (n.billId === billId || n.bill?.id === billId));
@@ -436,6 +485,10 @@ export async function approveBill(billId) {
         billApprovalId: approval.id,
         status: "APPROVED",
     });
+    if (result.processing) {
+        out(result);
+        return;
+    }
     let email;
     try {
         await api.email.sendReplyBillApprovalEmail.mutate(result.updatedApproval);
@@ -453,7 +506,7 @@ export async function approveBill(billId) {
     });
 }
 export async function listApprovals(opts) {
-    const notifications = await api.budget.getNotifications.query();
+    const notifications = await getAllNotifications();
     const pending = notifications.filter(isPendingRequest);
     const typeFilter = opts.type === undefined || opts.type === "ALL"
         ? (_n) => true
@@ -524,19 +577,15 @@ export async function createBillApproval(billId) {
     const approvalIds = (result.results ?? []).map((item) => ({ id: item.id }));
     let email;
     if (approvalIds.length === 0) {
-        email = { sent: false, count: 0, error: "No approval ids returned" };
+        email = createApprovalEmailDeliveryFailure("No approval ids returned");
     }
     else {
         try {
-            await api.email.sendBillApprovalRequestEmail.mutate(approvalIds);
-            email = { sent: true, count: approvalIds.length };
+            const delivery = await api.email.sendBillApprovalRequestEmail.mutate(approvalIds);
+            email = createApprovalEmailDeliveryReport(delivery);
         }
         catch (error) {
-            email = {
-                sent: false,
-                count: approvalIds.length,
-                error: error instanceof Error ? error.message : String(error),
-            };
+            email = createApprovalEmailDeliveryFailure(error instanceof Error ? error.message : String(error));
         }
     }
     out({
@@ -589,30 +638,104 @@ export async function getBillAttachments(id) {
     const result = await api.bill.getAttachments.query({ id });
     out(result);
 }
-export async function uploadBillAttachmentFromPath(billId, filePath) {
+export async function stageBillAttachmentsFromPaths(projectId, filePaths) {
+    const attachments = [];
+    for (const filePath of filePaths) {
+        const buffer = await readFile(filePath);
+        const fileName = basename(filePath);
+        const size = buffer.byteLength;
+        const contentType = billAttachmentContentTypeForFileName(fileName);
+        const { uploadUrl, key } = await api.attachment.requestStagedBillAttachmentUpload.mutate({
+            projectId,
+            fileName,
+            size,
+            contentType,
+        });
+        const response = await fetch(uploadUrl, {
+            method: "PUT",
+            body: buffer,
+            headers: { "Content-Type": contentType },
+        });
+        if (!response.ok) {
+            throw new Error(`S3 upload failed: HTTP ${response.status} ${(await response.text()).slice(0, 500)}`);
+        }
+        attachments.push({ id: randomUUID(), key, name: fileName, size });
+    }
+    out({
+        success: true,
+        projectId,
+        count: attachments.length,
+        attachments,
+    });
+}
+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;
+    const attachmentContentType = billAttachmentContentTypeForFileName(fileName);
     const { uploadUrl, key } = await api.attachment.requestBillAttachmentUpload.mutate({
         billId,
+        contentType: attachmentContentType,
         fileName,
         size,
     });
     const res = await fetch(uploadUrl, {
         method: "PUT",
         body: buf,
-        headers: { "Content-Type": contentTypeHeaderForFileName(fileName) },
+        headers: { "Content-Type": attachmentContentType },
     });
     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);
@@ -646,15 +769,17 @@ export async function uploadBudgetAttachmentFromPath(budgetId, filePath) {
     const buf = await readFile(filePath);
     const fileName = basename(filePath);
     const size = buf.byteLength;
+    const attachmentContentType = attachmentContentTypeForFileName(fileName);
     const { uploadUrl, key } = await api.attachment.requestBudgetAttachmentUpload.mutate({
         budgetId,
+        contentType: attachmentContentType,
         fileName,
         size,
     });
     const res = await fetch(uploadUrl, {
         method: "PUT",
         body: buf,
-        headers: { "Content-Type": contentTypeHeaderForFileName(fileName) },
+        headers: { "Content-Type": attachmentContentType },
     });
     if (!res.ok) {
         throw new Error(`S3 upload failed: HTTP ${res.status} ${(await res.text()).slice(0, 500)}`);
@@ -677,15 +802,17 @@ export async function uploadBudgetWinProofFromPath(budgetId, filePath, opts) {
     const buf = await readFile(filePath);
     const fileName = basename(filePath);
     const size = buf.byteLength;
+    const attachmentContentType = attachmentContentTypeForFileName(fileName);
     const { uploadUrl, key } = await api.attachment.requestBudgetWinProofUpload.mutate({
         budgetId,
+        contentType: attachmentContentType,
         fileName,
         size,
     });
     const res = await fetch(uploadUrl, {
         method: "PUT",
         body: buf,
-        headers: { "Content-Type": contentTypeHeaderForFileName(fileName) },
+        headers: { "Content-Type": attachmentContentType },
     });
     if (!res.ok) {
         throw new Error(`S3 upload failed: HTTP ${res.status} ${(await res.text()).slice(0, 500)}`);
@@ -774,19 +901,15 @@ export async function createBudgetApproval(budgetId, preflight) {
     const approvalIds = (result.results ?? []).map((item) => ({ id: item.id }));
     let email;
     if (approvalIds.length === 0) {
-        email = { sent: false, count: 0, error: "No approval ids returned" };
+        email = createApprovalEmailDeliveryFailure("No approval ids returned");
     }
     else {
         try {
-            await api.email.sendApprovalRequestEmail.mutate(approvalIds);
-            email = { sent: true, count: approvalIds.length };
+            const delivery = await api.email.sendApprovalRequestEmail.mutate(approvalIds);
+            email = createApprovalEmailDeliveryReport(delivery);
         }
         catch (error) {
-            email = {
-                sent: false,
-                count: approvalIds.length,
-                error: error instanceof Error ? error.message : String(error),
-            };
+            email = createApprovalEmailDeliveryFailure(error instanceof Error ? error.message : String(error));
         }
     }
     out({
@@ -967,19 +1090,15 @@ export async function createSupplierFromPayload(raw) {
     let emailResult;
     const approvalIds = (approval.results ?? []).map((item) => ({ id: item.id }));
     if (approvalIds.length === 0) {
-        emailResult = { sent: false, count: 0, error: "No approval ids returned" };
+        emailResult = createApprovalEmailDeliveryFailure("No approval ids returned");
     }
     else {
         try {
-            await api.email.sendSupplierApprovalRequestEmail.mutate(approvalIds);
-            emailResult = { sent: true, count: approvalIds.length };
+            const delivery = await api.email.sendSupplierApprovalRequestEmail.mutate(approvalIds);
+            emailResult = createApprovalEmailDeliveryReport(delivery);
         }
         catch (error) {
-            emailResult = {
-                sent: false,
-                count: approvalIds.length,
-                error: error instanceof Error ? error.message : String(error),
-            };
+            emailResult = createApprovalEmailDeliveryFailure(error instanceof Error ? error.message : String(error));
         }
     }
     out({
@@ -1016,27 +1135,23 @@ export async function updateSupplierFromPayload(raw) {
             approvalResult = {
                 requested: true,
                 approvalCount: 0,
-                email: { sent: false, count: 0, error: "No approval ids returned" },
+                email: createApprovalEmailDeliveryFailure("No approval ids returned"),
             };
         }
         else {
             try {
-                await api.email.sendSupplierApprovalRequestEmail.mutate(approvalIds);
+                const delivery = await api.email.sendSupplierApprovalRequestEmail.mutate(approvalIds);
                 approvalResult = {
                     requested: true,
                     approvalCount: approvalIds.length,
-                    email: { sent: true, count: approvalIds.length },
+                    email: createApprovalEmailDeliveryReport(delivery),
                 };
             }
             catch (error) {
                 approvalResult = {
                     requested: true,
                     approvalCount: approvalIds.length,
-                    email: {
-                        sent: false,
-                        count: approvalIds.length,
-                        error: error instanceof Error ? error.message : String(error),
-                    },
+                    email: createApprovalEmailDeliveryFailure(error instanceof Error ? error.message : String(error)),
                 };
             }
         }
@@ -1089,7 +1204,7 @@ export async function approveBudget(budgetId) {
         entity: `budget ${budgetId}`,
         details: "and send requester reply email",
     });
-    const notifications = await api.budget.getNotifications.query();
+    const notifications = await getAllNotifications();
     const pending = notifications.filter((n) => n.notificationType === "request" &&
         n.status === ExtendedApprovalStatus.PENDING_APPROVAL &&
         n.type === ExtendedApprovalType.BUDGET &&
@@ -1125,7 +1240,7 @@ export async function rejectBudget(budgetId, reason) {
         entity: `budget ${budgetId}`,
         details: `with reason "${reason}" and send requester reply email`,
     });
-    const notifications = await api.budget.getNotifications.query();
+    const notifications = await getAllNotifications();
     const pending = notifications.filter((n) => n.notificationType === "request" &&
         n.status === ExtendedApprovalStatus.PENDING_APPROVAL &&
         n.type === ExtendedApprovalType.BUDGET &&
@@ -1223,7 +1338,7 @@ export async function approveSupplier(supplierId) {
         entity: `supplier ${supplierId}`,
         details: "and send requester reply email",
     });
-    const notifications = await api.budget.getNotifications.query();
+    const notifications = await getAllNotifications();
     const pending = notifications.filter((n) => n.notificationType === "request" &&
         n.status === ExtendedApprovalStatus.PENDING_APPROVAL &&
         n.type === ExtendedApprovalType.SUPPLIER &&
@@ -1261,7 +1376,7 @@ export async function rejectSupplier(supplierId, reason) {
         entity: `supplier ${supplierId}`,
         details: `with reason "${reason}" and send requester reply email`,
     });
-    const notifications = await api.budget.getNotifications.query();
+    const notifications = await getAllNotifications();
     const pending = notifications.filter((n) => n.notificationType === "request" &&
         n.status === ExtendedApprovalStatus.PENDING_APPROVAL &&
         n.type === ExtendedApprovalType.SUPPLIER &&
@@ -1300,7 +1415,7 @@ export async function rejectBill(billId, reason) {
         entity: `bill ${billId}`,
         details: `with reason "${reason}" and send requester reply email`,
     });
-    const notifications = await api.budget.getNotifications.query();
+    const notifications = await getAllNotifications();
     const pending = notifications.filter((n) => n.notificationType === "request" &&
         n.status === ExtendedApprovalStatus.PENDING_APPROVAL &&
         n.type === ExtendedApprovalType.BILL &&
@@ -1314,6 +1429,10 @@ export async function rejectBill(billId, reason) {
         status: ExtendedApprovalStatus.REJECTED,
         rejectionReason: reason,
     });
+    if (result.processing) {
+        out(result);
+        return;
+    }
     let email;
     try {
         await api.email.sendReplyBillApprovalEmail.mutate(result.updatedApproval);
@@ -1335,7 +1454,7 @@ export async function approveQuotation(quotationId) {
         action: "Approve quotation",
         entity: `quotation ${quotationId}`,
     });
-    const notifications = await api.budget.getNotifications.query();
+    const notifications = await getAllNotifications();
     const pending = notifications.filter((n) => isPendingRequest(n) &&
         n.type === QUOTATION &&
         (n.supplierQuotationId === quotationId ||
@@ -1355,7 +1474,7 @@ export async function rejectQuotation(quotationId, reason) {
         entity: `quotation ${quotationId}`,
         details: `with reason "${reason}"`,
     });
-    const notifications = await api.budget.getNotifications.query();
+    const notifications = await getAllNotifications();
     const pending = notifications.filter((n) => isPendingRequest(n) &&
         n.type === QUOTATION &&
         (n.supplierQuotationId === quotationId ||
@@ -1424,6 +1543,7 @@ export async function createProject(opts) {
         contactPersonId: opts.contactPersonId,
         insideSalesId: opts.insideSalesId,
         businessDevelopmentId: opts.businessDevelopmentId,
+        projectManagerId: opts.projectManagerId,
         venue: opts.venue,
         pax: opts.pax,
         asanaTaskId: links.asanaTaskId,
@@ -1447,8 +1567,8 @@ export async function updateProjectStatus(id, status, opts) {
         id,
         status,
         ...(opts?.projectManagerId && { projectManagerId: opts.projectManagerId }),
-        ...(opts?.projectManagerName && {
-            projectManagerName: opts.projectManagerName,
+        ...(opts?.projectManagerEmail && {
+            projectManagerEmail: opts.projectManagerEmail,
         }),
         ...(opts?.wonOverrideReason && {
             wonOverrideReason: opts.wonOverrideReason,
@@ -1495,6 +1615,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, stageBillAttachmentsFromPaths, 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)
@@ -145,7 +145,7 @@ Budgets
   create-budget-approval <budgetId>   (also sends approval request emails)
   create-estimate <budgetId>          (creates QuickBooks estimate; supports preflight updates)
   add-budget-items           --budgetId --items '[{"itemId":"…","quantity":1,"markup":30},…]'
-  update-budget-item         --id <budgetItemId> [--description plain-text] [--note plain-text] [--quantity] [--markup] [--cost] [--unitPrice] [--isFreeOfCharge true|false] [--gstInclusive true|false]
+  update-budget-item         --id <budgetItemId> [--description plain-text] [--note plain-text] [--quantity] [--markup] [--cost] [--unitPrice] [--isFreeOfCharge true|false] [--gstInclusive true|false] [--gstOutOfScope true|false]
   remove-budget-item <budgetItemId>
   reorder-budget-items       <budgetId> --itemIds <csv>
   update-budget-item-supplier --budgetItemId --supplierId
@@ -162,23 +162,27 @@ Bills
     isClaimable differentiates the shared bill/claim records: false = bill, true = claim.
     New supplier bills from 1 Jul 2026 00:00 SGT require approved quotation coverage for each non-legacy line item.
   create-bill-approval <billId>       (also sends approval request emails)
-  create-bill                --payload '<json>'  (bill.create; payload.isClaimable false = bill, true = claim; use upload-bill-attachment after create to add files)
+  create-bill                --payload '<json>'  (bill.create; payload.isClaimable false = bill, true = claim)
+  stage-bill-attachment <projectId> <filePath...> [--file <path>] [--files <csv>]   Upload files before create-bill; returns attachment JSON for attachments/paymentProofAttachments
   update-bill                --payload '<json>'  (bill.update; must include id)
   delete-bill <billId>
   update-bill-status <id> <status> [--rejectionReason] [--paymentTrackingUrl] [--paymentReference]
     status (${billStatusesForUpdateHelp.join(", ")}) — not PENDING_APPROVAL; use create-bill-approval
+    Moving a bill or claim to PAID sends creator and supplier emails, CC m@getout.sg and BCC noah@getout.sg; duplicate claim recipients receive one email.
   patch-bill-payment <billId> [--paymentTrackingUrl] [--paymentReference] [--quickbooksBillId] [--paymentDate <ISO>]
     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
   list-quotations            [--projectId] [--budgetId] [--supplierId] [--status CSV] [--page] [--pageSize]
   get-quotation <quotationId>
   upload-quotation-attachment <projectId> <filePath>   Presigned S3 upload; returns attachment JSON for create-quotation payload
-  create-quotation           --payload '<json>'  (quotation.createDraft)
+  create-quotation           --payload '<json>'  (quotation.createDraft; requires amountWithoutGst and gstAmount)
   submit-quotation <quotationId>
   approve-quotation <quotationId>
   reject-quotation <quotationId> --reason <text>
@@ -203,11 +207,12 @@ 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 --startDate <ISO> [--asanaTaskId] [--asanaSearch <text>] [--slackChannelId --slackChannelUrl --slackChannelName] [--pax] [--endDate <ISO>] [--description]
-  update-project             --payload '<json>'  (project.updateProject; optional requestQboAccountantNotification; default notify like web)
+    Budget overview totalRevenue includes Estimate Accepted and Estimate Closed budgets only.
+  create-project             --name --companyId --contactPersonId --insideSalesId --businessDevelopmentId --venue --startDate <ISO> [--projectManagerId <userId>] [--asanaTaskId] [--asanaSearch <text>] [--slackChannelId --slackChannelUrl --slackChannelName] [--pax] [--endDate <ISO>] [--description]
+  update-project             --payload '<json>'  (project.updateProject; optional projectManagerId and requestQboAccountantNotification; default notify like web)
   delete-project <id>
-  update-project-status <id> <status> [--projectManagerId <id>] [--projectManagerName <name>] [--wonOverrideReason <text>]
-    Required when moving PITCH → WON: supply --projectManagerId or --projectManagerName.
+  update-project-status <id> <status> [--projectManagerId <userId>] [--projectManagerEmail <email>] [--wonOverrideReason <text>]
+	Required when moving PITCH → WON: supply --projectManagerId or --projectManagerEmail.
     Required when moving to WON without accepted/closed budget or win proof: --wonOverrideReason (10+ chars).
     status: ${projectStatusesForHelp.join(", ")}
 
@@ -241,6 +246,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)
@@ -472,6 +481,7 @@ async function main() {
                     unitPrice: parseOptNum(getFlag(flags, "unitPrice"), "--unitPrice"),
                     isFreeOfCharge: parseOptionalBoolFlag(flags, "isFreeOfCharge"),
                     gstInclusive: parseOptionalBoolFlag(flags, "gstInclusive"),
+                    gstOutOfScope: parseOptionalBoolFlag(flags, "gstOutOfScope"),
                 });
                 break;
             }
@@ -684,12 +694,91 @@ 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 "stage-bill-attachment": {
+                const [projectId, ...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 (!projectId || filePaths.length === 0) {
+                    throw new Error("stage-bill-attachment requires <projectId> <filePath...> or --file/--files");
+                }
+                await stageBillAttachmentsFromPaths(projectId, filePaths);
+                break;
+            }
+            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);
                 }
-                await uploadBillAttachmentFromPath(billId, filePath);
+                else {
+                    await uploadBillAttachmentsFromPaths(billId, filePaths, attachmentType);
+                }
+                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": {
@@ -911,6 +1000,7 @@ async function main() {
                 const contactPersonId = getFlag(flags, "contactPersonId");
                 const insideSalesId = getFlag(flags, "insideSalesId");
                 const businessDevelopmentId = getFlag(flags, "businessDevelopmentId");
+                const projectManagerId = getFlag(flags, "projectManagerId");
                 const venue = getFlag(flags, "venue");
                 const pax = getFlag(flags, "pax");
                 const asanaTaskId = getFlag(flags, "asanaTaskId");
@@ -929,7 +1019,7 @@ async function main() {
                     !businessDevelopmentId ||
                     !venue ||
                     !startDate) {
-                    throw new Error("create-project requires --name --companyId --contactPersonId --insideSalesId --businessDevelopmentId --venue --startDate (ISO/datetime flags as appropriate); optional --asanaTaskId, --asanaSearch, --pax and --endDate");
+                    throw new Error("create-project requires --name --companyId --contactPersonId --insideSalesId --businessDevelopmentId --venue --startDate (ISO/datetime flags as appropriate); optional --projectManagerId, --asanaTaskId, --asanaSearch, --pax and --endDate");
                 }
                 await createProject({
                     name,
@@ -937,6 +1027,7 @@ async function main() {
                     contactPersonId,
                     insideSalesId,
                     businessDevelopmentId,
+                    projectManagerId,
                     venue,
                     pax,
                     asanaTaskId,
@@ -972,11 +1063,13 @@ async function main() {
                     throw new Error("update-project-status requires <id> <status>");
                 }
                 const pmIdFlag = getFlag(flags, "projectManagerId");
-                const pmNameFlag = getFlag(flags, "projectManagerName");
+                const pmEmailFlag = getFlag(flags, "projectManagerEmail");
                 const wonOverrideReasonFlag = getFlag(flags, "wonOverrideReason");
                 await updateProjectStatus(id, parseProjectStatusForUpdate(statusRaw), {
                     ...(pmIdFlag && { projectManagerId: String(pmIdFlag) }),
-                    ...(pmNameFlag && { projectManagerName: String(pmNameFlag) }),
+                    ...(pmEmailFlag && {
+                        projectManagerEmail: String(pmEmailFlag),
+                    }),
                     ...(wonOverrideReasonFlag && {
                         wonOverrideReason: String(wonOverrideReasonFlag),
                     }),
@@ -1171,6 +1264,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/parse-mutation-payload.js

@@ -77,8 +77,8 @@ export function parseBudgetDiscountPayload(raw) {
         totalSellingBeforeDiscount: Number(o.totalSellingBeforeDiscount),
     };
 }
-const billAttachment = (x, i) => {
-    const label = `create-bill payload.attachments[${i}]`;
+const billAttachment = (x, i, field = "attachments") => {
+    const label = `create-bill payload.${field}[${i}]`;
     const a = requireObject(x, label);
     return {
         id: requiredString(a.id, `${label}.id`),
@@ -102,6 +102,16 @@ export function parseCreateBillPayload(raw) {
     const attachments = Array.isArray(attachmentsRaw)
         ? attachmentsRaw.map((x, i) => billAttachment(x, i))
         : [];
+    const alreadyPaidRaw = o.alreadyPaid;
+    if (alreadyPaidRaw !== undefined &&
+        alreadyPaidRaw !== null &&
+        typeof alreadyPaidRaw !== "boolean") {
+        throw new Error("create-bill payload.alreadyPaid must be boolean.");
+    }
+    const paymentProofAttachmentsRaw = o.paymentProofAttachments;
+    const paymentProofAttachments = Array.isArray(paymentProofAttachmentsRaw)
+        ? paymentProofAttachmentsRaw.map((x, i) => billAttachment(x, i, "paymentProofAttachments"))
+        : [];
     let verificationResults;
     const vr = o.verificationResults;
     if (vr !== undefined && vr !== null) {
@@ -153,6 +163,9 @@ export function parseCreateBillPayload(raw) {
         comment: optionalString(o.comment),
         isClaimable,
         attachments,
+        alreadyPaid: alreadyPaidRaw ?? undefined,
+        paymentReference: optionalString(o.paymentReference),
+        paymentProofAttachments,
         extractedSupplierName: optionalString(o.extractedSupplierName),
         extractedAmount: o.extractedAmount === undefined || o.extractedAmount === null
             ? undefined
@@ -214,6 +227,7 @@ export function parseUpdateProjectPayload(raw) {
         asanaTaskId: requiredString(o.asanaTaskId, "update-project payload.asanaTaskId"),
         insideSalesId: requiredString(o.insideSalesId, "update-project payload.insideSalesId"),
         businessDevelopmentId: requiredString(o.businessDevelopmentId, "update-project payload.businessDevelopmentId"),
+        projectManagerId: optionalString(o.projectManagerId),
         venue: requiredString(o.venue, "update-project payload.venue"),
         pax: optionalString(o.pax),
         dateRange: {

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.16.0",
+  "version": "1.18.1",
   "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",