@integrity-labs/xero-broker 0.1.9 → 0.1.11

package/README.md

@@ -27,6 +27,7 @@ has to a Xero write — there is no ungated lane to the same operation.
 | `xero.bill.create` | `write` | Creates a payable obligation |
 | `xero.bill.approve` | `write_high_risk` | Draft → approved is the gate before payment |
 | `xero.invoice.void` | `write_destructive` | Cannot be undone in Xero |
+| `xero.invoice.delete` | `write_destructive` | DRAFT/SUBMITTED only; cannot be undone |
 | `xero.contact.merge` | `write_destructive` | Irreversible |
 | `xero.bank_transaction.delete` | `write_destructive` | Audit-trail loss |
 

package/dist/index.js

@@ -21204,6 +21204,9 @@ var XERO_WRITE_VERBS = [
   "xero.bill.create",
   "xero.bill.approve",
   "xero.invoice.void",
+  // CS-1962: delete a DRAFT/SUBMITTED invoice or bill. Void covers AUTHORISED;
+  // until this an agent that raised a draft in error had no way to remove it.
+  "xero.invoice.delete",
   "xero.invoice.update",
   // CS-1779: the verb was BUILT and UNREACHABLE. `xero.invoice.create` has
   // existed since CS-1630 - it is in approval-core's ApprovalVerb union, the
@@ -21222,17 +21225,22 @@ var XERO_WRITE_VERBS = [
   // product in its catalogue, so its invoice lines are free text that never
   // depletes stock.
   "xero.item.create",
-  "xero.item.update"
+  "xero.item.update",
+  // CS-2000: repeating invoice templates. Without them a monthly retainer is
+  // raised and emailed by hand each month, and a template left in DRAFT or with
+  // auto-send off silently generates nothing.
+  "xero.repeating_invoice.create",
+  "xero.repeating_invoice.update"
 ];
 var verbSchema = external_exports.enum(XERO_WRITE_VERBS).describe(
-  "The Xero write operation to perform. One of: xero.payment.create (pay an invoice/bill \u2014 moves money), xero.bill.create (create a payable), xero.bill.approve (DRAFT/SUBMITTED \u2192 AUTHORISED), xero.invoice.void (irreversible), xero.invoice.update (edit line items / unit amounts / tax treatment on an existing invoice or bill), xero.invoice.create (raise an ACCREC customer/sales invoice - `reference` is REQUIRED and is the idempotency key), xero.contact.merge (irreversible), xero.bank_transaction.delete (irreversible), xero.manual_journal.create (post a multi-line GL entry \u2014 reclasses, accruals, corrections; debits must equal credits), xero.item.create (add an inventory item to the catalogue - `code` is REQUIRED and is the idempotency key), xero.item.update (edit an existing inventory item - only the fields you send change)."
+  "The Xero write operation to perform. One of: xero.payment.create (pay an invoice/bill \u2014 moves money), xero.bill.create (create a payable), xero.bill.approve (DRAFT/SUBMITTED \u2192 AUTHORISED), xero.invoice.void (irreversible; for an AUTHORISED invoice with no payments), xero.invoice.delete (irreversible; ONLY for a DRAFT or SUBMITTED invoice or bill - an AUTHORISED invoice must be voided instead, and a PAID one cannot be deleted or voided until its payments are removed; waits for human approval like every write), xero.invoice.update (edit line items / unit amounts / tax treatment on an existing invoice or bill), xero.invoice.create (raise an ACCREC customer/sales invoice - `reference` is REQUIRED and is the idempotency key), xero.contact.merge (irreversible), xero.bank_transaction.delete (irreversible), xero.manual_journal.create (post a multi-line GL entry \u2014 reclasses, accruals, corrections; debits must equal credits), xero.item.create (add an inventory item to the catalogue - `code` is REQUIRED and is the idempotency key), xero.item.update (edit an existing inventory item - only the fields you send change), xero.repeating_invoice.create (create an ACCREC repeating invoice template that raises an invoice every week/month - `reference` is REQUIRED and is the idempotency key), xero.repeating_invoice.update (change the template status DRAFT/AUTHORISED, reference, end date or auto-send settings - never deletes, never changes lines)."
 );
 var payloadSchema = external_exports.object({
   tenant_id: external_exports.string().min(1).max(128).describe(
     "Xero organisation id (the Xero-Tenant-Id header value) the write lands in. NOT the Augmented team. Required \u2014 a missing tenant risks writing to the wrong set of books."
   )
 }).passthrough().describe(
-  "Verb-specific fields. xero.payment.create: { invoice_id, account_id, amount, currency?, counterparty? }. xero.bill.create: { contact_id, amount, currency?, counterparty?, line_items_preview, line_items?: [{ description, unit_amount, quantity?, account_code?, tax_type? }], line_amount_types? (Exclusive|Inclusive|NoTax), reference?, date? (YYYY-MM-DD), due_date? (YYYY-MM-DD), account_code? } \u2014 `amount` MUST equal the sum of unit_amount x quantity across line_items (the approval card shows `amount`, so a mismatch is refused rather than silently rewritten); `currency` is sent to Xero as CurrencyCode. Send line_items to raise a CODED payable in ONE approval; omit it and the bill is a single synthesized line from line_items_preview + amount, which posts as an uncoded lump dated today. line_amount_types matters: Xero defaults to Exclusive, so a GST-INCLUSIVE total sent without it is read as a subtotal and the bill total comes out wrong. xero.bill.approve: { invoice_id, amount?, currency?, counterparty? }. xero.invoice.void: { invoice_id, invoice_number?, amount?, counterparty? }. xero.invoice.create: { contact_id, reference (REQUIRED - it is the idempotency key; must not contain a double quote or backslash), line_items: [{ description, unit_amount, quantity?, account_code?, tax_type?, item_code? }], line_amount_types? (Exclusive|Inclusive|NoTax, default Exclusive), date? (YYYY-MM-DD), due_date? (YYYY-MM-DD), status? (DRAFT|AUTHORISED, default DRAFT), amount?, currency?, counterparty? } \u2014 raises an ACCREC customer/sales invoice. `reference` is required because a duplicate ACCREC invoice is a second bill against a customer: the executor reconciles on it before creating, so a retry adopts the existing invoice instead of raising another. AUTHORISED is the status a customer can be sent, so it must be asked for rather than inherited. `amount` MUST equal the sum of unit_amount x quantity across line_items - the tax-EXCLUSIVE SUBTOTAL under the default Exclusive treatment, the total under Inclusive/NoTax - because the approval card shows `amount` and a mismatch is REFUSED rather than silently rewritten. Do not send the gross tax-inclusive figure on an Exclusive invoice; it cannot be verified and it will be refused. xero.invoice.update: { invoice_id, line_items?: [{ description, unit_amount, quantity?, account_code?, tax_type?, item_code? }], line_amount_types? (Exclusive|Inclusive|NoTax), reference?, date?, due_date?, invoice_number?, counterparty?, amount?, currency? } \u2014 WARNING: line_items REPLACES the entire line set on the invoice, so send every line the invoice should end up with, EACH WITH ITS item_code where the org tracks inventory \u2014 a resent line without its item_code loses the item association, so a one-line correction can silently strip inventory tracking off the whole invoice; omit the field entirely to leave the lines untouched. Use line_amount_types to fix a wrong tax treatment (e.g. a GST-inclusive total mistakenly entered on a Tax Exclusive line). `amount` here is the DISPLAY-ONLY NEW TOTAL shown on the card and is NOT checked against line_items - unlike xero.invoice.create and xero.bill.create - because it is the gross figure and the gross depends on tax rates this payload does not carry. Said explicitly so the absence of a check is a documented decision rather than something to be read as a gap. xero.contact.merge: { source_contact_id, target_contact_id, source_name?, target_name? }. xero.bank_transaction.delete: { bank_transaction_id, amount?, counterparty? }. xero.manual_journal.create: { narration, journal_lines: [{ account_code, line_amount (positive=debit, negative=credit), description?, tax_type? }], date? (YYYY-MM-DD), status? (DRAFT|POSTED, default DRAFT), amount?, currency? } \u2014 lines must balance to zero. xero.item.create: { code (REQUIRED, max 30 chars, unique per organisation, no double quote or backslash - the idempotency key), name (REQUIRED, max 50 chars), description? (sales description), purchase_description?, is_sold?, is_purchased?, sales_details?: { unit_price?, account_code?, tax_type? }, purchase_details?: { unit_price?, account_code?, cogs_account_code?, tax_type? }, is_tracked_as_inventory?, inventory_asset_account_code? } \u2014 adds an item invoice and bill lines can reference by item_code. The executor looks `code` up first: an existing item with the same code, the same name AND every field you set is adopted (a retry); an existing item with the same code but a different name, or with different tracking/accounts/prices, is refused (pick another code, or use xero.item.update on that item). A TRACKED item (is_tracked_as_inventory: true) REQUIRES inventory_asset_account_code AND purchase_details.cogs_account_code, or Xero rejects it. xero.item.update: { item_id (REQUIRED, the Xero ItemID from list-items; the approval card identifies the item by this id), code? (renames the code - refused if another item already uses it), name?, description?, purchase_description?, is_sold?, is_purchased?, sales_details?, purchase_details?, is_tracked_as_inventory?, inventory_asset_account_code? } \u2014 only the fields you send change; details blocks merge field by field, so sending sales_details: { unit_price } keeps the existing sales account. Always include tenant_id."
+  "Verb-specific fields. xero.payment.create: { invoice_id, account_id, amount, currency?, counterparty? }. xero.bill.create: { contact_id, amount, currency?, counterparty?, line_items_preview, line_items?: [{ description, unit_amount, quantity?, account_code?, tax_type? }], line_amount_types? (Exclusive|Inclusive|NoTax), reference?, date? (YYYY-MM-DD), due_date? (YYYY-MM-DD), account_code? } \u2014 `amount` MUST equal the sum of unit_amount x quantity across line_items (the approval card shows `amount`, so a mismatch is refused rather than silently rewritten); `currency` is sent to Xero as CurrencyCode. Send line_items to raise a CODED payable in ONE approval; omit it and the bill is a single synthesized line from line_items_preview + amount, which posts as an uncoded lump dated today. line_amount_types matters: Xero defaults to Exclusive, so a GST-INCLUSIVE total sent without it is read as a subtotal and the bill total comes out wrong. xero.bill.approve: { invoice_id, amount?, currency?, counterparty? }. xero.invoice.void: { invoice_id, invoice_number?, amount?, counterparty? }. xero.invoice.delete: { invoice_id (REQUIRED, the Xero InvoiceID UUID from list-invoices, not the number), invoice_number?, amount?, counterparty? } \u2014 permanently deletes a DRAFT or SUBMITTED invoice or bill (ACCREC or ACCPAY) once a human approves. The executor reads the invoice first and refuses anything else: AUTHORISED -> use xero.invoice.void; PAID -> cannot be removed until its payments are removed in Xero; VOIDED -> nothing to delete. If you send invoice_number it is shown on the approval card and must match the invoice Xero holds under invoice_id, or the delete is refused. An invoice that is already DELETED reports success with already_deleted: true. xero.invoice.create: { contact_id, reference (REQUIRED - it is the idempotency key; must not contain a double quote or backslash), line_items: [{ description, unit_amount, quantity?, account_code?, tax_type?, item_code? }], line_amount_types? (Exclusive|Inclusive|NoTax, default Exclusive), date? (YYYY-MM-DD), due_date? (YYYY-MM-DD), status? (DRAFT|AUTHORISED, default DRAFT), amount?, currency?, counterparty? } \u2014 raises an ACCREC customer/sales invoice. `reference` is required because a duplicate ACCREC invoice is a second bill against a customer: the executor reconciles on it before creating, so a retry adopts the existing invoice instead of raising another. AUTHORISED is the status a customer can be sent, so it must be asked for rather than inherited. `amount` MUST equal the sum of unit_amount x quantity across line_items - the tax-EXCLUSIVE SUBTOTAL under the default Exclusive treatment, the total under Inclusive/NoTax - because the approval card shows `amount` and a mismatch is REFUSED rather than silently rewritten. Do not send the gross tax-inclusive figure on an Exclusive invoice; it cannot be verified and it will be refused. xero.invoice.update: { invoice_id, line_items?: [{ description, unit_amount, quantity?, account_code?, tax_type?, item_code? }], line_amount_types? (Exclusive|Inclusive|NoTax), reference?, date?, due_date?, invoice_number?, counterparty?, amount?, currency? } \u2014 WARNING: line_items REPLACES the entire line set on the invoice, so send every line the invoice should end up with, EACH WITH ITS item_code where the org tracks inventory \u2014 a resent line without its item_code loses the item association, so a one-line correction can silently strip inventory tracking off the whole invoice; omit the field entirely to leave the lines untouched. Use line_amount_types to fix a wrong tax treatment (e.g. a GST-inclusive total mistakenly entered on a Tax Exclusive line). `amount` here is the DISPLAY-ONLY NEW TOTAL shown on the card and is NOT checked against line_items - unlike xero.invoice.create and xero.bill.create - because it is the gross figure and the gross depends on tax rates this payload does not carry. Said explicitly so the absence of a check is a documented decision rather than something to be read as a gap. xero.contact.merge: { source_contact_id, target_contact_id, source_name?, target_name? }. xero.bank_transaction.delete: { bank_transaction_id, amount?, counterparty? }. xero.manual_journal.create: { narration, journal_lines: [{ account_code, line_amount (positive=debit, negative=credit), description?, tax_type? }], date? (YYYY-MM-DD), status? (DRAFT|POSTED, default DRAFT), amount?, currency? } \u2014 lines must balance to zero. xero.item.create: { code (REQUIRED, max 30 chars, unique per organisation, no double quote or backslash - the idempotency key), name (REQUIRED, max 50 chars), description? (sales description), purchase_description?, is_sold?, is_purchased?, sales_details?: { unit_price?, account_code?, tax_type? }, purchase_details?: { unit_price?, account_code?, cogs_account_code?, tax_type? }, is_tracked_as_inventory?, inventory_asset_account_code? } \u2014 adds an item invoice and bill lines can reference by item_code. The executor looks `code` up first: an existing item with the same code, the same name AND every field you set is adopted (a retry); an existing item with the same code but a different name, or with different tracking/accounts/prices, is refused (pick another code, or use xero.item.update on that item). A TRACKED item (is_tracked_as_inventory: true) REQUIRES inventory_asset_account_code AND purchase_details.cogs_account_code, or Xero rejects it. xero.item.update: { item_id (REQUIRED, the Xero ItemID from list-items; the approval card identifies the item by this id), code? (renames the code - refused if another item already uses it), name?, description?, purchase_description?, is_sold?, is_purchased?, sales_details?, purchase_details?, is_tracked_as_inventory?, inventory_asset_account_code? } \u2014 only the fields you send change; details blocks merge field by field, so sending sales_details: { unit_price } keeps the existing sales account. xero.repeating_invoice.create: { contact_id, reference (REQUIRED - the idempotency key; no double quote or backslash), schedule: { period (1 = every month/week), unit (WEEKLY|MONTHLY), due_date (number, read through due_date_type), due_date_type (DAYSAFTERBILLDATE|DAYSAFTERBILLMONTH|DAYSAFTERINVOICEDATE|DAYSAFTERINVOICEMONTH|OFCURRENTMONTH|OFFOLLOWINGMONTH), start_date (YYYY-MM-DD, the FIRST invoice date; its day of month is the day every invoice is dated), end_date? }, line_items: [{ description, unit_amount, quantity?, account_code?, tax_type?, item_code? }], line_amount_types? (default Exclusive), status? (DRAFT|AUTHORISED, default DRAFT - a DRAFT template generates NOTHING), approved_for_sending? (true = Xero EMAILS each generated invoice to the customer unattended; only takes effect when AUTHORISED), send_copy?, include_pdf?, mark_as_sent?, amount? (the PER-INVOICE subtotal; refused if it does not match the lines), currency?, counterparty? } - e.g. $2,000 + GST on the 4th of each month: unit MONTHLY, period 1, start_date the next 4th, line_amount_types Exclusive, one line unit_amount 2000 with the GST tax_type. A template already carrying the reference is adopted ONLY if it is identical to this request (a retry; a duplicate template bills twice every period); one that differs in anything (contact, status, lines, schedule, send settings) is refused - to activate or change an EXISTING template use xero.repeating_invoice.update, not create. xero.repeating_invoice.update: { repeating_invoice_id (the RepeatingInvoiceID from list-repeating-invoices), status? (DRAFT|AUTHORISED only), reference?, end_date?, approved_for_sending?, send_copy?, include_pdf?, mark_as_sent?, counterparty? } - send only what changes; line_items, the schedule (other than end_date) and deletion are NOT supported: create a new template instead. Always include tenant_id."
 );
 var reasonSchema = external_exports.string().min(1).max(2e3).describe(
   "Why the agent needs to perform this write. Surfaced verbatim on the approval card for the human reviewer. Mandatory."
@@ -21270,7 +21278,7 @@ var awaitDecisionSchema = external_exports.object({
 // package.json
 var package_default = {
   name: "@integrity-labs/xero-broker",
-  version: "0.1.9",
+  version: "0.1.11",
   description: "Xero Broker \u2014 MCP server that routes money- and ledger-touching Xero writes through approval-core (HITL). Sibling to cloud-broker / channel-broker; the only write path for an agent once the vendor xero-mcp-server's write tools are stripped. ENG-4922.",
   type: "module",
   bin: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@integrity-labs/xero-broker",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Xero Broker — MCP server that routes money- and ledger-touching Xero writes through approval-core (HITL). Sibling to cloud-broker / channel-broker; the only write path for an agent once the vendor xero-mcp-server's write tools are stripped. ENG-4922.",
   "type": "module",
   "bin": {