@go-labs-sg/bb 1.0.4 → 1.1.1

package/README.md

@@ -1,12 +1,12 @@
 # bb
 
-Command-line interface for **Budget Builder**. Call budgets, bills, approvals, and suppliers from your terminal or from tools that don’t support MCP (e.g. some AI agents). Responses are JSON on stdout.
+Command-line interface for **Budget Builder**. Call budgets, bills, approvals, suppliers, dashboard, and more from your terminal or from tools that don’t support MCP (e.g. some AI agents). Responses are JSON on stdout.
 
 **Registry:** [`@go-labs-sg/bb`](https://www.npmjs.com/package/@go-labs-sg/bb)
 
 ## Requirements
 
-- **Node.js** 18+
+- **Node.js** 18+ (ESM; relative imports in `dist` use `.js` extensions)
 - A **Budget Builder API key** (same key used for the MCP server)
 
 ## Install
@@ -48,17 +48,21 @@ bb list-suppliers
 
 Global options and flags use `--key=value` or `--key value` (see `bb help`).
 
-## Commands
+**Authoritative command list:** run `bb help` — it includes every command, positional args, and flags (kept in sync with the MCP tool surface). You can also use MCP-style `snake_case` (e.g. `bb list_bills`); it is normalized to kebab-case.
 
-| Command | Description |
+### Command overview
+
+| Area | Commands (non-exhaustive) |
 | --- | --- |
-| `list-budgets` | List budgets. Flags: `--projectId`, `--name`, `--status` (comma-separated), `--page`, `--perPage` |
-| `get-budget <id>` | Budget details and line items |
-| `update-budget-status <id> <status>` | Change budget status (e.g. `APPROVED`, `REJECTED`, `DRAFT`, …) |
-| `list-bills` | List bills. Flags: `--projectId`, `--budgetId`, `--status`, `--page`, `--pageSize` |
-| `approve-bill <id>` | Approve a pending bill (matches your pending bill approvals) |
-| `list-approvals` | Pending approvals. Flag: `--type` = `budget`, `supplier`, `bill`, or `all` |
-| `list-suppliers` | List suppliers. Flags: `--name`, `--page`, `--perPage` |
+| **Budgets** | `list-budgets`, `get-budget`, `get-budget-items`, `get-budget-details`, `get-budget-categories`, `get-budget-versions`, `update-budget-status`, `create-budget-approval`, `add-budget-items`, `update-budget-item`, `remove-budget-item` |
+| **Bills** | `list-bills`, `list-claims`, `create-bill-approval`, `update-bill-status`, `patch-bill-payment`, `patch-bill-invoice-number`, `get-bill-attachments`, `get-bill-details` |
+| **Approvals** | `list-approvals` / `get-pending-approvals`, `approve-bill`, `reject-bill`, `approve-budget`, `reject-budget`, `approve-supplier`, `reject-supplier` |
+| **Companies & projects** | `list-companies`, `get-company`, `create-company`, `list-projects`, `get-project`, `create-project`, `update-project-status` |
+| **Contacts** | `list-contacts` |
+| **Suppliers & items** | `list-suppliers`, `get-supplier-details`, `get-supplier-analytics`, `list-items`, `get-item`, `list-item-categories` |
+| **Dashboard & users** | `list-users`, `get-user-performance`, `get-dashboard`, `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` |
 
 ## Output
 
@@ -70,7 +74,7 @@ A `.env` file in the **current working directory** is loaded automatically (for
 
 ## Developing in this repo
 
-From the monorepo root:
+From the monorepo root (after `bun install`):
 
 ```bash
 export BB_API_KEY=...
@@ -80,5 +84,15 @@ bun run bb -- list-budgets
 Or from `packages/cli`:
 
 ```bash
+bun run build          # emit dist/ via tsc
+bun run typecheck      # tsc --noEmit
 bun run src/index.ts list-budgets
 ```
+
+### Layout
+
+- **`src/filter-enums.ts`** — “extended” filter enums (ALL + Prisma enums), maintained here so the published package does not depend on unpublished workspace packages. Keep in line with `packages/utils/src/filter-enums.ts` when those values change.
+
+### Publish
+
+`prepublishOnly` strips `workspace:` / `catalog:` entries from this package’s `package.json`, runs `tsc`, then `postpack` restores the file — so the npm tarball does not contain monorepo protocol dependencies. Types from `@bb/api` are compile-time only (`import type`). Enum **values** in emitted JS import `@bb/db/enums` (workspace `@bb/db` during monorepo development).

package/dist/commands.js

@@ -1,13 +1,12 @@
 import { api } from "./api-client.js";
+import { BudgetRole, Deals, ExtendedApprovalStatus, ExtendedApprovalType, ExtendedBudgetStatus, TimeFrame, } from "./filter-enums.js";
+import { billStatusesForApi, } from "./parse-cli-enums.js";
 const BUDGET = "BUDGET";
 const BILL = "BILL";
 const SUPPLIER = "SUPPLIER";
 function isPendingRequest(n) {
     return n.notificationType === "request" && n.status === "PENDING_APPROVAL";
 }
-function isApprovalType(s) {
-    return s === BUDGET || s === BILL || s === SUPPLIER;
-}
 const out = (data) => {
     console.log(JSON.stringify(data, null, 2));
 };
@@ -16,6 +15,11 @@ export async function listBudgets(opts) {
         projectId: opts.projectId,
         name: opts.name,
         statuses: opts.statuses,
+        createdBy: opts.createdBy,
+        dateFrom: opts.dateFrom,
+        dateTo: opts.dateTo,
+        sortBy: opts.sortBy,
+        sortDir: opts.sortDir,
         page: opts.page ?? 1,
         perPage: opts.perPage ?? 20,
     };
@@ -30,18 +34,24 @@ export async function getBudget(id) {
     out({ budget, items });
 }
 export async function updateBudgetStatus(budgetId, status) {
-    const input = {
+    const result = await api.budget.updateBudgetStatus.mutate({
         id: budgetId,
-        status: status,
-    };
-    const result = await api.budget.updateBudgetStatus.mutate(input);
+        status,
+    });
     out(result);
 }
 export async function listBills(opts) {
     const input = {
         projectId: opts.projectId,
         budgetId: opts.budgetId,
-        status: opts.status,
+        statuses: billStatusesForApi(opts.statuses),
+        search: opts.search?.trim() || undefined,
+        isClaimable: opts.isClaimable,
+        createdByIds: opts.createdByIds && opts.createdByIds.length > 0
+            ? opts.createdByIds
+            : undefined,
+        sortBy: opts.sortBy,
+        sortDir: opts.sortDir,
         page: opts.page ?? 1,
         pageSize: opts.pageSize ?? 20,
     };
@@ -61,19 +71,17 @@ export async function approveBill(billId) {
         billApprovalId: approval.id,
         status: "APPROVED",
     });
-    out({ ...result, success: true, message: "Bill approved" });
+    out(result);
 }
 export async function listApprovals(opts) {
     const notifications = await api.budget.getNotifications.query();
     const pending = notifications.filter(isPendingRequest);
-    const raw = opts.type?.toUpperCase();
-    if (raw !== undefined && raw !== "ALL" && !isApprovalType(raw)) {
-        throw new Error("Invalid --type. Use one of: budget, supplier, bill, all.");
-    }
-    const typeFilter = !opts.type || opts.type.toLowerCase() === "all"
+    const typeFilter = opts.type === undefined || opts.type === "ALL"
         ? (_n) => true
-        : (n) => raw !== undefined && isApprovalType(raw) && n.type === raw;
-    const filtered = pending.filter(typeFilter);
+        : (n) => n.type === opts.type;
+    const filtered = pending
+        .filter(typeFilter)
+        .filter((n) => n.type !== BUDGET || !n.budget?.quickbooksEstimateId);
     const items = filtered.map((n) => {
         let id;
         let name;
@@ -116,3 +124,377 @@ export async function listSuppliers(opts) {
     });
     out(result);
 }
+// --- Bills (MCP parity) ---
+export async function createBillApproval(billId) {
+    const result = await api.bill.createApproval.mutate({ billId });
+    out(result);
+}
+export async function updateBillStatus(opts) {
+    const result = await api.bill.updateStatus.mutate({
+        id: opts.id,
+        status: opts.status,
+        rejectionReason: opts.rejectionReason,
+        paymentTrackingUrl: opts.paymentTrackingUrl,
+        paymentReference: opts.paymentReference,
+    });
+    out(result);
+}
+export async function patchBillPayment(opts) {
+    const result = await api.bill.patchPayment.mutate({
+        id: opts.id,
+        paymentTrackingUrl: opts.paymentTrackingUrl,
+        paymentReference: opts.paymentReference,
+        quickbooksBillId: opts.quickbooksBillId,
+    });
+    out(result);
+}
+export async function patchBillInvoiceNumber(id, invoiceNumber) {
+    const result = await api.bill.patchInvoiceNumber.mutate({
+        id,
+        invoiceNumber,
+    });
+    out(result);
+}
+export async function getBillAttachments(id) {
+    const result = await api.bill.getAttachments.query({ id });
+    out(result);
+}
+export async function getBillDetails(id) {
+    const result = await api.bill.getById.query({ id });
+    out(result);
+}
+// --- Budgets (MCP parity) ---
+export async function getBudgetItemsOnly(budgetId) {
+    const items = await api.budget.getBudgetItems.query({ budgetId });
+    out(items);
+}
+export async function addBudgetItems(opts) {
+    const result = await api.budgetItem.addBudgetItems.mutate(opts);
+    out(result);
+}
+export async function updateBudgetItem(input) {
+    const result = await api.budgetItem.updateBudgetItem.mutate(input);
+    out(result);
+}
+export async function removeBudgetItem(budgetItemId) {
+    const result = await api.budgetItem.removeBudgetItem.mutate({
+        budgetItemId,
+    });
+    out(result);
+}
+export async function getBudgetCategories() {
+    const categories = await api.budget.getBudgetCategories.query();
+    out(categories);
+}
+export async function getBudgetVersions(budgetId) {
+    const versions = await api.budgetVersion.getBudgetVersions.query({
+        budgetId,
+    });
+    out(versions);
+}
+export async function createBudgetApproval(budgetId) {
+    const result = await api.budget.createBudgetApproval.mutate({ budgetId });
+    out(result);
+}
+export async function getBudgetDetails(budgetId) {
+    const detail = await api.budget.getBudgetDetail.query({ id: budgetId });
+    out(detail);
+}
+// --- Approvals: budgets / suppliers / bills (MCP parity) ---
+export async function approveBudget(budgetId) {
+    const notifications = await api.budget.getNotifications.query();
+    const pending = notifications.filter((n) => n.notificationType === "request" &&
+        n.status === ExtendedApprovalStatus.PENDING_APPROVAL &&
+        n.type === ExtendedApprovalType.BUDGET &&
+        (n.budgetId === budgetId ||
+            n.budget?.id === budgetId));
+    const approval = pending[0];
+    if (!approval) {
+        throw new Error("No pending budget approval found for this budget and approver.");
+    }
+    await api.budget.updateBudgetApproval.mutate({
+        budgetApprovalId: approval.id,
+        status: ExtendedApprovalStatus.APPROVED,
+    });
+    out({ success: true, message: "Budget approved successfully" });
+}
+export async function rejectBudget(budgetId, reason) {
+    const notifications = await api.budget.getNotifications.query();
+    const pending = notifications.filter((n) => n.notificationType === "request" &&
+        n.status === ExtendedApprovalStatus.PENDING_APPROVAL &&
+        n.type === ExtendedApprovalType.BUDGET &&
+        (n.budgetId === budgetId ||
+            n.budget?.id === budgetId));
+    const approval = pending[0];
+    if (!approval) {
+        throw new Error("No pending budget approval found for this budget and approver.");
+    }
+    await api.budget.updateBudgetApproval.mutate({
+        budgetApprovalId: approval.id,
+        status: ExtendedApprovalStatus.REJECTED,
+        rejectionReason: reason,
+    });
+    out({ success: true, message: "Budget rejected" });
+}
+export async function getSupplierDetails(supplierId) {
+    const supplier = await api.supplier.getSupplierById.query({
+        id: supplierId,
+    });
+    out(supplier);
+}
+export async function approveSupplier(supplierId) {
+    const notifications = await api.budget.getNotifications.query();
+    const pending = notifications.filter((n) => n.notificationType === "request" &&
+        n.status === ExtendedApprovalStatus.PENDING_APPROVAL &&
+        n.type === ExtendedApprovalType.SUPPLIER &&
+        (n.supplierId === supplierId || n.supplier?.id === supplierId));
+    const approval = pending[0];
+    if (!approval) {
+        throw new Error("No pending supplier approval found.");
+    }
+    await api.supplier.updateSupplierApproval.mutate({
+        supplierApprovalId: approval.id,
+        status: ExtendedApprovalStatus.APPROVED,
+    });
+    out({ success: true, message: "Supplier approved successfully" });
+}
+export async function rejectSupplier(supplierId, reason) {
+    const notifications = await api.budget.getNotifications.query();
+    const pending = notifications.filter((n) => n.notificationType === "request" &&
+        n.status === ExtendedApprovalStatus.PENDING_APPROVAL &&
+        n.type === ExtendedApprovalType.SUPPLIER &&
+        (n.supplierId === supplierId || n.supplier?.id === supplierId));
+    const approval = pending[0];
+    if (!approval) {
+        throw new Error("No pending supplier approval found.");
+    }
+    await api.supplier.updateSupplierApproval.mutate({
+        supplierApprovalId: approval.id,
+        status: ExtendedApprovalStatus.REJECTED,
+        rejectionReason: reason,
+    });
+    out({ success: true, message: "Supplier rejected" });
+}
+export async function rejectBill(billId, reason) {
+    const notifications = await api.budget.getNotifications.query();
+    const pending = notifications.filter((n) => n.notificationType === "request" &&
+        n.status === ExtendedApprovalStatus.PENDING_APPROVAL &&
+        n.type === ExtendedApprovalType.BILL &&
+        (n.billId === billId || n.bill?.id === billId));
+    const approval = pending[0];
+    if (!approval) {
+        throw new Error("No pending bill approval found.");
+    }
+    await api.bill.updateApproval.mutate({
+        billApprovalId: approval.id,
+        status: ExtendedApprovalStatus.REJECTED,
+        rejectionReason: reason,
+    });
+    out({ success: true, message: "Bill rejected" });
+}
+// --- Companies & projects ---
+export async function listCompanies(opts) {
+    const result = await api.company.getCompanies.query({
+        name: opts.name,
+        createdBy: opts.createdBy,
+        page: opts.page ?? 1,
+        perPage: opts.perPage ?? 20,
+    });
+    out(result);
+}
+export async function getCompany(id) {
+    const company = await api.company.getCompanyById.query({ id });
+    out(company);
+}
+export async function createCompany(opts) {
+    const result = await api.company.createCompany.mutate(opts);
+    out(result);
+}
+export async function listProjects(opts) {
+    const result = await api.project.getAllProjects.query({
+        companyId: opts.companyId,
+        name: opts.name,
+        status: opts.status,
+        page: opts.page ?? 1,
+        perPage: opts.perPage ?? 20,
+    });
+    out(result);
+}
+export async function getProject(id) {
+    const [project, budgetsOverview, billsOverview] = await Promise.all([
+        api.project.getProjectDetailsById.query({ id }),
+        api.project.getProjectBudgetsOverview.query({ projectId: id }),
+        api.project.getProjectBillsOverview.query({ projectId: id }),
+    ]);
+    out({ project, budgetsOverview, billsOverview });
+}
+export async function createProject(opts) {
+    const result = await api.project.createProject.mutate({
+        name: opts.name,
+        description: opts.description,
+        companyId: opts.companyId,
+        contactPersonId: opts.contactPersonId,
+        dateRange: {
+            from: new Date(opts.startDate),
+            to: opts.endDate ? new Date(opts.endDate) : undefined,
+        },
+    });
+    out(result);
+}
+export async function updateProjectStatus(id, status) {
+    const result = await api.project.updateProjectStatus.mutate({ id, status });
+    out(result);
+}
+// --- Contacts ---
+export async function listContacts(companyId) {
+    const contacts = await api.contactPerson.getContactPersonByCompanyId.query({
+        companyId,
+    });
+    out(contacts);
+}
+// --- Items ---
+export async function listItems(opts) {
+    const result = await api.item.getItems.query({
+        page: opts.page ?? 1,
+        perPage: opts.perPage ?? 20,
+        name: opts.name,
+    });
+    out(result);
+}
+export async function getItem(id) {
+    const item = await api.item.getItem.query({ id });
+    out(item);
+}
+export async function listItemCategories(opts) {
+    const result = await api.itemCategory.getItemCategories.query({
+        page: opts.page ?? 1,
+        perPage: opts.perPage ?? 50,
+    });
+    out(result);
+}
+// --- Supplier analytics ---
+export async function getSupplierAnalytics(opts) {
+    const result = await api.dashboard.getSupplierTableData.query({
+        page: opts.page ?? 1,
+        perPage: opts.perPage ?? 20,
+        sort: [],
+        name: opts.name,
+        timeFrame: (opts.timeFrame ?? "ALL"),
+    });
+    out(result);
+}
+// --- Dashboard / analytics ---
+export async function listUsers() {
+    const users = await api.user.getAllUsers.query();
+    out(users);
+}
+export async function getUserPerformance(userId) {
+    const result = await api.dashboard.getUserPerformance.query({ userId });
+    out(result);
+}
+export async function getDashboard(input) {
+    const result = await api.dashboard.getDashboard.query({
+        userId: input.userId,
+        role: input.role ?? "ALL",
+        deals: input.deals ?? "ALL",
+        timeFrame: input.timeFrame ?? "ALL",
+        startDate: input.startDate,
+        endDate: input.endDate,
+    });
+    out(result);
+}
+export async function getFinancialOverview(input) {
+    const result = await api.dashboard.getFinancialOverview.query({
+        userId: input.userId,
+        role: input.role ?? BudgetRole.ALL,
+        deals: input.deals ?? Deals.ALL,
+        timeFrame: input.timeFrame ?? TimeFrame.ALL,
+        startDate: input.startDate,
+        endDate: input.endDate,
+    });
+    out(result);
+}
+// --- Error logs ---
+export async function getRecentErrors(opts) {
+    const result = await api.errorLog.getRecentErrors.query({
+        page: opts.page ?? 1,
+        perPage: opts.perPage ?? 10,
+        severity: opts.severity,
+        status: opts.status,
+    });
+    out(result);
+}
+export async function getErrorMetrics() {
+    const result = await api.errorLog.getErrorMetrics.query({});
+    out(result);
+}
+// --- Historical / benchmarks ---
+export async function getApprovedBudgets(opts) {
+    const perPage = Math.min(opts.limit ?? 50, 100);
+    const { budgets, totalCount } = await api.budget.getAllBudgets.query({
+        projectId: opts.projectId,
+        statuses: [
+            ExtendedBudgetStatus.APPROVED,
+            ExtendedBudgetStatus.ESTIMATE_ACCEPTED,
+            ExtendedBudgetStatus.ESTIMATE_CLOSED,
+        ],
+        page: 1,
+        perPage,
+    });
+    const items = (budgets ?? []).map((b) => {
+        const calc = b;
+        const revenue = calc.totalSellingAfterDiscount ?? 0;
+        const cost = calc.totalCostWithoutGst ?? 0;
+        const gp = calc.gpPercentage ?? 0;
+        const date = b.date instanceof Date ? b.date.toISOString() : String(b.date);
+        const createdAt = b.createdAt instanceof Date
+            ? b.createdAt.toISOString()
+            : String(b.createdAt);
+        return {
+            id: b.id,
+            name: b.name,
+            categoryId: b.categoryId,
+            company: b.project?.company?.name,
+            date,
+            pax: b.pax,
+            revenue: Number(revenue.toFixed(2)),
+            cost: Number(cost.toFixed(2)),
+            gpPercentage: Number(gp.toFixed(2)),
+            createdAt,
+        };
+    });
+    let filtered = items;
+    if (opts.minRevenue != null) {
+        const minR = opts.minRevenue;
+        filtered = filtered.filter((i) => i.revenue >= minR);
+    }
+    if (opts.maxRevenue != null) {
+        const maxR = opts.maxRevenue;
+        filtered = filtered.filter((i) => i.revenue <= maxR);
+    }
+    out({ budgets: filtered, count: filtered.length, totalCount });
+}
+export async function getBudgetCategoryBenchmarks(opts) {
+    const result = await api.budget.getBudgetCategoryBenchmarks.query({
+        categoryId: opts.categoryId,
+        limit: opts.limit ?? 100,
+    });
+    out(result);
+}
+export async function getItemPricingHistory(opts) {
+    const result = await api.budget.getItemPricingHistory.query({
+        itemName: opts.itemName,
+        categoryId: opts.categoryId,
+        supplierId: opts.supplierId,
+        limit: opts.limit ?? 100,
+    });
+    out(result);
+}
+export async function getSupplierPricingHistory(opts) {
+    const result = await api.budget.getSupplierPricingHistory.query({
+        supplierId: opts.supplierId,
+        itemCategoryId: opts.itemCategoryId,
+        limit: opts.limit ?? 100,
+    });
+    out(result);
+}

package/dist/filter-enums.js

@@ -0,0 +1,58 @@
+import { ApprovalStatus, ApprovalType, BillStatus, BudgetStatus, ErrorSeverity, ErrorStatus, EstimationMode, ProjectStatus, } from "@bb/db/enums";
+export const ExtendedApprovalStatus = {
+    ...ApprovalStatus,
+    ALL: "ALL",
+};
+export const ExtendedApprovalType = {
+    ...ApprovalType,
+    ALL: "ALL",
+};
+export const ExtendedProjectStatus = {
+    ...ProjectStatus,
+    ALL: "ALL",
+};
+export const ExtendedBudgetStatus = {
+    ...BudgetStatus,
+    ALL: "ALL",
+};
+export const ExtendedBillStatus = {
+    ...BillStatus,
+    ALL: "ALL",
+};
+export const ExtendedEstimationMode = {
+    ...EstimationMode,
+    ALL: "ALL",
+};
+export const BudgetRole = {
+    ALL: "ALL",
+    BD: "BD",
+    CREATOR: "CREATOR",
+    INSIDE_SALES: "INSIDE_SALES",
+};
+export const Deals = {
+    ALL: "ALL",
+    SUCCESSFUL: "SUCCESSFUL",
+    LOST: "LOST",
+};
+export const TimeFrame = {
+    ALL: "ALL",
+    LAST_YEAR: "LAST_YEAR",
+    LAST_6_MONTHS: "LAST_6_MONTHS",
+    LAST_3_MONTHS: "LAST_3_MONTHS",
+    CUSTOM: "CUSTOM",
+};
+export const ChartTimeFrame = {
+    LAST_30_DAYS: "last_30_days",
+    LAST_3_MONTHS: "last_3_months",
+    LAST_6_MONTHS: "last_6_months",
+    LAST_1_YEAR: "last_1_year",
+    ALL_TIME: "all_time",
+};
+export const ExtendedErrorSeverity = {
+    ALL: "ALL",
+    ...ErrorSeverity,
+};
+export const ExtendedErrorStatus = {
+    ALL: "ALL",
+    ...ErrorStatus,
+};