jaz-clio 4.25.5 → 4.25.7

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 4.25.5
+version: 4.25.7
 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.
 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.

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 4.25.5
+version: 4.25.7
 description: Accounting data conversion skill — migrates customer data from Xero, QuickBooks, Sage, MYOB, and Excel exports to Jaz. Covers config, quick, and full conversion workflows, Excel parsing, CoA/contact/tax/items mapping, clearing accounts, TTB, and TB verification.
 ---
 

package/assets/skills/jobs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-jobs
-version: 4.25.5
+version: 4.25.7
 description: 12 accounting jobs for SMB bookkeepers and accountants — month-end, quarter-end, and year-end close playbooks plus 9 ad-hoc operational jobs (bank recon, document collection, GST/VAT filing, payment runs, credit control, supplier recon, audit prep, fixed asset review, statutory filing). Jobs can have paired tools as nested subcommands (e.g., `clio jobs bank-recon match`, `clio jobs document-collection ingest`, `clio jobs statutory-filing sg-cs`). Paired with an interactive CLI blueprint generator (clio jobs).
 license: MIT
 compatibility: Works with Claude Code, Claude Cowork, Claude.ai, and any agent that reads markdown. For API payloads, load the jaz-api skill. For individual transaction patterns, load the jaz-recipes skill.

package/assets/skills/transaction-recipes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-recipes
-version: 4.25.5
+version: 4.25.7
 description: 16 IFRS-compliant recipes for complex multi-step accounting in Jaz — prepaid amortization, deferred revenue, loan schedules, IFRS 16 leases, hire purchase, fixed deposits, asset disposal, FX revaluation, ECL provisioning, IAS 37 provisions, dividends, intercompany, and capital WIP. Each recipe includes journal entries, capsule structure, and verification steps. Paired with 13 financial calculators that produce execution-ready blueprints with workings.
 license: MIT
 compatibility: Works with Claude Code, Claude Cowork, Claude.ai, and any agent that reads markdown. For API payloads, load the jaz-api skill alongside this one.

package/dist/core/registry/tools.js

