@go-labs-sg/bb 3.1.0 → 3.2.0

package/command-manifest.json

@@ -2317,7 +2317,7 @@
 	{
 		"path": ["bill", "create"],
 		"legacyAliases": ["create-bill", "create_bill"],
-		"summary": "Create a bill or claim with an approved supplier. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. --draft-only guarantees DRAFT without email or external writes; otherwise unpaid creation skips email permission but keeps external-write permission.",
+		"summary": "Create a bill or claim with an approved supplier. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. If the selected quotations cannot split the bill amount across every selected line (a line without a quoted amount that cannot be derived from the quotation total), pass lineAmounts; updates that keep the same amount and lines reuse the existing line amounts. --draft-only guarantees DRAFT without email or external writes; otherwise unpaid creation skips email permission but keeps external-write permission.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -2375,7 +2375,7 @@
 	{
 		"path": ["bill", "selection", "validate"],
 		"legacyAliases": ["validate-bill-selection", "validate_bill_selection"],
-		"summary": "Validate the approved supplier and selected bill line items.",
+		"summary": "Validate the approved supplier and selected bill line items. Supplier bills need approved quotation sources (quotationIds, legacy quotationId, or quotationAllocations with lineAmounts) for every line that is not quotation-exempt (Go Internal lines, or projects/budgets created before the quotation cutoff). With billId, lines already on the bill keep their stored sources unless new sources are supplied. Exemption is decided by the server, so there is no --quotation-exempt flag here. Amounts (amount, lineAmounts, quotationAllocations) are ex-GST dollars with at most 2 decimal places.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -2491,7 +2491,7 @@
 	{
 		"path": ["bill", "update"],
 		"legacyAliases": ["update-bill", "update_bill"],
-		"summary": "Update a bill or claim with a partial payload including id; omitted fields are preserved. Comment-only updates are allowed on approved/paid bills without altering financial data or QuickBooks. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. Re-read and verify both amount fields and allocations after correcting a gross/net mistake.",
+		"summary": "Update a bill or claim with a partial payload including id; omitted fields are preserved. Comment-only updates are allowed on approved/paid bills without altering financial data or QuickBooks. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. If the selected quotations cannot split the bill amount across every selected line (a line without a quoted amount that cannot be derived from the quotation total), pass lineAmounts; updates that keep the same amount and lines reuse the existing line amounts. Re-read and verify both amount fields and allocations after correcting a gross/net mistake.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -10255,7 +10255,7 @@
 	{
 		"path": ["webhook", "delivery", "list"],
 		"legacyAliases": ["list-webhook-deliveries", "list_webhook_deliveries"],
-		"summary": "List webhook deliveries.",
+		"summary": "Admin-only: list webhook deliveries newest first. Returns { items, pageInfo }; follow pageInfo.nextCursor (or previousCursor with --direction backward). Cursors are opaque and filter-bound; raw delivery ids are rejected.",
 		"globalOptions": [
 			{
 				"name": "--help",
@@ -10296,6 +10296,30 @@
 			{
 				"name": "--allow-financial-write",
 				"description": "Allow financial-record changes in non-interactive use."
+			},
+			{
+				"name": "--endpointId <id>",
+				"description": "Only deliveries to this endpoint."
+			},
+			{
+				"name": "--status <PENDING|SUCCEEDED|FAILED,...>",
+				"description": "Comma-separated delivery statuses."
+			},
+			{
+				"name": "--eventType <type>",
+				"description": "Exact event type, e.g. bill.approved."
+			},
+			{
+				"name": "--limit <n>",
+				"description": "Rows per cursor page (1..100; default 20)."
+			},
+			{
+				"name": "--cursor <token>",
+				"description": "Opaque token from pageInfo.nextCursor or pageInfo.previousCursor; bound to the same filters."
+			},
+			{
+				"name": "--direction <value>",
+				"description": "forward or backward (default forward; backward requires cursor)."
 			}
 		],
 		"argumentMode": "legacy-passthrough",

package/command-reference.md

@@ -396,7 +396,7 @@ Effects: state-change, email.
 
 ## `bb bill create`
 
-Create a bill or claim with an approved supplier. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. --draft-only guarantees DRAFT without email or external writes; otherwise unpaid creation skips email permission but keeps external-write permission.
+Create a bill or claim with an approved supplier. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. If the selected quotations cannot split the bill amount across every selected line (a line without a quoted amount that cannot be derived from the quotation total), pass lineAmounts; updates that keep the same amount and lines reuse the existing line amounts. --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`.
 
@@ -409,7 +409,7 @@ Payload fields (--payload JSON)
 
 ## `bb bill selection validate`
 
-Validate the approved supplier and selected bill line items.
+Validate the approved supplier and selected bill line items. Supplier bills need approved quotation sources (quotationIds, legacy quotationId, or quotationAllocations with lineAmounts) for every line that is not quotation-exempt (Go Internal lines, or projects/budgets created before the quotation cutoff). With billId, lines already on the bill keep their stored sources unless new sources are supplied. Exemption is decided by the server, so there is no --quotation-exempt flag here. Amounts (amount, lineAmounts, quotationAllocations) are ex-GST dollars with at most 2 decimal places.
 
 Legacy aliases: `validate-bill-selection`, `validate_bill_selection`.
 
@@ -435,7 +435,7 @@ Payload fields (--payload JSON)
 
 ## `bb bill update`
 
-Update a bill or claim with a partial payload including id; omitted fields are preserved. Comment-only updates are allowed on approved/paid bills without altering financial data or QuickBooks. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. Re-read and verify both amount fields and allocations after correcting a gross/net mistake.
+Update a bill or claim with a partial payload including id; omitted fields are preserved. Comment-only updates are allowed on approved/paid bills without altering financial data or QuickBooks. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. If the selected quotations cannot split the bill amount across every selected line (a line without a quoted amount that cannot be derived from the quotation total), pass lineAmounts; updates that keep the same amount and lines reuse the existing line amounts. Re-read and verify both amount fields and allocations after correcting a gross/net mistake.
 
 Legacy aliases: `update-bill`, `update_bill`.
 
@@ -1657,7 +1657,7 @@ Effects: state-change.
 
 ## `bb webhook delivery list`
 
-List webhook deliveries.
+Admin-only: list webhook deliveries newest first. Returns { items, pageInfo }; follow pageInfo.nextCursor (or previousCursor with --direction backward). Cursors are opaque and filter-bound; raw delivery ids are rejected.
 
 Legacy aliases: `list-webhook-deliveries`, `list_webhook_deliveries`.
 

package/dist/index.js

@@ -7723,7 +7723,7 @@ var parseQuotationReferences = (input, commandName) => {
       const allocation = requireObject(raw, label);
       const amount = Number(allocation.amount);
       if (!Number.isFinite(amount) || amount < 0 || !Number.isInteger(amount * 100)) {
-        throw validationError(`${label}.amount must be a non-negative cent value.`);
+        throw validationError(`${label}.amount must be a non-negative dollar amount (ex-GST) with at most 2 decimal places.`);
       }
       return {
         budgetItemId: requiredString(allocation.budgetItemId, `${label}.budgetItemId`),
@@ -7776,7 +7776,7 @@ var parseBillLineAmounts = (input, commandName) => {
     const line = requireObject(raw, label);
     const amount = Number(line.amount);
     if (!Number.isFinite(amount) || amount < 0 || !Number.isInteger(amount * 100)) {
-      throw validationError(`${label}.amount must be a non-negative cent value.`);
+      throw validationError(`${label}.amount must be a non-negative dollar amount (ex-GST) with at most 2 decimal places.`);
     }
     return {
       budgetItemId: requiredString(line.budgetItemId, `${label}.budgetItemId`),
@@ -11473,6 +11473,8 @@ var summaryFor = (legacyTarget) => {
     return "List one cursor page of active item categories ({ items, pageInfo }; --limit/--cursor/--direction, optional --name/--sortBy/--sortDir). --page/--perPage are rejected.";
   if (legacyTarget === "count-item-categories")
     return "Count active item categories matching --name: { totalCount }.";
+  if (legacyTarget === "list-webhook-deliveries")
+    return "Admin-only: list webhook deliveries newest first. Returns { items, pageInfo }; follow pageInfo.nextCursor (or previousCursor with --direction backward). Cursors are opaque and filter-bound; raw delivery ids are rejected.";
   if (legacyTarget === "list-integration-operations")
     return "List one cursor page of integration operations, newest first ({ items, pageInfo }; --limit/--cursor/--direction). --page/--perPage are rejected. Admin only.";
   if (legacyTarget === "count-integration-operations")
@@ -11491,17 +11493,17 @@ var summaryFor = (legacyTarget) => {
     return "Get budget details. Omit --includeInactive for active budgets only; --includeInactive is an Admin-only historical read.";
   }
   if (legacyTarget === "create-bill") {
-    return "Create a bill or claim with an approved supplier. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. --draft-only guarantees DRAFT without email or external writes; otherwise unpaid creation skips email permission but keeps external-write permission.";
+    return "Create a bill or claim with an approved supplier. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. If the selected quotations cannot split the bill amount across every selected line (a line without a quoted amount that cannot be derived from the quotation total), pass lineAmounts; updates that keep the same amount and lines reuse the existing line amounts. --draft-only guarantees DRAFT without email or external writes; otherwise unpaid creation skips email permission but keeps external-write permission.";
   }
   if (legacyTarget === "record-external-bill-payment")
     return "Record an already-made payment on an APPROVED bill or claim, with no email and no money transfer. Requires <billId> --paymentReference --paymentDate YYYY-MM-DD --paymentAccount <QBO account ID> [--paymentProof receipt.pdf]. Reuses settled QBO payment links or queues one dated payment from the selected account. Exact retries are safe; do not pay again while reconciliation is pending.";
   if (legacyTarget === "list-external-payment-accounts")
     return "List active QuickBooks bank and credit-card account IDs for recording external payments (admin only).";
   if (legacyTarget === "update-bill") {
-    return "Update a bill or claim with a partial payload including id; omitted fields are preserved. Comment-only updates are allowed on approved/paid bills without altering financial data or QuickBooks. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. Re-read and verify both amount fields and allocations after correcting a gross/net mistake.";
+    return "Update a bill or claim with a partial payload including id; omitted fields are preserved. Comment-only updates are allowed on approved/paid bills without altering financial data or QuickBooks. All amount fields exclude GST: amount is the portion billed; extractedAmount is the full invoice subtotal; lineAmounts and quotationAllocations also exclude GST. Example: 1800 + 162 GST = 1962 total requires amount=1800 and extractedAmount=1800 for a full bill. The CLI does not strip GST from input. If the selected quotations cannot split the bill amount across every selected line (a line without a quoted amount that cannot be derived from the quotation total), pass lineAmounts; updates that keep the same amount and lines reuse the existing line amounts. Re-read and verify both amount fields and allocations after correcting a gross/net mistake.";
   }
   if (legacyTarget === "validate-bill-selection") {
-    return "Validate the approved supplier and selected bill line items.";
+    return "Validate the approved supplier and selected bill line items. Supplier bills need approved quotation sources (quotationIds, legacy quotationId, or quotationAllocations with lineAmounts) for every line that is not quotation-exempt (Go Internal lines, or projects/budgets created before the quotation cutoff). With billId, lines already on the bill keep their stored sources unless new sources are supplied. Exemption is decided by the server, so there is no --quotation-exempt flag here. Amounts (amount, lineAmounts, quotationAllocations) are ex-GST dollars with at most 2 decimal places.";
   }
   if (legacyTarget === "create-quotation") {
     return 'Create a quotation with an approved supplier using --payload JSON. Include projectId, budgetId, supplierId, budgetItemIds, amountWithoutGst, gstAmount, and one uploaded attachment in attachments. Multiple budget items require lineAmounts: [{"budgetItemId":"<first-id>","amount":750},{"budgetItemId":"<second-id>","amount":450}], covering every selected budget-item ID exactly once and summing to amountWithoutGst. Amounts exclude GST; use gstAmount: 0 for no GST. Example: amountWithoutGst: 1200 with line amounts 750 and 450.';
@@ -12490,7 +12492,32 @@ var registry2 = [
   legacyCommand("delete-webhook-endpoint", ["webhook", "endpoint", "delete"]),
   legacyCommand("rotate-webhook-secret", ["webhook", "secret", "rotate"]),
   legacyCommand("send-webhook-test-event", ["webhook", "endpoint", "test"]),
-  legacyCommand("list-webhook-deliveries", ["webhook", "delivery", "list"]),
+  legacyCommand("list-webhook-deliveries", ["webhook", "delivery", "list"], [], [
+    {
+      name: "--endpointId <id>",
+      description: "Only deliveries to this endpoint."
+    },
+    {
+      name: "--status <PENDING|SUCCEEDED|FAILED,...>",
+      description: "Comma-separated delivery statuses."
+    },
+    {
+      name: "--eventType <type>",
+      description: "Exact event type, e.g. bill.approved."
+    },
+    {
+      name: "--limit <n>",
+      description: "Rows per cursor page (1..100; default 20)."
+    },
+    {
+      name: "--cursor <token>",
+      description: "Opaque token from pageInfo.nextCursor or pageInfo.previousCursor; bound to the same filters."
+    },
+    {
+      name: "--direction <value>",
+      description: "forward or backward (default forward; backward requires cursor)."
+    }
+  ]),
   legacyCommand("get-webhook-delivery", ["webhook", "delivery", "get"]),
   legacyCommand("replay-webhook-delivery", ["webhook", "delivery", "replay"]),
   legacyCommand("list-inbound-sources", ["inbound", "source", "list"], [], [
@@ -13544,7 +13571,7 @@ Webhooks (admin)
   delete-webhook-endpoint <endpointId>
   rotate-webhook-secret <endpointId> [--previousSecretTtlHours <0-168>]  (prints the new secret once)
   send-webhook-test-event <endpointId>
-  list-webhook-deliveries [--endpointId] [--status PENDING|SUCCEEDED|FAILED] [--eventType] [--cursor] [--limit]
+  list-webhook-deliveries [--endpointId] [--status <PENDING|SUCCEEDED|FAILED,...>] [--eventType] [--limit 1-100] [--cursor <token>] [--direction forward|backward]  (newest first; prints items + pageInfo)
   get-webhook-delivery <deliveryId>  (attempts with response codes)
   replay-webhook-delivery <deliveryId>  (same eventId, new attempt chain)
 
@@ -15922,14 +15949,22 @@ Waiting for approval\u2026
         break;
       }
       case "list-webhook-deliveries": {
-        const status = getFlag(flags, "status");
-        if (status && status !== "PENDING" && status !== "SUCCEEDED" && status !== "FAILED")
-          throw new Error("--status must be PENDING, SUCCEEDED or FAILED");
+        const statuses = (getFlag(flags, "status") ?? "").split(",").map((value) => value.trim()).filter(Boolean);
+        for (const status of statuses)
+          if (status !== "PENDING" && status !== "SUCCEEDED" && status !== "FAILED")
+            throw new Error("--status must be PENDING, SUCCEEDED or FAILED (comma-separated)");
+        const cursor = getFlag(flags, "cursor");
+        const direction = parseProjectDirection(getFlag(flags, "direction"));
+        if (direction === "backward" && !cursor)
+          throw new Error("--direction backward requires --cursor <token>.");
         await listWebhookDeliveries({
           endpointId: getFlag(flags, "endpointId"),
-          status,
+          ...statuses.length ? {
+            status: statuses
+          } : {},
           eventType: getFlag(flags, "eventType"),
-          cursor: getFlag(flags, "cursor"),
+          cursor,
+          direction,
           limit: parsePositiveIntFlag(getFlag(flags, "limit"), "--limit")
         });
         break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-labs-sg/bb",
-  "version": "3.1.0",
+  "version": "3.2.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",