@go-labs-sg/bb 1.0.0

package/README.md

@@ -0,0 +1,114 @@
+# bb — Budget Builder CLI
+
+Lightweight CLI that wraps the same tRPC API used by the MCP server. For AI agents (e.g. Chuck/OpenClaw) that don’t support MCP: run `bb` from the shell and get JSON back.
+
+**Why no workspace refs in the published package?**  
+`workspace:*` only resolves inside your monorepo. When someone installs from npm (`npx @go-labs-sg/bb` or `npm i -g @go-labs-sg/bb`), their environment has no workspace, so the CLI is built with no runtime dependency on `@bb/api`, `@bb/db`, or `@bb/utils`. In the repo we keep `@bb/typescript-config` as a devDependency for typechecking; it is stripped from the tarball when publishing (or use a publish flow that omits workspace devDeps).
+
+## Auth
+
+- Set **`BB_API_KEY`** in the environment (same API key as MCP / Goracle > API Keys).
+- The CLI targets the production API at `https://budget-builder.getout.events`.
+
+## Usage
+
+From the monorepo root:
+
+```bash
+export BB_API_KEY=your_api_key
+bun run bb -- list-budgets
+bun run bb -- get-budget <id>
+bun run bb -- update-budget-status <id> <status>
+bun run bb -- list-bills
+bun run bb -- approve-bill <id>
+bun run bb -- list-approvals
+bun run bb -- list-suppliers
+```
+
+Or from `packages/cli`:
+
+```bash
+bun run src/index.ts list-budgets
+```
+
+## Commands
+
+| Command | Description |
+|--------|-------------|
+| `list-budgets` | List budgets. Optional: `--projectId`, `--name`, `--status` (comma-separated), `--page`, `--perPage` |
+| `get-budget <id>` | Budget details + line items |
+| `update-budget-status <id> <status>` | Set status (e.g. `APPROVED`, `REJECTED`) |
+| `list-bills` | List bills. Optional: `--projectId`, `--budgetId`, `--status`, `--page`, `--pageSize` |
+| `approve-bill <id>` | Approve a pending bill |
+| `list-approvals` | Pending approvals. Optional: `--type` (budget \| supplier \| bill \| all) |
+| `list-suppliers` | List suppliers. Optional: `--name`, `--page`, `--perPage` |
+
+Output is JSON to stdout. Errors go to stderr and exit code 1.
+
+## Install from npm (for agents without the repo)
+
+```bash
+npx @go-labs-sg/bb list-budgets
+# or
+npm install -g @go-labs-sg/bb
+bb list-budgets
+```
+
+Set `BB_API_KEY` in the environment before running.
+
+## Testing (local)
+
+1. **Create an API key** in the web app: Goracle → API Keys → Create MCP API Key. Copy the key (shown once).
+
+2. **Start the web app** (or use a deployed URL):
+   ```bash
+   bun run web:dev
+   ```
+
+3. **Set env and run** from monorepo root:
+   ```bash
+   export BB_API_KEY=your_copied_key
+   bun run bb -- list-budgets
+   bun run bb -- list-suppliers
+   ```
+
+4. **Verify JSON output** — you should see structured JSON on stdout. Errors go to stderr with exit code 1.
+
+   If you see `{"error":"Unable to connect..."}` — the production API may be unreachable or your network may be blocking the request.
+
+## Private publishing (npm)
+
+To publish privately:
+
+1. **Use a scoped package** (already `@go-labs-sg/bb`).
+
+2. **Set `publishConfig`** in `package.json`:
+   ```json
+   "publishConfig": {
+     "access": "restricted"
+   }
+   ```
+   (`restricted` = private for scoped packages; `public` = public)
+
+3. **Ensure you're logged in** to npm and have access to the `@go-labs-sg` org:
+   ```bash
+   npm login
+   npm org ls go-labs-sg  # verify access
+   ```
+
+4. **Publish** from the CLI package:
+   ```bash
+   cd packages/cli
+   npm publish
+   ```
+
+5. **For Chuck/OpenClaw** — install from your private registry:
+   ```bash
+   npm install -g @go-labs-sg/bb
+   # or
+   npx @go-labs-sg/bb list-budgets
+   ```
+
+   Set `BB_API_KEY` in the agent's environment.
+
+**Alternative: GitHub Packages** — use `@go-labs-sg/bb` with `registry: https://npm.pkg.github.com` and a `GITHUB_TOKEN` with `read:packages` / `write:packages`.

package/dist/api-client.d.ts

@@ -0,0 +1,5 @@
+import type { AppRouter } from "@bb/api";
+import { type CreateTRPCProxyClient } from "@trpc/client";
+export declare const api: CreateTRPCProxyClient<AppRouter>;
+export declare function requireApiKey(): string;
+//# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAGN,KAAK,qBAAqB,EAC1B,MAAM,cAAc,CAAC;AAetB,eAAO,MAAM,GAAG,EAAE,qBAAqB,CAAC,SAAS,CAgB/C,CAAC;AAEH,wBAAgB,aAAa,IAAI,MAAM,CAOtC"}

