jaz-clio 4.55.5 → 4.58.1

package/README.md

@@ -3,11 +3,11 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/jaz-clio"><img src="https://img.shields.io/npm/v/jaz-clio?style=for-the-badge&logo=npm" alt="npm"></a>
   <a href="https://www.npmjs.com/package/jaz-clio"><img src="https://img.shields.io/npm/dm/jaz-clio?style=for-the-badge&label=downloads" alt="npm downloads"></a>
-  <img src="https://img.shields.io/badge/tools-247-blue?style=for-the-badge" alt="247 Tools">
+  <img src="https://img.shields.io/badge/tools-266-blue?style=for-the-badge" alt="266 Tools">
   <a href="https://github.com/teamtinvio/jaz-ai/blob/main/LICENSE"><img src="https://img.shields.io/github/license/teamtinvio/jaz-ai?style=for-the-badge&color=green" alt="License"></a>
 </p>
 
-247 tools. 13 financial calculators. 12 job playbooks. 117 API rules. 16 IFRS recipes.
+266 tools. 13 financial calculators. 12 job playbooks. 130 API rules. 16 IFRS recipes.
 
 ```bash
 npm install -g jaz-clio
@@ -19,7 +19,7 @@ Requires **Node.js 18+** ([nodejs.org](https://nodejs.org)). Also fully compatib
 
 - [Three Ways In](#three-ways-in) — CLI, MCP, Skills
 - [CLI](#cli) — 53 command groups
-- [MCP Server](#mcp-server) — 247 tools for AI agents
+- [MCP Server](#mcp-server) — 266 tools for AI agents
 - [Skills](#skills) — Teach any AI the Jaz API
 - [Setup](#setup) — Auth, multi-org, automation
 
@@ -51,7 +51,7 @@ clio search "overdue"                             # Find it across all entities
 
 ## MCP Server
 
-247 CLI tools, available to any AI agent that speaks MCP. Runs locally — no cloud, no ports.
+266 CLI tools, available to any AI agent that speaks MCP. Runs locally — no cloud, no ports.
 
 **Claude Code:**
 ```bash
@@ -80,7 +80,7 @@ claude mcp add jaz -- npx jaz-clio mcp
 
 ## Skills
 
