jaz-clio 4.34.2 → 4.34.4

package/README.md

@@ -235,7 +235,7 @@ Every command supports `--json` for structured output — ideal for piping to ot
 
 ## MCP Server
 
-Expose all 240 CLI tools to AI coding and coworking agents via the Model Context Protocol (MCP). The server runs locally on your machine — no cloud, no ports. API calls go directly from your machine to the Jaz API.
+Expose all 241 CLI tools to AI coding and coworking agents via the Model Context Protocol (MCP). The server runs locally on your machine — no cloud, no ports. API calls go directly from your machine to the Jaz API.
 
 **Claude Code:**
 

package/assets/skills/api/SKILL.md

@@ -1,7 +1,14 @@
 ---
 name: jaz-api
-version: 4.34.2
-description: Complete reference for the Jaz REST API — the accounting platform backend. Use this skill whenever building, modifying, debugging, or extending any code that calls the API — including API clients, integrations, data seeding, test data, or new endpoint work. Contains every field name, response shape, error, gotcha, and edge case discovered through live production testing.
+version: 4.34.4
+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
+  recovery (422/400/404/500), search filters, pagination, and edge cases for
+  every endpoint — invoices, bills, credit notes, journals, cash entries,
+  payments, contacts, CoA, items, tax profiles, bank records, fixed assets,
+  schedulers, subscriptions, attachments, and Jaz Magic extraction. Also use
+  when building API clients, seeding test data, or adding new endpoint support.
 license: MIT
 compatibility: Requires Jaz API key (x-jk-api-key header). Works with Claude Code, Google Antigravity, OpenAI Codex, GitHub Copilot, Cursor, and any agent that reads markdown.
 ---
@@ -110,8 +117,10 @@ You are working with the **Jaz REST API** — the accounting platform backend. A
 | AR/AP summary | `startDate`, `endDate` |
 | Bank balance summary | `primarySnapshotDate` |
 | Equity movement | `primarySnapshotStartDate`, `primarySnapshotEndDate` |
+| Ledger highlights | *(none — simple GET)* |
 
-37. **Data exports use simpler field names**: P&L export uses `startDate`/`endDate` (NOT `primarySnapshotDate`). AR/AP export uses `endDate`.
+37. **Ledger highlights is a simple GET** — `GET /api/v1/ledger/highlights` returns org-wide GL summary metadata: transaction counts by type, date range, active accounts/currencies, cross-currency flag, and dynamic FX types. No parameters. Response dates are epoch ms (see Rule 52).
+37a. **Data exports use simpler field names**: P&L export uses `startDate`/`endDate` (NOT `primarySnapshotDate`). AR/AP export uses `endDate`.
 
 ### Pagination
 38. **All list/search endpoints use `limit`/`offset` pagination** — NOT `page`/`size`. Default limit=100, offset=0. Max limit=1000, max offset=65536. `page`/`size` params are silently ignored. Response shape: `{ totalPages, totalElements, truncated, data: [...] }`. When `truncated: true`, a `_meta: { fetchedRows, maxRows }` field explains why (offset cap or `--max-rows` soft cap — default 10,000). Use `--max-rows <n>` to override. Always check `truncated` before assuming the full dataset was returned.
@@ -339,16 +348,6 @@ Supports `--json` for structured output. 186 articles across 20 sections. Automa
 - Use `clio help-center` when you need specific answers (returns only relevant articles, saves context)
 - Read `help-center-mirror/*.md` directly only when you need to scan an entire section comprehensively
 
-## DX Overhaul (Implemented)
-
-The backend DX overhaul is live. Key improvements now available:
-- **Request-side field aliases**: `name` → `tagName`/`internalName`, `issueDate` → `valueDate`, `bankAccountResourceId` → `accountResourceId`, and more. Both canonical and alias names are accepted.
-- **Response-side aliases**: Tags, items, and custom fields return `name` alongside canonical field names (`tagName`, `internalName`, `customFieldName`).
-- **`saveAsDraft` defaults to `false`**: Omitting it creates a finalized transaction. No longer required on POST.
-- **`POST /items/search` available**: Advanced search with filters now works for items.
-- **NormalizeToArray**: Flat payment/refund/credit objects are auto-wrapped into arrays. Array format is still recommended.
-- **Nil-safe deletes**: Delete endpoints return 404 (not 500) when resource not found.
-
 ## Recommended Client Patterns
 
 - **Starting from an attachment?** → Use Jaz Magic (`POST /magic/createBusinessTransactionFromAttachment`). Never manually parse a PDF/JPG to construct `POST /invoices` or `POST /bills` — let the extraction & autofill pipeline handle it.
