@go-labs-sg/bb 2.28.0 → 2.30.0

package/README.md

@@ -230,6 +230,10 @@ commands return a conflict until delivery becomes `SENT` or `FAILED`.
 
 Every canonical command is classified by effect: `state-change`, `email`, `external-write`, `delete`, and/or `financial-write`. Interactive runs require one exact `CONFIRM`. Non-interactive runs require the corresponding flags (`--allow-state-change`, `--allow-email`, `--allow-external-write`, `--allow-delete`, and `--allow-financial-write`); commands with multiple effects require every matching flag. Agents must still get user confirmation in chat first—the runtime gate is not user authorization.
 
+**Draft-only bills:** Use `bb bill create --draft-only --payload '<bill-json>' --allow-state-change --allow-financial-write` when the user authorizes a draft only. The equivalent payload field is `draftOnly: true`. This creates `DRAFT` for every role, without auto-checking, auto-approval, approval requests, emails, or QuickBooks writes. It cannot be combined with `alreadyPaid: true`; conflicting flag and payload values are rejected. Draft-only creation uses the dedicated `bill.createDraft` API route and fails on older servers without falling back to ordinary creation. Deploy backend support before releasing the updated CLI. Reconciled projects must be moved to Won separately before draft-only creation, because reopening a project can trigger external integrations. Completed projects retain their existing creation restriction.
+
+Bill creation determines its required permissions from the parsed input, for both canonical and legacy commands. Ordinary unpaid creation requires state-change, financial-write, and external-write permissions, but no email permission. Already-paid creation also requires email permission. Without draft-only mode, existing role behavior remains: ordinary users create drafts, Accounting creates checked bills, and Admin creates approved bills and writes to QuickBooks. Ordinary creation can also adjust existing QuickBooks placeholder bills. Explicit drafts defer those adjustments until the later approval/QuickBooks workflow. When later authorized to submit the draft, use `bb bill approval create <billId>` with its state-change and email permissions; Admin-created drafts also enter finance review through this command. The static command catalog lists the union of possible effects.
+
 **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:** Legacy flat commands retain their additional interactive `yes` prompt when the current budget is locked. Canonical v2 commands use the single effect-aware confirmation gate; non-interactive execution requires `--allow-state-change` plus any other effects declared for that command.
@@ -337,3 +341,11 @@ bun run pack:artifact
 `pack:artifact` copies only the publish allowlist into a temporary staging directory and writes a sanitized publish manifest there. It never edits the source `package.json`, and the staged archive contains no workspace-only development dependencies. The release workflow packs once, validates the resulting archive, smoke-tests that exact tarball under Bun 1.4, then publishes that exact tarball. Types from `@go-labs/budget-builder-api` are compile-time only (`import type`). Prisma enum **values** used at runtime live in `src/prisma-enums.ts` (kept in sync with `packages/budget-builder/db` generated enums) so npm installs do not need `@go-labs/budget-builder-db`.
 
 The generated `command-reference.md` and `command-manifest.json` are release artifacts. Regenerate them whenever the command registry changes; the release workflow rejects a tarball that does not include both files.
+
+### Customer invoice lifecycle filters
+
+`bb customer-invoice list --status SENT` filters by the displayed invoice lifecycle.
+The list also accepts `PARTIALLY_SENT`, `PARTIALLY_PAID`, `PAID`, and `VOIDED`,
+alongside existing approval states such as `APPROVED` and `PENDING_APPROVAL`.
+`--sortBy status` sorts by lifecycle; `lifecycleStatus` in list/detail output is
+separate from the stored approval/operational `status`.

package/command-manifest.json

@@ -2063,7 +2063,7 @@
 	{
 		"path": ["bill", "create"],
 		"legacyAliases": ["create-bill", "create_bill"],
-		"summary": "Create a bill or claim with an approved supplier.",
+		"summary": "Create a bill or claim with an approved supplier. --draft-only guarantees DRAFT without email or external writes; otherwise unpaid creation skips email permission but keeps external-write permission.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -2104,6 +2104,10 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--draft-only",
+				"description": "Create a draft for every role; no approval, email, or QuickBooks writes. Conflicts with alreadyPaid: true."
 			}
 		],
 		"argumentMode": "legacy-passthrough",

package/command-reference.md

@@ -347,7 +347,7 @@ Effects: state-change, email.
 
 ## `bb bill create`
 