package/dist/api-client.js

@@ -0,0 +1,36 @@
+import { createTRPCProxyClient, httpBatchLink } from "@trpc/client";
+import SuperJSON from "superjson";
+const BASE_URL = "https://budget-builder.getout.events";
+function getAuthHeader() {
+    const key = process.env.BB_API_KEY;
+    if (!key?.trim())
+        return undefined;
+    return `Bearer ${key.trim()}`;
+}
+export const api = createTRPCProxyClient({
+    links: [
+        httpBatchLink({
+            url: `${BASE_URL}/api/trpc`,
+            transformer: SuperJSON,
+            headers: () => {
+                const headers = {
+                    "x-trpc-source": "bb-cli",
+                };
+                const auth = getAuthHeader();
+                if (auth)
+                    headers.Authorization = auth;
+                return headers;
+            },
+        }),
+    ],
+});
+export function requireApiKey() {
+    const key = process.env.BB_API_KEY?.trim();
+    if (!key) {
+        console.error(JSON.stringify({
+            error: "BB_API_KEY is required. Set it in the environment.",
+        }));
+        process.exit(1);
+    }
+    return key;
+}

package/dist/commands.d.ts

@@ -0,0 +1,28 @@
+import type { BudgetStatus } from "@bb/db/enums";
+import type { ExtendedBudgetStatus } from "@bb/utils/filter-enums";
+export declare function listBudgets(opts: {
+    projectId?: string;
+    name?: string;
+    statuses?: ExtendedBudgetStatus[];
+    page?: number;
+    perPage?: number;
+}): Promise<void>;
+export declare function getBudget(id: string): Promise<void>;
+export declare function updateBudgetStatus(budgetId: string, status: BudgetStatus): Promise<void>;
+export declare function listBills(opts: {
+    projectId?: string;
+    budgetId?: string;
+    status?: string;
+    page?: number;
+    pageSize?: number;
+}): Promise<void>;
+export declare function approveBill(billId: string): Promise<void>;
+export declare function listApprovals(opts: {
+    type?: string;
+}): Promise<void>;
+export declare function listSuppliers(opts: {
+    name?: string;
+    page?: number;
+    perPage?: number;
+}): Promise<void>;
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAWnE,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,oBAAoB,EAAE,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB;AAED,wBAAsB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMzD;AAED,wBAAsB,kBAAkB,CACvC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,GAClB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAehB;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmB/D;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA6C1E;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhB"}

package/dist/commands.js