@@ -361,3 +360,10 @@ The backend DX overhaul is live. Key improvements now available:
 - **Scheduled invoices/bills**: Wrap as `{ status, startDate, endDate, repeat, invoice/bill: { reference, valueDate, dueDate, contactResourceId, lineItems, saveAsDraft: false } }`. `reference` is required.
 - **Scheduled journals**: Flat: `{ status, startDate, endDate, repeat, valueDate, schedulerEntries, reference }`. `valueDate` is required.
 - **FX currency (invoices, bills, credit notes, AND journals)**: `currency: { sourceCurrency: "USD" }` (auto-fetches platform rate) or `currency: { sourceCurrency: "USD", exchangeRate: 1.35 }` (custom rate). Same object form on all transaction types. **Never use `currencyCode` string** — silently ignored.
+
+## See Also
+
+- **jaz-recipes** — 16 IFRS-compliant transaction recipes with journal entries, capsules, and calculators
+- **jaz-jobs** — 12 accounting job playbooks (month-end close, bank recon, GST/VAT filing, etc.)
+- **jaz-conversion** — Data migration workflows from Xero, QuickBooks, Sage, MYOB, and Excel
+- **jaz-cli** — CLI command reference, auth, output formats, pagination, and workflow patterns

package/assets/skills/api/help-center-mirror/bank-reconciliations.md

@@ -170,30 +170,38 @@ Source: https://help.jaz.ai/en/articles/9941717-managing-bank-statements
 
 - You can upload your statements in a CSV file format or as a PDF.
 
-**Q3. Will Jaz let me configure the columns from the statement PDF file?**
+**Q3. Can I import password protected bank statement PDFs?**
+
+- Yes. To import a password-protected bank statement, include the password in the file name using this format:
+  - Filename__pw__password.pdf
+    - <filename>+<double underscore>+<pw>+<double underscore>+<file password>
+      - Example: bankStam3nt__pw__filepass001.pdf
+- Note: Make sure there are two underscores before and after pw and do not include the “<>”  – brackets.
+
+**Q4. Will Jaz let me configure the columns from the statement PDF file?**
 
 - Yes, Jaz will extract the columns from the uploaded PDF file and let you assign them to fields in Jaz.
 
-**Q4. What if there are errors in the uploaded PDF statement file?**
+**Q5. What if there are errors in the uploaded PDF statement file?**
 
 - Jaz will extract statement lines from the uploaded PDF file and create a downloadable CSV file for reviewing discrepancies, if any.
 - Alternatively, you can still import the statement lines with no errors. Jaz will ignore the ones with issues and import the rest.
 
-**Q5. Can I import a statement in one currency into a bank account that uses a different currency?**
+**Q6. Can I import a statement in one currency into a bank account that uses a different currency?**
 
 - The final statement amounts that get recorded in Jaz will be in the currency of the bank account in Jaz, not the currency of the amounts in the bank statement.
 - Jaz will not do any automatic conversion between the different currencies, and will solely take the numerical amounts as is.
 - For example, a statement line that has 50 USD as its amount will be automatically recorded in Jaz as 50 USD, when importing to a USD bank account, or 50 SGD if importing into a SGD bank account.
 
-**Q6. Can I review the statement lines before they are imported into the system?**
+**Q7. Can I review the statement lines before they are imported into the system?**
 
 - Yes, Jaz will let you review all the statement lines before they are imported into your bank account on Jaz.
 
-**Q7. Can I upload multiple bank statements?**
+**Q8. Can I upload multiple bank statements?**
 
 - Yes, you can upload up to 12 files at a time.
 
-**Q8. Can I manage my uploaded statements?**
+**Q9. Can I manage my uploaded statements?**
 
 - To manage your uploaded statements, utilize the Overview tab:
   - Pending – configure and review imported statements
@@ -202,11 +210,11 @@ Source: https://help.jaz.ai/en/articles/9941717-managing-bank-statements
   - Deleted – view and restore deleted files
     - *Note: Reconciled files cannot be deleted.*
 
-**Q9. Can I delete a bank statement line?**
+**Q10. Can I delete a bank statement line?**
 
 - Yes, you can delete a bank statement line individually via the 3-dot menu on the statement line OR you can bulk-delete by selecting multiple statement lines at once from both reconciled & unreconciled tabs.
 