-Create a bill or claim with an approved supplier.
+Create a bill or claim with an approved supplier. --draft-only guarantees DRAFT without email or external writes; otherwise unpaid creation skips email permission but keeps external-write permission.
 
 Legacy aliases: `create-bill`, `create_bill`.
 

package/dist/index.js

@@ -19681,6 +19681,14 @@ var ErrorStatus = {
   RESOLVED: "RESOLVED",
   IGNORED: "IGNORED"
 };
+var CustomerInvoiceBatchStatus = {
+  CREATING: "CREATING",
+  PENDING_APPROVAL: "PENDING_APPROVAL",
+  APPROVED: "APPROVED",
+  REJECTED_VOIDED: "REJECTED_VOIDED",
+  EXPIRED_VOIDED: "EXPIRED_VOIDED",
+  PARTIAL_QBO_FAILURE: "PARTIAL_QBO_FAILURE"
+};
 var BillStatus = {
   DRAFT: "DRAFT",
   PENDING_APPROVAL: "PENDING_APPROVAL",
@@ -19742,6 +19750,16 @@ var ExtendedErrorStatus = {
   ...ErrorStatus
 };
 
+// ../utils/src/customer-invoice-lifecycle.ts
+var customerInvoiceLifecycleStatuses = [
+  ...Object.values(CustomerInvoiceBatchStatus),
+  "PARTIALLY_SENT",
+  "SENT",
+  "PARTIALLY_PAID",
+  "PAID",
+  "VOIDED"
+];
+
 // src/prisma-enums.ts
 var ProjectStatus2 = {
   PITCH: "PITCH",
@@ -19757,14 +19775,6 @@ var SupplierQuotationStatus = {
   REJECTED: "REJECTED",
   SUPERSEDED: "SUPERSEDED"
 };
-var CustomerInvoiceBatchStatus = {
-  CREATING: "CREATING",
-  PENDING_APPROVAL: "PENDING_APPROVAL",
-  APPROVED: "APPROVED",
-  REJECTED_VOIDED: "REJECTED_VOIDED",
-  EXPIRED_VOIDED: "EXPIRED_VOIDED",
-  PARTIAL_QBO_FAILURE: "PARTIAL_QBO_FAILURE"
-};
 var BudgetStatus2 = {
   DRAFT: "DRAFT",
   PENDING_APPROVAL: "PENDING_APPROVAL",
@@ -19797,7 +19807,7 @@ var BUDGET_STATUS_VALUES = new Set(Object.values(BudgetStatus2));
 var BILL_STATUS_VALUES = new Set(Object.values(BillStatus2));
 var PROJECT_STATUS_VALUES = new Set(Object.values(ProjectStatus2));
 var SUPPLIER_QUOTATION_STATUS_VALUES = new Set(Object.values(SupplierQuotationStatus));
-var CUSTOMER_INVOICE_BATCH_STATUS_VALUES = new Set(Object.values(CustomerInvoiceBatchStatus));
+var CUSTOMER_INVOICE_LIFECYCLE_STATUS_VALUES = new Set(customerInvoiceLifecycleStatuses);
 var USER_ROLE_VALUES = new Set(Object.values(UserRole));
 var EXTENDED_PROJECT_STATUS_VALUES = new Set(Object.values(ExtendedProjectStatus));
 var DASHBOARD_ROLE_VALUES = new Set([
@@ -20023,8 +20033,8 @@ function parseCommaSeparatedCustomerInvoiceStatuses(raw) {
   if (parts.length === 0)
     return;
   for (const status of parts) {
-    if (!CUSTOMER_INVOICE_BATCH_STATUS_VALUES.has(status)) {
-      throw new Error(`Invalid customer invoice status "${status}". Use one of: ${[...CUSTOMER_INVOICE_BATCH_STATUS_VALUES].join(", ")}.`);
+    if (!CUSTOMER_INVOICE_LIFECYCLE_STATUS_VALUES.has(status)) {
+      throw new Error(`Invalid customer invoice status "${status}". Use one of: ${[...CUSTOMER_INVOICE_LIFECYCLE_STATUS_VALUES].join(", ")}.`);
     }
   }
   return parts;
@@ -20249,7 +20259,7 @@ var billAttachment = (x, i, field = "attachments") => {
     size: Number(a.size)
   };
 };
-function parseCreateBillPayload(raw) {
+function parseCreateBillPayload(raw, draftOnlyFlag) {
   const o = requireObject(raw, "create-bill payload");
   const isClaimable = o.isClaimable;
   if (typeof isClaimable !== "boolean") {
@@ -20261,7 +20271,18 @@ function parseCreateBillPayload(raw) {
   }
   const attachmentsRaw = o.attachments;
   const attachments = Array.isArray(attachmentsRaw) ? attachmentsRaw.map((x, i) => billAttachment(x, i)) : [];
+  const draftOnlyRaw = o.draftOnly;
+  if (draftOnlyRaw !== undefined && typeof draftOnlyRaw !== "boolean") {
+    throw new Error("create-bill payload.draftOnly must be boolean.");
+  }
+  if (draftOnlyFlag !== undefined && draftOnlyRaw !== undefined && draftOnlyFlag !== draftOnlyRaw) {
+    throw new Error("--draft-only conflicts with payload.draftOnly.");
+  }
+  const draftOnly = draftOnlyFlag ?? draftOnlyRaw;
   const alreadyPaidRaw = o.alreadyPaid;
+  if (draftOnly && alreadyPaidRaw === true) {
+    throw new Error("Draft-only creation cannot be combined with alreadyPaid: true.");
+  }
   if (alreadyPaidRaw !== undefined && alreadyPaidRaw !== null && typeof alreadyPaidRaw !== "boolean") {
     throw new Error("create-bill payload.alreadyPaid must be boolean.");
   }
@@ -20305,6 +20326,7 @@ function parseCreateBillPayload(raw) {
     isClaimable,
     attachments,
     alreadyPaid: alreadyPaidRaw ?? undefined,
+    draftOnly,
     paymentReference: optionalString(o.paymentReference),
     paymentProofAttachments,
     extractedSupplierName: optionalString(o.extractedSupplierName),
@@ -20317,8 +20339,12 @@ function parseCreateBillPayload(raw) {
 }
 function parseUpdateBillPayload(raw) {
   const o = requireObject(raw, "update-bill payload");
+  const { draftOnly, ...input2 } = parseCreateBillPayload(raw);
+  if (draftOnly !== undefined) {
+    throw new Error("draftOnly is only supported when creating a bill.");
+  }
   return {
-    ...parseCreateBillPayload(raw),
+    ...input2,
     id: requiredString(o.id, "update-bill payload.id")
   };
 }
@@ -22020,9 +22046,24 @@ async function deleteItemCategoriesByIds(ids) {
   const result = await api2.itemCategory.deleteItemCategories.mutate({ ids });
   out(result);
 }
-async function createBillFromPayload(raw) {
-  const input2 = parseCreateBillPayload(raw);
-  const result = await api2.bill.create.mutate(input2);
+async function createBillFromPayload(raw, draftOnlyFlag) {
+  const input2 = parseCreateBillPayload(raw, draftOnlyFlag);
+  await confirmCurrentCommand({
+    action: input2.draftOnly ? "bill create (draft only)" : "bill create",
+    target: `project ${input2.projectId}, supplier ${input2.supplierId}`,
+    effects: [
+      "state-change",
+      "financial-write",
+      ...input2.draftOnly ? [] : ["external-write"],
+      ...input2.alreadyPaid ? ["email"] : []
+    ],
+    details: input2.draftOnly ? "Create a DRAFT bill without approval, email, or QuickBooks writes." : "Uses the caller's normal bill creation workflow; Accounting auto-checks and Admin auto-approves unpaid bills."
+  });
+  const result = input2.draftOnly ? await api2.bill.createDraft.mutate({
+    ...input2,
+    draftOnly: true,
+    alreadyPaid: false
+  }) : await api2.bill.create.mutate(input2);
   out(result);
 }
 async function listQuotations(opts) {
@@ -23179,7 +23220,7 @@ var summaryFor = (legacyTarget) => {
   if (legacyTarget === "whoami")
     return "Show the active API-key identity.";
   if (legacyTarget === "create-bill") {
-    return "Create a bill or claim with an approved supplier.";
+    return "Create a bill or claim with an approved supplier. --draft-only guarantees DRAFT without email or external writes; otherwise unpaid creation skips email permission but keeps external-write permission.";
   }
   if (legacyTarget === "validate-bill-selection") {
     return "Validate the approved supplier and selected bill line items.";
@@ -23287,7 +23328,12 @@ var registry2 = [
   legacyCommand("list-bills", ["bill", "list"]),
   legacyCommand("list-claims", ["claim", "list"]),
   legacyCommand("create-bill-approval", ["bill", "approval", "create"]),
-  legacyCommand("create-bill", ["bill", "create"]),
+  legacyCommand("create-bill", ["bill", "create"], [], [
+    {
+      name: "--draft-only",
+      description: "Create a draft for every role; no approval, email, or QuickBooks writes. Conflicts with alreadyPaid: true."
+    }
+  ]),
   legacyCommand("validate-bill-selection", ["bill", "selection", "validate"]),
   legacyCommand("update-bill", ["bill", "update"]),
   legacyCommand("update-bill-payment-evidence", [
@@ -23833,7 +23879,7 @@ Bills
     isClaimable differentiates the shared bill/claim records: false = bill, true = claim.
   Non-legacy supplier bills from 1 Jul 2026 00:00 SGT require approved quotation coverage linked to every selected line item, independent of the bill supplier, including already-paid bills.
   create-bill-approval <billId>       (also queues approval request emails)
-  create-bill                --payload '<json>'  (bill.create; payload.isClaimable false = bill, true = claim; supplier must be APPROVED)
+  create-bill                --payload '<json>' [--draft-only]  (bill.create; payload.isClaimable false = bill, true = claim; supplier must be APPROVED)
   validate-bill-selection    --payload '<json>'  Require an APPROVED supplier, then verify approved quotation links for each budgetItemId; alreadyPaid never bypasses quotation checks.
   stage-bill-attachment <projectId> <filePath...> [--file <path>] [--files <csv>]   Upload files before create-bill; returns attachment JSON for attachments/paymentProofAttachments
   cleanup-staged-bill-attachments <projectId> --keys <csv>   Delete unattached staged bill/claim uploads.
@@ -24318,7 +24364,7 @@ Waiting for approval\u2026
       }
       configureAccessToken(accessToken);
     }
-    if (!resolvedCommand.isLegacyAlias && resolvedCommand.command.effects.length > 0) {
+    if (!resolvedCommand.isLegacyAlias && cmd !== "create-bill" && resolvedCommand.command.effects.length > 0) {
       await confirmCurrentCommand({
         action: resolvedCommand.command.path.join(" "),
         target: commandConfirmationTarget(resolvedCommand),
@@ -24685,7 +24731,8 @@ Waiting for approval\u2026
           throw new Error("create-bill requires --payload '<json>'");
         }
         const raw = parseJsonFlag(String(payloadRaw), "--payload");
-        await createBillFromPayload(raw);
+        const draftOnly = flags["draft-only"] === true ? true : parseOptionalBoolFlag(flags, "draft-only");
+        await createBillFromPayload(raw, draftOnly);
         break;
       }
       case "validate-bill-selection": {

package/package.json

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

package/role-aware-agent-guide.md

@@ -129,6 +129,8 @@ The following distinctions are especially important:
 - Project Hub setup and sync are asynchronous external writes. Read `bb project hub status <project-id>` first, obtain explicit approval, and request the mutation once instead of repeatedly queueing it. Setup readiness remains visible through `status`; commercial sync returns an outbox operation ID for Admin diagnostics.
 - Bill/claim status commands have separate role rules for `CHECKED`, `APPROVED`, and `PAID`.
 - `bb bill create --payload` uses `isClaimable=false`; `isClaimable=true` creates a claim. Claims intentionally permit some base-user flows that supplier bills do not.
+- For a draft-only bill or claim, use `bb bill create --draft-only --payload` (or `draftOnly: true` in the payload). This forces `DRAFT` for every role and requires only `--allow-state-change --allow-financial-write`. It sends no approval/email and performs no QuickBooks writes. Do not combine it with `alreadyPaid: true`. An older API without `bill.createDraft` rejects the command; never retry with ordinary creation to bypass that error.
+- Ordinary unpaid creation does not require `--allow-email`, but remains role-dependent: Accounting auto-checks and Admin auto-approves. It still requires `--allow-external-write`, including for possible placeholder adjustments. Already-paid creation retains the email gate.
 - Staged attachments belong to the user in the database. Do not reuse, share, or manually construct staged keys.
 
 ## Handling authorization failures