-117 production-tested API rules. Field name mappings. Error recovery patterns. 12 job playbooks. Installable into any AI-aware project.
+130 production-tested API rules. Field name mappings. Error recovery patterns. 12 job playbooks. Installable into any AI-aware project.
 
 ```bash
 clio init

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 4.55.5
+version: 4.58.1
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 117 production gotchas, error
@@ -345,6 +345,43 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 116. **PaymentMethod accepts 11 values** — All payment endpoints (invoices, bills, credit note refunds, payment updates) accept: `CASH`, `BANK_TRANSFER`, `CREDIT_CARD`, `CHEQUE`, `E_WALLET`, `WITHHOLDING_TAX_CERTIFICATE`, `CLEARING_SETTLEMENT`, `DEBT_WRITE_OFF`, `INTER_COMPANY`, `OTHER`, `PAYMENT_GATEWAY`. Default is `BANK_TRANSFER`. The OAS previously listed only 7 — the API runtime already accepted all 11.
 117. **Fixed asset sale accepts PURCHASE type** — `saleBusinessTransactionType` in mark-as-sold accepts `SALE`, `PURCHASE`, or `JOURNAL_MANUAL`. Use `PURCHASE` when the disposal is linked to a purchase-side transaction (e.g., trade-in).
 
+### Bulk Upserts (transactions)
+
+118. **8 bulk-upsert endpoints for transactions** — `POST /api/v1/{invoices,bills,customer-credit-notes,supplier-credit-notes,journals,fixed-assets}/bulk-upsert` plus line-item variants for invoices and bills (`/invoices/line-items/bulk-upsert`, `/bills/line-items/bulk-upsert`). Max **500 rows per call**. All async — return `{data: {jobId, subscriptionFBPath, status, totalRecords}}`. Poll `search_background_jobs` with `filter: {resourceId: {eq: jobId}}` until terminal status. **Natural keys**: invoices = `invoiceReference`, bills = `billReference`, credit notes = `creditNoteReference`, journals = `reference`, fixed assets = `reference`. Provide `resourceId` (UUID) to update by ID; otherwise the natural key drives upsert. `rowIndex` is optional caller-supplied for error reporting.
+
+119. **PARTIAL_SUCCESS handling** — When `search_background_jobs` returns `PARTIAL_SUCCESS` for a bulk-upsert job, the per-row failures are in `data[0].errorDetails` on the SAME response (an array of per-row error objects). Top-level counts (`processedCount`, `failedCount`, `totalRecords`) tell you *how many* failed; `errorDetails` tells you *which rows and why*. Don't pretend the operation succeeded — surface the failed rows to the user. The rule of thumb: poll with `search_background_jobs` filtered by `resourceId: { eq: jobId }`, then read `data[0].errorDetails` for terminal states.
+
+120. **`dateFormat` field was removed from bulk-upsert** — the API now requires ISO 8601 (`YYYY-MM-DD`) for ALL date fields on `POST /{invoices,bills,journals}/bulk-upsert`. Sending `dateFormat: "MM/DD/YYYY"` (or any other value) is silently ignored. Reject any datetime strings (anything with `T` or `:`) client-side before submitting.
+
+121. **Intra-batch reference dedup is MERGE, not REJECT** — Two rows in the same bulk-upsert call sharing the same natural key (`invoiceReference`/`billReference`/etc.) are MERGED by the API (last row wins). If the user wants strict-uniqueness, dedup client-side first.
+
+122. **Fixed asset bulk upsert requires `registrationType` + `typeCode`** — `registrationType: "NEW" | "TRANSFER"` distinguishes newly-acquired assets from those inherited from a prior accounting system. `typeCode` selects the asset class (e.g., `COMPUTER_EQUIPMENT`). Both are required on every row. `depreciationStartDate` is `YYYY-MM-DD` only.
+
+### Reconciliation actions (write-side)
+
+123. **8 reconciliation action endpoints under `/api/v1/reconciliations/*`** — these *commit* a reconciliation decision against a bank statement entry, distinct from `view_auto_reconciliation` (which queries `/search-magic-reconciliation` for *suggestions*). Two are async, six are sync:
+    - **Async (jobId):** `quick_reconcile` (bulk match entries to journals, max 500), `apply_bank_rule` (bulk apply a rule to entries, max 500). Poll `search_background_jobs` filtered by `resourceId`; on `PARTIAL_SUCCESS` read `data[0].errorDetails` for per-row failures.
+    - **Sync (single bank entry):** `reconcile_direct_cash_entry`, `reconcile_cash_journal`, `reconcile_manual_journal`, `reconcile_cash_transfer`, `reconcile_invoice_receipt`, `reconcile_bill_receipt`. Each returns `{bankStatementEntryResourceId, status, reference, valueDate}`.
+
+124. **Recon prefill from the bank statement entry** — when caller omits `valueDate`, `dueDate`, payment `amount`, or direction (cash-in vs cash-out), the API fills these from the bank entry. Best-effort: a missing entry lookup logs a warning and forwards the payload as-is. Caller can always override by passing the field explicitly.
+
+125. **The 6 sync recon endpoints are NOT idempotent** — calling twice on the same `bankStatementEntryResourceId` creates duplicate journals. Before retrying, confirm the entry's reconciled state via `view_auto_reconciliation` or `search_bank_records` filtered by `status`. Concurrent calls on the same entry race — last-write-wins.
+
+126. **Sync recon → AR/AP via `invoice_receipt` / `bill_receipt`** — these endpoints CREATE a transaction (invoice for AR, bill for AP) and immediately reconcile it to the bank entry. The two endpoints stay separate (not unified) because the invoice side carries `billTo` / `billFrom` that bills don't have. Cash-in vs cash-out, by contrast, IS unified into `reconcile_direct_cash_entry` — direction is encoded in the bank entry sign.
+
+127. **Cash transfer `amount` is conditional** — for `reconcile_cash_transfer`, `amount` is required only when the counterparty account is in a non-functional currency. Same-currency transfers omit it; the API derives the amount from the bank entry.
+
+### Drafts lifecycle (server-side, BULK-friendly)
+
+128. **3 BULK-action server-side draft lifecycle endpoints under `/api/v1/drafts/*`** — distinct from the local-only `src/core/drafts/` payload helpers. All three accept a single mixed-type batch (max 500 items per call); there are NO per-entity variants. ONE call covers any combination of invoices, bills, customer credit notes, and supplier credit notes.
+    - `POST /api/v1/drafts/validate` (sync) → `validate_drafts`. Returns per-item validation errors + display data inline. No state change. Use to pre-flight before convert/submit.
+    - `POST /api/v1/drafts/convert-to-active` (async, jobId) → `convert_drafts_to_active`. Promotes drafts to ACTIVE. Poll `search_background_jobs` filtered by `resourceId`; on PARTIAL_SUCCESS read `data[0].errorDetails`.
+    - `POST /api/v1/drafts/submit-for-approval` (async, jobId) → `submit_drafts_for_approval`. Routes drafts into the approval workflow.
+
+129. **Drafts lifecycle request shape (mix-friendly)** — all 3 endpoints accept the same body: `{ items: [{btResourceId, btType}] }` with `btType ∈ {SALE | PURCHASE | SALE_CREDIT_NOTE | PURCHASE_CREDIT_NOTE}`. **Max 500 items per call. ONE batch can mix any combination of types** — no need to group by btType client-side, no need to make multiple calls per entity type. **Mapping**: `SALE` → invoice, `PURCHASE` → bill, `SALE_CREDIT_NOTE` → customer credit note, `PURCHASE_CREDIT_NOTE` → supplier credit note. Journals are NOT in the enum (they have their own approval flow).
+
+130. **Drafts lifecycle is NOT idempotent** — a second `convert_drafts_to_active` on already-ACTIVE drafts returns 422; a second `submit_drafts_for_approval` on drafts with an in-flight approval returns 422. Filter the draft list by `status: DRAFT` before submitting (the entity-specific search tools — `search_invoices`, `search_bills`, etc. — accept `status` filters). `validate_drafts` IS safe to call repeatedly (read-only, no state change).
+
 ## Supporting Files
 
 For detailed reference, read these files in this skill directory:

package/assets/skills/api/help-center-mirror/bills.md

@@ -809,8 +809,8 @@ Source: https://help.jaz.ai/en/articles/9104254-void-bill
 
 ---
 
-### Bulk Bill Payments
-Source: https://help.jaz.ai/en/articles/9993161-bulk-bill-payments
+### Bulk and Batch Bill Payments
+Source: https://help.jaz.ai/en/articles/9993161-bulk-and-batch-bill-payments
 
 **Q1. Can I record payments for multiple bills at once?**
 
@@ -819,16 +819,16 @@ Source: https://help.jaz.ai/en/articles/9993161-bulk-bill-payments
 
 **Q2: Can I make bulk/batch payments for bills in different currencies?**
 
-- Yes, you can select and pay invoices in various currencies simultaneously.
+- Yes, you can select and pay bills in various currencies simultaneously.
 - All the payments will be recorded in the selected payment account currency.
 
 **Q3. What is the difference between Bulk Payments and Batch Payments?**
 
-- Bulk and Batch Payments both create a separate payment for each transaction and support partial, split, and cross-currency amounts. They only differ in bank reconciliation:
-  - **Bulk Payments:** Each payment appears as a separate cashflow record
-  - **Batch Payments:** Payments in the batch are aggregated into a single cashflow record**Q4. Can I partially pay bills during bulk/batch payments?**
+Bulk and Batch Payments both create a separate payment for each transaction and support partial, split, and cross-currency amounts. They only differ in bank reconciliation:
+- **Bulk Payments:** Each payment appears as a separate cashflow record
+- **Batch Payments:** Payments in the batch are aggregated into a single cashflow record**Q4. Can I partially pay bills during bulk/batch payments?**
 
-- Yes, you can do partial payments during bulk/batch payments, by updating the bill payment amount.
+- Update the 'Bill Payment Amount' while recording the invoice payment amount in the bulk/batch payments flow.
 
 **Q5. Payments created from the bulk/batch payment flow are created in which currency?**
 
@@ -851,29 +851,33 @@ Source: https://help.jaz.ai/en/articles/9993161-bulk-bill-payments
 
 **Q9. Is there a limit to the number of bills I can pay at once?**
 
-- Yes, you can only select records on a single page. If the page size is set to 200, you can select up to 200 bills to create bulk payments. The current maximum page size is 500 records.
+- Yes, You can only select all the records present on a single page. So, if the page size is set to 200 records, you can select 200 bill records to create bulk/batch payments.
 
 **Q10. Can I record overpayments from the bill bulk/batch payment flow?**
 
-- No, you cannot record overpayments. Jaz will prevent you from entering a payment amount that is greater than the balance due on the bill.
+- No, you cannot record overpayments. Jaz will prevent you from entering a payment amount that is greater than the balance due on the invoice.
 
 **Q11. How do I edit a recorded bulk/batch payment?**
 
 - Find the payment record (either from the payments tab / find the bill against which the payment is recorded) and edit the details as needed.
 
-**Q12. Why are there separate columns for "Payment" and "Cash Received"?**
+**Q12. Why are there separate columns for "Payment" and "Cash Spent"?**
 
 - The "Payment" column reflects the bill's original amount due in its designated currency.
-- The "Cash Received" column allows you to record the actual amount received, which might differ due to exchange rate fluctuations in multi-currency scenarios.
+- The "Cash Spent" column allows you to record the actual amount spent, which might differ due to exchange rate fluctuations in multi-currency scenarios.
 
-**Q13. Can I view the total cash received during the bulk/batch payment?**
+**Q13. What happens when I click "Save" on the "Record Bill Payments" modal?**
 
-- Yes, you can view the total cash received during the bulk payment flow. The total cash received will be in the payment account currency.
+- When you click "Save" on the "Record Bill Payments" modal, the payments will be recorded and the bills will be marked as paid.
 
-**Q14. Is bulk payment the same as batch payment?**
+**Q14. Can I view the total cash spent during the bulk/batch payment?**
 
-- No, bulk payments create 1 payment record for all the selected bills.
-- Batch payments create a single payment for all the selected bills.
+- Yes, you can view the total cash spent during the bulk/batch payment flow. The total cash spent will be in the payment account currency.
+
+**Q15. Is bulk payment the same as batch payment?**
+
+- No, bulk payments create 1 payment record for all the selected invoices.
+- Batch payments create a single payment for all the selected invoices.
 
 ---
 

package/assets/skills/api/help-center-mirror/get-started.md

@@ -335,7 +335,11 @@ Source: https://help.jaz.ai/en/articles/11710444-billing-account-setup
 - Add new payment methods. Having at least two is recommended for reliability.
 - Enable the Auto Charge toggle to activate automatic payments.
 
-**Q9. I’ve set up my Billing Account, what’s next?**
+**Q9. Can I give others access to my billing account?**
+
+- Yes. You can add users through the **Delegate Whitelist**. Go to**Billing Account** > hover over the **account** > click the**three-dot icon** > **Edit** >**Delegate Whitelist** > **Add Emails**
+- Whitelisted users can use your account as a billing method in organizations where you both have billing permissions. They cannot view or manage the account.
+- **Note:** Only whitelist trusted users. Jaz is not liable for any unauthorized charges made by delegates.**Q10. I’ve set up my Billing Account, what’s next?**
 
 - Head over to **[Plans & Add-ons](https://help.jaz.ai/en/articles/11710415-choosing-plans-addons)**to customize the right plan for your organization.