@@ -212,18 +212,36 @@ export const TOOL_DEFINITIONS = [
         params: {
             name: { type: 'string', description: 'Account name' },
             code: { type: 'string', description: 'Account code (unique)' },
-            accountType: { type: 'string', description: 'Account type (e.g., "Current Assets", "Revenue")' },
+            accountType: { type: 'string', description: 'Exact API values: "Bank Accounts", "Cash", "Current Asset", "Fixed Asset", "Inventory", "Current Liability", "Non-current Liability", "Shareholders Equity", "Operating Revenue", "Other Revenue", "Operating Expense", "Direct Costs"' },
             currencyCode: { type: 'string', description: 'Currency code (e.g., "SGD")' },
         },
         required: ['name', 'code', 'accountType'],
         group: 'accounts',
         readOnly: false,
-        execute: async (ctx, input) => createAccount(ctx.client, {
-            code: input.code,
-            name: input.name,
-            accountType: input.accountType,
-            currencyCode: input.currencyCode,
-        }),
+        execute: async (ctx, input) => {
+            // Normalize common LLM variations to exact API values
+            const typeMap = {
+                'current assets': 'Current Asset', 'current asset': 'Current Asset',
+                'fixed assets': 'Fixed Asset', 'fixed asset': 'Fixed Asset',
+                'bank account': 'Bank Accounts', 'bank accounts': 'Bank Accounts', 'bank': 'Bank Accounts',
+                'current liabilities': 'Current Liability', 'current liability': 'Current Liability',
+                'non-current liabilities': 'Non-current Liability', 'non-current liability': 'Non-current Liability',
+                'equity': 'Shareholders Equity', 'shareholders equity': 'Shareholders Equity', "shareholders' equity": 'Shareholders Equity', "shareholder's equity": 'Shareholders Equity',
+                'revenue': 'Operating Revenue', 'operating revenue': 'Operating Revenue',
+                'other revenue': 'Other Revenue', 'other income': 'Other Revenue',
+                'expense': 'Operating Expense', 'operating expense': 'Operating Expense', 'expenses': 'Operating Expense',
+                'direct costs': 'Direct Costs', 'cost of goods sold': 'Direct Costs', 'cogs': 'Direct Costs',
+                'cash': 'Cash', 'inventory': 'Inventory',
+            };
+            const rawType = input.accountType;
+            const accountType = typeMap[rawType.toLowerCase()] ?? rawType;
+            return createAccount(ctx.client, {
+                code: input.code,
+                name: input.name,
+                accountType,
+                currencyCode: input.currencyCode,
+            });
+        },
     },
     {
         name: 'update_account',
@@ -316,24 +334,39 @@ export const TOOL_DEFINITIONS = [
     listTool('list_invoices', 'List invoices. Returns reference, date, status, contact, totalAmount. Paginated — response includes totalElements. Use limit/offset to page.', 'invoices', (client, off, lim) => listInvoices(client, { limit: lim, offset: off })),
     {
         name: 'search_invoices',
-        description: 'Search invoices by reference or contact name. Returns up to 100 by default. Use limit/offset to page through large result sets.',
+        description: 'Search invoices by reference, contact name, and/or date range. Provide any combination of filters.',
         params: {
-            query: { type: 'string', description: 'Search term (reference or contact name)' },
+            query: { type: 'string', description: 'Search by invoice reference number' },
+            contactName: { type: 'string', description: 'Search by contact name' },
+            startDate: { type: 'string', description: 'Filter invoices on or after this date (YYYY-MM-DD)' },
+            endDate: { type: 'string', description: 'Filter invoices on or before this date (YYYY-MM-DD)' },
             ...SEARCH_PARAMS,
         },
-        required: ['query'],
+        required: [],
         group: 'invoices',
         readOnly: true,
         execute: async (ctx, input) => {
             const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
             const query = input.query;
+            const contactName = input.contactName;
+            const startDate = input.startDate;
+            const endDate = input.endDate;
+            // Build filter — avoid nested `contact` inside `or` (causes 400)
+            const filter = {};
+            if (query)
+                filter.reference = { contains: query };
+            if (contactName)
+                filter.contact = { name: { contains: contactName } };
+            if (startDate || endDate) {
+                const dateFilter = {};
+                if (startDate)
+                    dateFilter.gte = startDate;
+                if (endDate)
+                    dateFilter.lte = endDate;
+                filter.valueDate = dateFilter;
+            }
             return handlePaginationMode(mode, (off, lim) => searchInvoices(ctx.client, {
-                filter: query ? {
-                    or: [
-                        { reference: { contains: query } },
-                        { contact: { name: { contains: query } } },
-                    ],
-                } : undefined,
+                filter: Object.keys(filter).length > 0 ? filter : undefined,
                 limit: lim, offset: off,
                 sort: { sortBy: [sortBy ?? 'valueDate'], order: (sortOrder ?? 'DESC') },
             }), limit, offset, 100);
@@ -437,7 +470,7 @@ export const TOOL_DEFINITIONS = [
                 accountResourceId: input.accountResourceId,
                 valueDate: input.valueDate,
                 dueDate: input.valueDate,
-                reference: input.reference ?? '',
+                reference: input.reference || `PMT-${Date.now()}`,
                 paymentMethod: (input.paymentMethod ?? 'BANK_TRANSFER'),
                 saveAsDraft: false,
                 customFields: input.customFields, // eslint-disable-line @typescript-eslint/no-explicit-any
@@ -501,24 +534,38 @@ export const TOOL_DEFINITIONS = [
     listTool('list_bills', 'List bills (purchase invoices). Returns reference, date, status, contact, amounts. Paginated — response includes totalElements. Use limit/offset to page.', 'bills', (client, off, lim) => listBills(client, { limit: lim, offset: off })),
     {
         name: 'search_bills',
-        description: 'Search bills by reference or contact name. Returns up to 100 by default. Use limit/offset to page through large result sets.',
+        description: 'Search bills by reference, contact name, and/or date range. Provide any combination of filters.',
         params: {
-            query: { type: 'string', description: 'Search term' },
+            query: { type: 'string', description: 'Search by bill reference number' },
+            contactName: { type: 'string', description: 'Search by contact name' },
+            startDate: { type: 'string', description: 'Filter bills on or after this date (YYYY-MM-DD)' },
+            endDate: { type: 'string', description: 'Filter bills on or before this date (YYYY-MM-DD)' },
             ...SEARCH_PARAMS,
         },
-        required: ['query'],
+        required: [],
         group: 'bills',
         readOnly: true,
         execute: async (ctx, input) => {
             const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
             const query = input.query;
+            const contactName = input.contactName;
+            const startDate = input.startDate;
+            const endDate = input.endDate;
+            const filter = {};
+            if (query)
+                filter.reference = { contains: query };
+            if (contactName)
+                filter.contact = { name: { contains: contactName } };
+            if (startDate || endDate) {
+                const dateFilter = {};
+                if (startDate)
+                    dateFilter.gte = startDate;
+                if (endDate)
+                    dateFilter.lte = endDate;
+                filter.valueDate = dateFilter;
+            }
             return handlePaginationMode(mode, (off, lim) => searchBills(ctx.client, {
-                filter: query ? {
-                    or: [
-                        { reference: { contains: query } },
-                        { contact: { name: { contains: query } } },
-                    ],
-                } : undefined,
+                filter: Object.keys(filter).length > 0 ? filter : undefined,
                 limit: lim, offset: off,
                 sort: { sortBy: [sortBy ?? 'valueDate'], order: (sortOrder ?? 'DESC') },
             }), limit, offset, 100);
@@ -625,7 +672,7 @@ export const TOOL_DEFINITIONS = [
                 accountResourceId: input.accountResourceId,
                 valueDate: input.valueDate,
                 dueDate: input.valueDate,
-                reference: input.reference ?? '',
+                reference: input.reference || `PMT-${Date.now()}`,
                 paymentMethod: (input.paymentMethod ?? 'BANK_TRANSFER'),
                 saveAsDraft: false,
                 customFields: input.customFields, // eslint-disable-line @typescript-eslint/no-explicit-any
@@ -1143,7 +1190,12 @@ export const TOOL_DEFINITIONS = [
         required: ['valueDate', 'contactResourceId', 'lineItems'],
         group: 'customer_credit_notes',
         readOnly: false,
-        execute: async (ctx, input) => createCustomerCreditNote(ctx.client, input),
+        execute: async (ctx, input) => {
+            const data = { ...input };
+            if (!data.reference)
+                data.reference = `CCN-${Date.now()}`;
+            return createCustomerCreditNote(ctx.client, data);
+        },
     },
     {
         name: 'delete_customer_credit_note',
@@ -1307,7 +1359,12 @@ export const TOOL_DEFINITIONS = [
         required: ['valueDate', 'contactResourceId', 'lineItems'],
         group: 'supplier_credit_notes',
         readOnly: false,
-        execute: async (ctx, input) => createSupplierCreditNote(ctx.client, input),
+        execute: async (ctx, input) => {
+            const data = { ...input };
+            if (!data.reference)
+                data.reference = `SCN-${Date.now()}`;
+            return createSupplierCreditNote(ctx.client, data);
+        },
     },
     {
         name: 'delete_supplier_credit_note',
@@ -1525,9 +1582,10 @@ export const TOOL_DEFINITIONS = [
     listTool('list_cash_in', 'List cash-in entries (direct cash receipts). Paginated.', 'cash_entries', (client, off, lim) => listCashIn(client, { limit: lim, offset: off })),
     {
         name: 'create_cash_in',
-        description: `Create a direct cash-in entry. IMPORTANT:
-- journalEntries must have accountResourceId, type (DEBIT/CREDIT), and amount.
-- accountResourceId is the bank/cash account receiving the money.`,
+        description: `Create a direct cash-in entry (money received). IMPORTANT:
+- accountResourceId is the bank/cash account receiving the money. Must be a "Bank Accounts" or "Cash" type account that is NOT used for cash-out.
+- journalEntries are the offsetting entries (e.g., revenue account). Each needs accountResourceId, type (DEBIT/CREDIT), and amount.
+- The API enforces account separation: cash-in accounts cannot be used for cash-out and vice versa.`,
         params: {
             reference: { type: 'string', description: 'Reference number' },
             valueDate: { type: 'string', description: 'Date (YYYY-MM-DD)' },
@@ -1553,12 +1611,20 @@ export const TOOL_DEFINITIONS = [
         required: ['valueDate', 'accountResourceId', 'journalEntries'],
         group: 'cash_entries',
         readOnly: false,
-        execute: async (ctx, input) => createCashIn(ctx.client, input),
+        execute: async (ctx, input) => {
+            const data = { ...input };
+            if (!data.reference)
+                data.reference = `CI-${Date.now()}`;
+            return createCashIn(ctx.client, data);
+        },
     },
     listTool('list_cash_out', 'List cash-out entries (direct cash disbursements). Paginated.', 'cash_entries', (client, off, lim) => listCashOut(client, { limit: lim, offset: off })),
     {
         name: 'create_cash_out',
-        description: 'Create a direct cash-out entry. Same structure as create_cash_in.',
+        description: `Create a direct cash-out entry (money paid out). IMPORTANT:
+- accountResourceId is the bank/cash account disbursing the money. Must be a "Bank Accounts" or "Cash" type account that is NOT used for cash-in.
+- journalEntries are the offsetting entries (e.g., expense account). Each needs accountResourceId, type (DEBIT/CREDIT), and amount.
+- The API enforces account separation: cash-out accounts cannot be used for cash-in and vice versa.`,
         params: {
             reference: { type: 'string', description: 'Reference number' },
             valueDate: { type: 'string', description: 'Date (YYYY-MM-DD)' },
@@ -1584,7 +1650,12 @@ export const TOOL_DEFINITIONS = [
         required: ['valueDate', 'accountResourceId', 'journalEntries'],
         group: 'cash_entries',
         readOnly: false,
-        execute: async (ctx, input) => createCashOut(ctx.client, input),
+        execute: async (ctx, input) => {
+            const data = { ...input };
+            if (!data.reference)
+                data.reference = `CO-${Date.now()}`;
+            return createCashOut(ctx.client, data);
+        },
     },
     {
         name: 'get_cash_in',
@@ -1650,7 +1721,10 @@ export const TOOL_DEFINITIONS = [
     listTool('list_cash_transfers', 'List cash transfer entries. Paginated.', 'cash_transfers', (client, off, lim) => listCashTransfers(client, { limit: lim, offset: off })),
     {
         name: 'create_cash_transfer',
-        description: 'Create a cash transfer between two accounts. Requires cashOut and cashIn sides.',
+        description: `Create a cash transfer between two accounts. IMPORTANT:
+- reference is required (auto-generated if not provided).
+- Both cashOut and cashIn sides need accountResourceId and journalEntries with amount.
+- cashOut.journalEntries[].amount is required — this is the transfer amount.`,
         params: {
             reference: { type: 'string', description: 'Reference number' },
             valueDate: { type: 'string', description: 'Date (YYYY-MM-DD)' },
@@ -1699,7 +1773,12 @@ export const TOOL_DEFINITIONS = [
         required: ['valueDate', 'cashOut', 'cashIn'],
         group: 'cash_transfers',
         readOnly: false,
-        execute: async (ctx, input) => createCashTransfer(ctx.client, input),
+        execute: async (ctx, input) => {
+            const data = { ...input };
+            if (!data.reference)
+                data.reference = `CT-${Date.now()}`;
+            return createCashTransfer(ctx.client, data);
+        },
     },
     // ── Scheduled Transactions ─────────────────────────────────────
     listTool('list_scheduled_invoices', 'List scheduled (recurring) invoices. Paginated.', 'schedulers', (client, off, lim) => listScheduledInvoices(client, { limit: lim, offset: off })),
@@ -1858,10 +1937,10 @@ export const TOOL_DEFINITIONS = [
                 items: {
                     type: 'object',
                     properties: {
-                        module: { type: 'string', description: 'Module (e.g., ACCOUNTING, SALES)' },
-                        role: { type: 'string', description: 'Role (e.g., ADMIN, VIEWER)' },
+                        moduleName: { type: 'string', description: 'Module name: ORGANIZATION, USER_MANAGEMENT, ACCOUNTING, SALES, PURCHASES, REPORTS, or FIXED_ASSET' },
+                        roleCode: { type: 'string', description: 'Role code: ADMIN, PREPARER, MEMBER, or NO_ACCESS' },
                     },
-                    required: ['module', 'role'],
+                    required: ['moduleName', 'roleCode'],
                 },
                 description: 'Module role assignments',
             },
@@ -1881,10 +1960,10 @@ export const TOOL_DEFINITIONS = [
                 items: {
                     type: 'object',
                     properties: {
-                        module: { type: 'string' },
-                        role: { type: 'string' },
+                        moduleName: { type: 'string', description: 'Module name: ORGANIZATION, USER_MANAGEMENT, ACCOUNTING, SALES, PURCHASES, REPORTS, or FIXED_ASSET' },
+                        roleCode: { type: 'string', description: 'Role code: ADMIN, PREPARER, MEMBER, or NO_ACCESS' },
                     },
-                    required: ['module', 'role'],
+                    required: ['moduleName', 'roleCode'],
                 },
             },
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jaz-clio",
-  "version": "4.25.5",
+  "version": "4.25.7",
   "description": "Clio — Command Line Interface Orchestrator for Jaz AI.",
   "type": "module",
   "bin": {