-**Q10. Is it possible to retrieve a deleted statement line?**
+**Q11. Is it possible to retrieve a deleted statement line?**
 
 - Yes, you can. Under the **Deleted**tab for the bank account, you will find a list of deleted statement lines.
 - Undelete individual statement line OR bulk undelete to move it back to the Unreconciled tab.

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

@@ -36,6 +36,44 @@ Source: https://help.jaz.ai/en/articles/9104226-apply-supplier-credit
 
 ---
 
+### Apply Supplier Credit
+Source: https://help.jaz.ai/en/articles/9104226-apply-supplier-credit
+
+**Q1. Can I apply a draft supplier credit note to a bill?**
+
+- No, supplier credit notes must be active before they can be applied.
+
+**Q2. Can I apply a supplier credit note of a different currency than the bill?**
+
+- If you would like to apply a supplier credit note to a bill, the supplier credit note must be in the same currency that the bill was created in.
+- For example, a bill that was created in USD can only make use of supplier credits that were also credited in USD.
+
+**Q3. Can I partially apply a supplier credit note to a bill?**
+
+- Yes, you do not have to use the full amount in the supplier credit note.
+- You can adjust this via the **Amount to Apply**field. Enter an amount smaller than the supplier credit note amount to only apply the credit note partially.
+
+**Q4. Can I partially pay a bill using a supplier credit only?**
+
+- Yes, supplier credits do not have to cover the entire bill amount. You can apply as much of a supplier credit note as you would like to a bill.
+- The rest of the bill can be paid with other payment methods.
+
+**Q5. Can I remove an applied supplier credit note from a bill?**
+
+- Yes, you can remove an applied supplier credit note on a bill by updating the applied amount to 0.
+  - Change the **Amount to Apply**amount to 0 on the **Edit Applied Credit**modal. This will remove all applied credit from the bill.
+
+**Q6. Does applying or removing a supplier credit note have an impact on my financial reports?**
+
+- There will be no further impact on your financial reports.
+- This is because the credits would have been accounted for during creation, appearing as a debit to Accounts Payable, and a credit to transaction account used on the bill.
+- The offset value date aligns with the later of the transaction date or the credit note date, ensuring accurate reporting across time zones. For example:
+  - Transaction Date: 1 Jan 2025
+  - Credit Note Date: 5 Jan 2025
+  - Offset Value Date: 5 Jan 2025
+
+---
+
 ### Bill Approval Records
 Source: https://help.jaz.ai/en/articles/9115415-bill-approval-records
 
@@ -114,52 +152,6 @@ Source: https://help.jaz.ai/en/articles/9104231-bill-receipts
 
 ---
 
-### Draft Bills & Payments
-Source: https://help.jaz.ai/en/articles/9104224-draft-bills-payments
-
-**Q1. Can I save a bill as a draft?**
-
-- Yes, a bill can be saved as a draft even if all the mandatory fields are not filled.
-
-**Q2. How can I convert a draft bill to an active one?**
-
-- Any draft bill can be converted to active only after all the mandatory fields are filled.
-
-**Q3. Can I save bill payment records as drafts?**
-
-- Similar to bill records, bill payments can also be saved as a draft.
-
-**Q4. How can I convert draft payment records to active ones?**
-
-- For bills, any draft payments are converted only if the bill is also converted to active.
-- Hence, to record the payment, the bill must be converted to active status.
-
-**Q5. Can I delete a draft bill?**
-
-- Yes, you can delete a draft bill. If the bill had a draft payment linked, it will also be deleted.
-
-**Q6. Can I delete a draft bill payment?**
-
-- Similar to draft bills, draft bill payments can also be deleted.
-
-**Q7. Do draft bills affect my financial reports?**
-
-- No, it does not. Financial reports are only affected once the bills are active.
-
-**Q8. Do draft bill payments affect my financial reports?**
-
-- No, it does not. Financial reports are only affected once the payments are active.
-
-**Q9. Can I create a non-base currency draft bill?**
-
-- Yes, the currency setting on a bill does not affect the ability to save it as a draft.
-
-**Q10. Can I create a non-base currency draft bill payment?**
-
-- Yes, you can save a bill payment as a draft even if it is in non-base currency.
-
----
-
 ### Import Bills
 Source: https://help.jaz.ai/en/articles/9104236-import-bills