@@ -0,0 +1,111 @@
+import { api } from "./api-client.js";
+const BUDGET = "BUDGET";
+const BILL = "BILL";
+const SUPPLIER = "SUPPLIER";
+const out = (data) => {
+    console.log(JSON.stringify(data, null, 2));
+};
+export async function listBudgets(opts) {
+    const input = {
+        projectId: opts.projectId,
+        name: opts.name,
+        statuses: opts.statuses,
+        page: opts.page ?? 1,
+        perPage: opts.perPage ?? 20,
+    };
+    const result = await api.budget.getAllBudgets.query(input);
+    out(result);
+}
+export async function getBudget(id) {
+    const [budget, items] = await Promise.all([
+        api.budget.getBudget.query({ id }),
+        api.budget.getBudgetItems.query({ budgetId: id }),
+    ]);
+    out({ budget, items });
+}
+export async function updateBudgetStatus(budgetId, status) {
+    const input = {
+        id: budgetId,
+        status: status,
+    };
+    const result = await api.budget.updateBudgetStatus.mutate(input);
+    out(result);
+}
+export async function listBills(opts) {
+    const input = {
+        projectId: opts.projectId,
+        budgetId: opts.budgetId,
+        status: opts.status,
+        page: opts.page ?? 1,
+        pageSize: opts.pageSize ?? 20,
+    };
+    const result = await api.bill.getAll.query(input);
+    out(result);
+}
+export async function approveBill(billId) {
+    const notifications = (await api.budget.getNotifications.query());
+    const pending = notifications.filter((n) => n.notificationType === "request" &&
+        n.status === "PENDING_APPROVAL" &&
+        n.type === BILL &&
+        (n.billId === billId || n.bill?.id === billId));
+    const approval = pending[0];
+    if (!approval) {
+        out({ error: "No pending bill approval found for this bill." });
+        process.exit(1);
+    }
+    const result = await api.bill.updateApproval.mutate({
+        billApprovalId: approval.id,
+        status: "APPROVED",
+    });
+    out({ ...result, success: true, message: "Bill approved" });
+}
+export async function listApprovals(opts) {
+    const notifications = (await api.budget.getNotifications.query());
+    const pending = notifications.filter((n) => n.notificationType === "request" && n.status === "PENDING_APPROVAL");
+    const typeUpper = opts.type?.toUpperCase();
+    const typeFilter = !opts.type || opts.type.toLowerCase() === "all"
+        ? () => true
+        : (n) => n.type === typeUpper;
+    const filtered = pending.filter(typeFilter);
+    const items = filtered.map((n) => {
+        let id;
+        let name;
+        if (n.type === BUDGET && n.budget) {
+            id = n.budgetId ?? n.id;
+            name = n.budget.name;
+        }
+        else if (n.type === BILL && n.bill) {
+            id = n.bill.id;
+            name = `Bill ${n.bill.invoiceNumber ?? n.bill.id.slice(0, 8)}`;
+        }
+        else if (n.type === SUPPLIER && n.supplier) {
+            id = n.supplier.id;
+            name = n.supplier.name;
+        }
+        else {
+            id = n.id;
+            name = "Unknown";
+        }
+        return {
+            approvalId: n.id,
+            type: n.type,
+            id,
+            name,
+            requestedBy: n.requester?.name ?? n.requester?.email ?? "Unknown",
+            requestedAt: typeof n.createdAt === "string"
+                ? n.createdAt
+                : n.createdAt instanceof Date
+                    ? n.createdAt.toISOString()
+                    : String(n.createdAt),
+        };
+    });
+    out({ items });
+}
+export async function listSuppliers(opts) {
+    const result = await api.supplier.getSuppliers.query({
+        page: opts.page ?? 1,
+        perPage: opts.perPage ?? 20,
+        name: opts.name,
+    });
+    out(result);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import "./load-env.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+import "./load-env.js";
+import { requireApiKey } from "./api-client.js";
+import { approveBill, getBudget, listApprovals, listBills, listBudgets, listSuppliers, updateBudgetStatus, } from "./commands.js";
+import { getFlag, parseArgs } from "./parse-args.js";
+const BUDGET_STATUSES = [
+    "DRAFT",
+    "PENDING_APPROVAL",
+    "APPROVED",
+    "REJECTED",
+    "ESTIMATE_CREATED",
+    "ESTIMATE_SENT",
+    "ESTIMATE_ACCEPTED",
+    "ESTIMATE_REJECTED",
+    "ESTIMATE_CLOSED",
+];
+function printHelp() {
+    const help = `
+bb — Budget Builder CLI (for AI agents / shell)
+
+Usage: bb <command> [options] [args]
+
+Auth: Set BB_API_KEY in the environment (same API key as MCP / Goracle).
+
+Commands:
+  list-budgets              List budgets (optional filters)
+    --projectId, --name, --status (comma-separated), --page, --perPage
+
+  get-budget <id>            Get budget details + line items
+
+  update-budget-status <id> <status>   Set budget status (e.g. APPROVED, REJECTED)
+    status: ${BUDGET_STATUSES.join(", ")}
+
+  list-bills                 List bills (optional filters)
+    --projectId, --budgetId, --status, --page, --pageSize
+
+  approve-bill <id>          Approve a pending bill
+
+  list-approvals             List pending approvals
+    --type  budget | supplier | bill | all
+
+  list-suppliers             List suppliers
+    --name, --page, --perPage
+
+Output: JSON to stdout. Errors to stderr and exit code 1.
+`;
+    console.log(help.trim());
+}
+async function main() {
+    const { command, positional, flags } = parseArgs(process.argv);
+    if (!command || command === "help" || flags["help"] === true) {
+        printHelp();
+        process.exit(0);
+    }
+    requireApiKey();
+    try {
+        switch (command) {
+            case "list-budgets": {
+                const statusStr = getFlag(flags, "status");
+                await listBudgets({
+                    projectId: getFlag(flags, "projectId"),
+                    name: getFlag(flags, "name"),
+                    statuses: statusStr !== undefined
+                        ? String(statusStr)
+                            .split(",")
+                            .map((s) => s.trim())
+                        : undefined,
+                    page: getFlag(flags, "page", (s) => Number.parseInt(s, 10)),
+                    perPage: getFlag(flags, "perPage", (s) => Number.parseInt(s, 10)),
+                });
+                break;
+            }
+            case "get-budget": {
+                const id = positional[0];
+                if (!id) {
+                    console.error(JSON.stringify({ error: "get-budget requires <id>" }));
+                    process.exit(1);
+                }
+                await getBudget(id);
+                break;
+            }
+            case "update-budget-status": {
+                const [id, status] = positional;
+                if (!id || !status) {
+                    console.error(JSON.stringify({
+                        error: "update-budget-status requires <id> <status>",
+                    }));
+                    process.exit(1);
+                }
+                if (!BUDGET_STATUSES.includes(status)) {
+                    console.error(JSON.stringify({
+                        error: `Invalid status. Use one of: ${BUDGET_STATUSES.join(", ")}`,
+                    }));
+                    process.exit(1);
+                }
+                await updateBudgetStatus(id, status);
+                break;
+            }
+            case "list-bills": {
+                await listBills({
+                    projectId: getFlag(flags, "projectId"),
+                    budgetId: getFlag(flags, "budgetId"),
+                    status: getFlag(flags, "status"),
+                    page: getFlag(flags, "page", (s) => Number.parseInt(s, 10)),
+                    pageSize: getFlag(flags, "pageSize", (s) => Number.parseInt(s, 10)),
+                });
+                break;
+            }
+            case "approve-bill": {
+                const id = positional[0];
+                if (!id) {
+                    console.error(JSON.stringify({ error: "approve-bill requires <id>" }));
+                    process.exit(1);
+                }
+                await approveBill(id);
+                break;
+            }
+            case "list-approvals": {
+                await listApprovals({
+                    type: getFlag(flags, "type"),
+                });
+                break;
+            }
+            case "list-suppliers": {
+                await listSuppliers({
+                    name: getFlag(flags, "name"),
+                    page: getFlag(flags, "page", (s) => Number.parseInt(s, 10)),
+                    perPage: getFlag(flags, "perPage", (s) => Number.parseInt(s, 10)),
+                });
+                break;
+            }
+            default: {
+                console.error(JSON.stringify({
+                    error: `Unknown command: ${command}. Run 'bb help'.`,
+                }));
+                process.exit(1);
+            }
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(JSON.stringify({ error: message }));
+        process.exit(1);
+    }
+}
+main();

package/dist/load-env.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=load-env.d.ts.map

package/dist/load-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-env.d.ts","sourceRoot":"","sources":["../src/load-env.ts"],"names":[],"mappings":""}

package/dist/load-env.js

@@ -0,0 +1,6 @@
+/**
+ * Load .env from current working directory so BB_API_KEY is available.
+ */
+import path from "node:path";
+import { config } from "dotenv";
+config({ path: path.resolve(process.cwd(), ".env") });

package/dist/parse-args.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Minimal argv parser for bb CLI.
+ * Supports: command [positional...] [--key=value] [--key value]
+ */
+export declare function parseArgs(argv: string[]): {
+    command: string;
+    positional: string[];
+    flags: Record<string, string | true>;
+};
+export declare function getFlag<T extends string | number>(flags: Record<string, string | true>, key: string, parse?: (s: string) => T): T | undefined;
+//# sourceMappingURL=parse-args.d.ts.map

package/dist/parse-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-args.d.ts","sourceRoot":"","sources":["../src/parse-args.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CACrC,CA8BA;AAED,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,EAChD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,EACpC,GAAG,EAAE,MAAM,EACX,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,CAAC,GACtB,CAAC,GAAG,SAAS,CAIf"}

package/dist/parse-args.js

@@ -0,0 +1,43 @@
+/**
+ * Minimal argv parser for bb CLI.
+ * Supports: command [positional...] [--key=value] [--key value]
+ */
+export function parseArgs(argv) {
+    const args = argv.slice(2); // drop node and script
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === undefined || arg === "--" || arg === "")
+            continue;
+        if (arg.startsWith("--")) {
+            const eq = arg.indexOf("=");
+            if (eq > 0) {
+                flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+            }
+            else {
+                // --flag or --flag value
+                const key = arg.slice(2);
+                const next = args[i + 1];
+                if (next !== undefined && !next.startsWith("--")) {
+                    flags[key] = next;
+                    i++;
+                }
+                else {
+                    flags[key] = true;
+                }
+            }
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    const command = positional[0] ?? "";
+    return { command, positional: positional.slice(1), flags };
+}
+export function getFlag(flags, key, parse) {
+    const v = flags[key];
+    if (v === undefined || v === true)
+        return undefined;
+    return parse ? parse(v) : v;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@go-labs-sg/bb",
+  "version": "1.0.0",
+  "description": "Budget Builder CLI — list budgets, bills, approvals, suppliers; approve bills; change status. For AI agents (e.g. Chuck/OpenClaw).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "bb": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "check": "biome check .",
+    "check:write": "biome check --write .",
+    "run": "bun run src/index.ts",
+    "prepublishOnly": "node scripts/strip-workspace-deps.js && bun run build",
+    "postpublish": "node scripts/restore-package-json.js"
+  },
+  "dependencies": {
+    "@trpc/client": "^11.10.0",
+    "dotenv": "^17.2.4",
+    "superjson": "^2.2.6"
+  },
+  "devDependencies": {},
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/go-labs-sg/budget-builder",
+    "directory": "packages/cli"
+  }
+}