jaz-clio 4.28.0 → 4.29.0

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 4.28.0
+version: 4.29.0
 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.28.0
+version: 4.29.0
 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.28.0
+version: 4.29.0
 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.28.0
+version: 4.29.0
 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/commands/bills.js

@@ -6,6 +6,7 @@ import { apiAction } from './api-action.js';
 import { resolveContactFlag, resolveAccountFlag, resolveTaxProfileFlag } from './resolve.js';
 import { parsePositiveInt, parseNonNegativeInt, parseMoney, parseRate, parseLineItems, parseCustomFields, readBodyInput, requireFields } from './parsers.js';
 import { paginatedFetch } from './pagination.js';
+import { buildInvoiceBillFilter } from '../core/registry/pagination.js';
 import { outputList } from './output.js';
 import { BILL_REQUIRED_FIELDS, buildDraftReport, formatDraftTable, addDraftFinalizeOptions, mergeDraftFlags, validateDraft, buildValidation, normalizeDate, sanitizeLineItem, } from './draft-helpers.js';
 const BILL_COLUMNS = [
@@ -73,7 +74,7 @@ export function registerBillsCommand(program) {
         .command('search')
         .description('Search bills with filters')
         .option('--ref <reference>', 'Filter by reference (contains)')
-        .option('--status <status>', 'Filter by status (DRAFT, UNPAID, PAID, OVERDUE, VOIDED)')
+        .option('--status <status>', 'Filter by status (DRAFT, UNPAID, PARTIALLY_PAID, PAID, OVERDUE, VOID)')
         .option('--contact <resourceId>', 'Filter by contact name or resourceId')
         .option('--tag <name>', 'Filter by tag')
         .option('--min-amount <n>', 'Minimum total amount', parseMoney)
@@ -97,40 +98,13 @@ export function registerBillsCommand(program) {
             const resolved = await resolveContactFlag(client, opts.contact, { silent: opts.json });
             opts.contact = resolved.resourceId;
         }
-        const filter = {};
-        if (opts.ref)
-            filter.reference = { contains: opts.ref };
-        if (opts.status)
-            filter.status = { eq: opts.status };
-        if (opts.contact)
-            filter.contactResourceId = { eq: opts.contact };
-        if (opts.tag)
-            filter.tags = { eq: opts.tag };
-        if (opts.minAmount !== undefined || opts.maxAmount !== undefined) {
-            const af = {};
-            if (opts.minAmount !== undefined)
-                af.gte = opts.minAmount;
-            if (opts.maxAmount !== undefined)
-                af.lte = opts.maxAmount;
-            filter.totalAmount = af;
-        }
-        if (opts.from || opts.to) {
-            const dateFilter = {};
-            if (opts.from)
-                dateFilter.gte = opts.from;
-            if (opts.to)
-                dateFilter.lte = opts.to;
-            filter.valueDate = dateFilter;
-        }
-        if (opts.dueFrom || opts.dueTo) {
-            const df = {};
-            if (opts.dueFrom)
-                df.gte = opts.dueFrom;
-            if (opts.dueTo)
-                df.lte = opts.dueTo;
-            filter.dueDate = df;
-        }
-        const searchFilter = Object.keys(filter).length > 0 ? filter : undefined;
+        const searchFilter = buildInvoiceBillFilter({
+            reference: opts.ref, status: opts.status,
+            contactResourceId: opts.contact, tag: opts.tag,
+            minAmount: opts.minAmount, maxAmount: opts.maxAmount,
+            startDate: opts.from, endDate: opts.to,
+            dueDateFrom: opts.dueFrom, dueDateTo: opts.dueTo,
+        });
         const sort = { sortBy: [opts.sort ?? 'valueDate'], order: (opts.order ?? 'DESC') };
         const result = await paginatedFetch(opts, ({ limit, offset }) => searchBills(client, { filter: searchFilter, limit, offset, sort }), { label: 'Searching bills', defaultLimit: 20 });
         outputList(result, BILL_COLUMNS, opts, 'Bills'); // eslint-disable-line @typescript-eslint/no-explicit-any

package/dist/commands/cashflow.js

@@ -3,6 +3,7 @@ import { searchCashflowTransactions } from '../core/api/cashflow.js';
 import { apiAction } from './api-action.js';
 import { parsePositiveInt, parseNonNegativeInt } from './parsers.js';
 import { paginatedFetch } from './pagination.js';
+import { buildCashflowFilter } from '../core/registry/pagination.js';
 import { outputList } from './output.js';
 import { formatId, formatReference, formatDirection, formatEpochDate } from './format-helpers.js';
 const CASHFLOW_COLUMNS = [
@@ -37,22 +38,10 @@ export function registerCashflowCommand(program) {
         .option('--api-key <key>', 'API key (overrides stored/env)')
         .option('--json', 'Output as JSON')
         .action(apiAction(async (client, opts) => {
-        const filter = {};
-        if (opts.ref)
-            filter.transactionReference = { contains: opts.ref };
-        if (opts.type)
-            filter.businessTransactionType = { eq: opts.type };
-        if (opts.direction)
-            filter.direction = { eq: opts.direction };
-        if (opts.from || opts.to) {
-            const dateFilter = {};
-            if (opts.from)
-                dateFilter.gte = opts.from;
-            if (opts.to)
-                dateFilter.lte = opts.to;
-            filter.valueDate = dateFilter;
-        }
-        const searchFilter = Object.keys(filter).length > 0 ? filter : undefined;
+        const searchFilter = buildCashflowFilter({
+            reference: opts.ref, businessTransactionType: opts.type,
+            direction: opts.direction, startDate: opts.from, endDate: opts.to,
+        });
         const sort = { sortBy: [opts.sort ?? 'valueDate'], order: (opts.order ?? 'DESC') };
         const result = await paginatedFetch(opts, ({ limit, offset }) => searchCashflowTransactions(client, { filter: searchFilter, limit, offset, sort }), { label: 'Searching cashflow transactions', defaultLimit: 20 });
         outputList(result, CASHFLOW_COLUMNS, opts, 'Cashflow'); // eslint-disable-line @typescript-eslint/no-explicit-any

package/dist/commands/contacts.js

@@ -4,6 +4,7 @@ import { apiAction } from './api-action.js';
 import { outputList } from './output.js';
 import { parsePositiveInt, parseNonNegativeInt, readBodyInput, requireFields } from './parsers.js';
 import { paginatedFetch } from './pagination.js';
+import { buildContactFilter } from '../core/registry/pagination.js';
 import { formatId } from './format-helpers.js';
 const CONTACTS_COLUMNS = [
     { key: 'resourceId', header: 'ID', format: formatId },
@@ -48,16 +49,13 @@ export function registerContactsCommand(program) {
         .option('--format <type>', 'Output format: table, json, csv, yaml')
         .option('--json', 'Output as JSON')
         .action((query, opts) => apiAction(async (client) => {
-        const filter = {
-            status: { eq: opts.status ?? 'ACTIVE' },
-            name: { contains: query },
-        };
-        if (opts.customer)
-            filter.customer = { eq: true };
-        if (opts.supplier)
-            filter.supplier = { eq: true };
-        if (opts.email)
-            filter.email = { contains: opts.email };
+        const filter = buildContactFilter({
+            query,
+            isCustomer: opts.customer ? true : undefined,
+            isSupplier: opts.supplier ? true : undefined,
+            status: opts.status ?? 'ACTIVE',
+            email: opts.email,
+        });
         const sort = { sortBy: [opts.sort ?? 'name'], order: (opts.order ?? 'ASC') };
         const result = await paginatedFetch(opts, ({ limit, offset }) => searchContacts(client, { filter, limit, offset, sort }), { label: 'Searching contacts', defaultLimit: 20 });
         outputList(result, CONTACTS_COLUMNS, opts, 'Contacts'); // eslint-disable-line @typescript-eslint/no-explicit-any

package/dist/commands/customer-credit-notes.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
 import { formatStatus, formatId, formatReference, formatCurrency } from './format-helpers.js';
+import { buildCnFilter } from '../core/registry/index.js';
 import { listCustomerCreditNotes, getCustomerCreditNote, searchCustomerCreditNotes, createCustomerCreditNote, updateCustomerCreditNote, deleteCustomerCreditNote, createCustomerCreditNoteRefund, listCustomerCreditNoteRefunds, finalizeCustomerCreditNote, downloadCustomerCreditNotePdf, } from '../core/api/customer-cn.js';
 import { listAttachments } from '../core/api/attachments.js';
 import { apiAction } from './api-action.js';
@@ -87,14 +88,7 @@ export function registerCustomerCreditNotesCommand(program) {
             const resolved = await resolveContactFlag(client, opts.contact, { silent: opts.json });
             opts.contact = resolved.resourceId;
         }
-        const filter = {};
-        if (opts.ref)
-            filter.reference = { contains: opts.ref };
-        if (opts.status)
-            filter.status = { eq: opts.status };
-        if (opts.contact)
-            filter.contactResourceId = { eq: opts.contact };
-        const searchFilter = Object.keys(filter).length > 0 ? filter : undefined;
+        const searchFilter = buildCnFilter({ reference: opts.ref, status: opts.status, contactResourceId: opts.contact });
         const sort = { sortBy: [opts.sort ?? 'valueDate'], order: (opts.order ?? 'DESC') };
         const result = await paginatedFetch(opts, ({ limit, offset }) => searchCustomerCreditNotes(client, { filter: searchFilter, limit, offset, sort }), { label: 'Searching customer credit notes', defaultLimit: 20 });
         outputList(result, CCN_COLUMNS, opts, 'Customer Credit Notes'); // eslint-disable-line @typescript-eslint/no-explicit-any

package/dist/commands/fixed-assets.js

@@ -72,7 +72,7 @@ export function registerFixedAssetsCommand(program) {
         if (opts.status)
             filter.status = { eq: opts.status };
         if (opts.tag)
-            filter.tags = { eq: opts.tag };
+            filter.tags = { name: { eq: opts.tag } };
         if (opts.category)
             filter.category = { eq: opts.category };
         if (opts.reference)

package/dist/commands/invoices.js

@@ -6,6 +6,7 @@ import { apiAction } from './api-action.js';
 import { resolveContactFlag, resolveAccountFlag, resolveTaxProfileFlag } from './resolve.js';
 import { parsePositiveInt, parseNonNegativeInt, parseMoney, parseRate, parseLineItems, parseCustomFields, readBodyInput, requireFields } from './parsers.js';
 import { paginatedFetch } from './pagination.js';
+import { buildInvoiceBillFilter } from '../core/registry/pagination.js';
 import { outputList } from './output.js';
 import { INVOICE_REQUIRED_FIELDS, buildDraftReport, formatDraftTable, addDraftFinalizeOptions, mergeDraftFlags, validateDraft, buildValidation, normalizeDate, sanitizeLineItem, } from './draft-helpers.js';
 const INVOICE_COLUMNS = [
@@ -75,7 +76,7 @@ export function registerInvoicesCommand(program) {
         .command('search')
         .description('Search invoices with filters')
         .option('--ref <reference>', 'Filter by reference (contains)')
-        .option('--status <status>', 'Filter by status (DRAFT, UNPAID, PAID, OVERDUE, VOIDED)')
+        .option('--status <status>', 'Filter by status (DRAFT, UNPAID, PARTIALLY_PAID, PAID, OVERDUE, VOID)')
         .option('--contact <resourceId>', 'Filter by contact name or resourceId')
         .option('--tag <name>', 'Filter by tag')
         .option('--min-amount <n>', 'Minimum total amount', parseMoney)
@@ -99,40 +100,13 @@ export function registerInvoicesCommand(program) {
             const resolved = await resolveContactFlag(client, opts.contact, { silent: opts.json });
             opts.contact = resolved.resourceId;
         }
-        const filter = {};
-        if (opts.ref)
-            filter.reference = { contains: opts.ref };
-        if (opts.status)
-            filter.status = { eq: opts.status };
-        if (opts.contact)
-            filter.contactResourceId = { eq: opts.contact };
-        if (opts.tag)
-            filter.tags = { eq: opts.tag };
-        if (opts.minAmount !== undefined || opts.maxAmount !== undefined) {
-            const af = {};
-            if (opts.minAmount !== undefined)
-                af.gte = opts.minAmount;
-            if (opts.maxAmount !== undefined)
-                af.lte = opts.maxAmount;
-            filter.totalAmount = af;
-        }
-        if (opts.from || opts.to) {
-            const dateFilter = {};
-            if (opts.from)
-                dateFilter.gte = opts.from;
-            if (opts.to)
-                dateFilter.lte = opts.to;
-            filter.valueDate = dateFilter;
-        }
-        if (opts.dueFrom || opts.dueTo) {
-            const df = {};
-            if (opts.dueFrom)
-                df.gte = opts.dueFrom;
-            if (opts.dueTo)
-                df.lte = opts.dueTo;
-            filter.dueDate = df;
-        }
-        const searchFilter = Object.keys(filter).length > 0 ? filter : undefined;
+        const searchFilter = buildInvoiceBillFilter({
+            reference: opts.ref, status: opts.status,
+            contactResourceId: opts.contact, tag: opts.tag,
+            minAmount: opts.minAmount, maxAmount: opts.maxAmount,
+            startDate: opts.from, endDate: opts.to,
+            dueDateFrom: opts.dueFrom, dueDateTo: opts.dueTo,
+        });
         const sort = { sortBy: [opts.sort ?? 'valueDate'], order: (opts.order ?? 'DESC') };
         const result = await paginatedFetch(opts, ({ limit, offset }) => searchInvoices(client, { filter: searchFilter, limit, offset, sort }), { label: 'Searching invoices', defaultLimit: 20 });
         outputList(result, INVOICE_COLUMNS, opts, 'Invoices'); // eslint-disable-line @typescript-eslint/no-explicit-any

package/dist/commands/journals.js

@@ -6,6 +6,7 @@ import { apiAction } from './api-action.js';
 import { resolveAccountFlag } from './resolve.js';
 import { parsePositiveInt, parseNonNegativeInt, parseJournalEntries, readBodyInput, requireFields } from './parsers.js';
 import { paginatedFetch } from './pagination.js';
+import { buildJournalFilter } from '../core/registry/pagination.js';
 import { outputList } from './output.js';
 import { JOURNAL_REQUIRED_FIELDS, buildDraftReport, formatDraftTable, addJournalDraftFinalizeOptions, mergeJournalDraftFlags, validateDraft, buildValidation, normalizeDate, sanitizeJournalEntry, } from './draft-helpers.js';
 const JOURNAL_COLUMNS = [
@@ -41,7 +42,7 @@ export function registerJournalsCommand(program) {
         .option('--ref <reference>', 'Filter by reference (contains)')
         .option('--from <YYYY-MM-DD>', 'Filter from date (inclusive)')
         .option('--to <YYYY-MM-DD>', 'Filter to date (inclusive)')
-        .option('--status <status>', 'Filter by status (DRAFT, FINALIZED)')
+        .option('--status <status>', 'Filter by status (DRAFT, FINALIZED, VOID)')
         .option('--tag <name>', 'Filter by tag')
         .option('--type <type>', 'Filter by type (JOURNAL_MANUAL, JOURNAL_DIRECT_CASH_IN, JOURNAL_DIRECT_CASH_OUT)')
         .option('--sort <field>', 'Sort field (default: valueDate)')
@@ -54,24 +55,10 @@ export function registerJournalsCommand(program) {
         .option('--api-key <key>', 'API key (overrides stored/env)')
         .option('--json', 'Output as JSON')
         .action(apiAction(async (client, opts) => {
-        const filter = {};
-        if (opts.ref)
-            filter.reference = { contains: opts.ref };
-        if (opts.status)
-            filter.status = { eq: opts.status };
-        if (opts.tag)
-            filter.tags = { eq: opts.tag };
-        if (opts.type)
-            filter.type = { eq: opts.type };
-        if (opts.from || opts.to) {
-            const dateFilter = {};
-            if (opts.from)
-                dateFilter.gte = opts.from;
-            if (opts.to)
-                dateFilter.lte = opts.to;
-            filter.valueDate = dateFilter;
-        }
-        const searchFilter = Object.keys(filter).length > 0 ? filter : undefined;
+        const searchFilter = buildJournalFilter({
+            reference: opts.ref, status: opts.status, tag: opts.tag,
+            type: opts.type, startDate: opts.from, endDate: opts.to,
+        });
         const sort = { sortBy: [opts.sort ?? 'valueDate'], order: (opts.order ?? 'DESC') };
         const result = await paginatedFetch(opts, ({ limit, offset }) => searchJournals(client, { filter: searchFilter, limit, offset, sort }), { label: 'Searching journals', defaultLimit: 20 });
         outputList(result, JOURNAL_COLUMNS, opts, 'Journals'); // eslint-disable-line @typescript-eslint/no-explicit-any

package/dist/commands/supplier-credit-notes.js

@@ -1,5 +1,6 @@
 import chalk from 'chalk';
 import { formatStatus, formatId, formatReference, formatCurrency } from './format-helpers.js';
+import { buildCnFilter } from '../core/registry/index.js';
 import { listSupplierCreditNotes, getSupplierCreditNote, searchSupplierCreditNotes, createSupplierCreditNote, updateSupplierCreditNote, deleteSupplierCreditNote, createSupplierCreditNoteRefund, listSupplierCreditNoteRefunds, finalizeSupplierCreditNote, } from '../core/api/supplier-cn.js';
 import { listAttachments } from '../core/api/attachments.js';
 import { apiAction } from './api-action.js';
@@ -87,14 +88,7 @@ export function registerSupplierCreditNotesCommand(program) {
             const resolved = await resolveContactFlag(client, opts.contact, { silent: opts.json });
             opts.contact = resolved.resourceId;
         }
-        const filter = {};
-        if (opts.ref)
-            filter.reference = { contains: opts.ref };
-        if (opts.status)
-            filter.status = { eq: opts.status };
-        if (opts.contact)
-            filter.contactResourceId = { eq: opts.contact };
-        const searchFilter = Object.keys(filter).length > 0 ? filter : undefined;
+        const searchFilter = buildCnFilter({ reference: opts.ref, status: opts.status, contactResourceId: opts.contact });
         const sort = { sortBy: [opts.sort ?? 'valueDate'], order: (opts.order ?? 'DESC') };
         const result = await paginatedFetch(opts, ({ limit, offset }) => searchSupplierCreditNotes(client, { filter: searchFilter, limit, offset, sort }), { label: 'Searching supplier credit notes', defaultLimit: 20 });
         outputList(result, SCN_COLUMNS, opts, 'Supplier Credit Notes'); // eslint-disable-line @typescript-eslint/no-explicit-any

package/dist/core/api/pagination.js

@@ -24,18 +24,20 @@ export async function fetchAllPages(fetcher, options = {}) {
     const pageSize = Math.min(Math.max(options.pageSize ?? DEFAULT_PAGE_SIZE, 1), 1000);
     const rawConcurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
     const concurrency = Math.max(Math.floor(rawConcurrency), 1);
+    const maxItems = options.maxItems ?? Infinity;
     const onProgress = options.onProgress;
     // ── Step 1: First page ──
     const firstPage = await fetcher(0, pageSize);
     const total = firstPage.totalElements;
     let requestCount = 1;
-    // Short-circuit: single page or empty
-    if (total <= pageSize) {
-        onProgress?.(firstPage.data.length, total);
+    // Short-circuit: single page, empty, or maxItems satisfied by first page
+    if (total <= pageSize || firstPage.data.length >= maxItems) {
+        const data = maxItems < Infinity ? firstPage.data.slice(0, maxItems) : firstPage.data;
+        onProgress?.(data.length, total);
         return {
-            data: firstPage.data,
+            data,
             totalElements: total,
-            truncated: false,
+            truncated: data.length < total,
             requestCount,
         };
     }
@@ -59,11 +61,14 @@ export async function fetchAllPages(fetcher, options = {}) {
             allData.push(...page.data);
         }
         onProgress?.(allData.length, total);
+        if (allData.length >= maxItems)
+            break;
     }
+    const cappedData = maxItems < Infinity ? allData.slice(0, maxItems) : allData;
     return {
-        data: allData,
+        data: cappedData,
         totalElements: total,
-        truncated,
+        truncated: truncated || cappedData.length < allData.length,
         requestCount,
     };
 }

package/dist/core/registry/index.js

@@ -1,3 +1,3 @@
 export { TOOL_DEFINITIONS } from './tools.js';
 export { getToolByName, getAllTools, getToolsByGroup, getReadOnlyTools, getWriteTools, getToolCount, } from './lookup.js';
-export { handlePaginationMode, buildCnFilter } from './pagination.js';
+export { handlePagination, buildCnFilter, buildBankRecordFilter, buildInvoiceBillFilter, buildJournalFilter, buildContactFilter, buildCashflowFilter } from './pagination.js';

package/dist/core/registry/pagination.js

@@ -1,45 +1,6 @@
-/**
- * Pagination mode helpers for list/search tools.
- * Moved from agent/tools.ts — shared by all list/search tool execute functions.
- */
-import { fetchAllPages } from '../api/pagination.js';
-/**
- * Handle pagination mode for list/search tools.
- * DRY helper — all list/search tools route through this.
- *
- * Modes:
- *   - default (omit mode): caller sets limit/offset (offset = page number, 0-indexed)
- *   - 'sample': returns 20 items + totalElements metadata
- *   - 'all': fetches all pages concurrently via fetchAllPages
- */
-export async function handlePaginationMode(mode, fetcher, limit, offset, defaultLimit) {
-    switch (mode) {
-        case 'all': {
-            const pageSize = Math.min(Math.max(limit ?? 200, 1), 1000);
-            const result = await fetchAllPages(fetcher, { pageSize, concurrency: 3 });
-            return {
-                _mode: 'all',
-                _note: result.truncated
-                    ? `Fetched ${result.data.length} of ${result.totalElements} items (offset cap: 65,536). ${result.requestCount} API calls.`
-                    : `Fetched all ${result.totalElements} items. ${result.requestCount} API calls.`,
-                data: result.data,
-                totalElements: result.totalElements,
-                truncated: result.truncated,
-            };
-        }
-        case 'sample': {
-            const result = await fetcher(0, 20);
-            return {
-                _mode: 'sample',
-                _note: `Showing ${result.data.length} of ${result.totalElements} items. Use limit/offset to page, or mode 'all' to fetch everything.`,
-                data: result.data,
-                totalElements: result.totalElements,
-                totalPages: result.totalPages,
-            };
-        }
-        default:
-            return fetcher(offset ?? 0, limit ?? defaultLimit);
-    }
+/** Paginate a tool call with sensible defaults. */
+export async function handlePagination(fetcher, limit, offset, defaultLimit) {
+    return fetcher(offset ?? 0, limit ?? defaultLimit);
 }
 /** Build a credit note search filter from agent input (shared by customer + supplier CN search). */
 export function buildCnFilter(input) {
@@ -52,6 +13,106 @@ export function buildCnFilter(input) {
         f.contactResourceId = { eq: input.contactResourceId };
     return Object.keys(f).length > 0 ? f : undefined;
 }
+/** Build invoice/bill search filter (shared by CLI + tool + MCP). */
+export function buildInvoiceBillFilter(input) {
+    const f = {};
+    if (input.reference)
+        f.reference = { contains: input.reference };
+    if (input.status)
+        f.status = { eq: input.status };
+    if (input.contactResourceId)
+        f.contactResourceId = { eq: input.contactResourceId };
+    if (input.contactName)
+        f.contact = { name: { contains: input.contactName } };
+    if (input.tag)
+        f.tags = { name: { eq: input.tag } };
+    if (input.currencyCode)
+        f.currencyCode = { eq: input.currencyCode };
+    const minAmt = typeof input.minAmount === 'number' && Number.isFinite(input.minAmount) ? input.minAmount : undefined;
+    const maxAmt = typeof input.maxAmount === 'number' && Number.isFinite(input.maxAmount) ? input.maxAmount : undefined;
+    if (minAmt != null || maxAmt != null) {
+        const a = {};
+        if (minAmt != null)
+            a.gte = minAmt;
+        if (maxAmt != null)
+            a.lte = maxAmt;
+        f.totalAmount = a;
+    }
+    if (input.startDate || input.endDate) {
+        const d = {};
+        if (input.startDate)
+            d.gte = input.startDate;
+        if (input.endDate)
+            d.lte = input.endDate;
+        f.valueDate = d;
+    }
+    if (input.dueDateFrom || input.dueDateTo) {
+        const d = {};
+        if (input.dueDateFrom)
+            d.gte = input.dueDateFrom;
+        if (input.dueDateTo)
+            d.lte = input.dueDateTo;
+        f.dueDate = d;
+    }
+    return Object.keys(f).length > 0 ? f : undefined;
+}
+/** Build journal search filter (shared by CLI + tool + MCP). */
+export function buildJournalFilter(input) {
+    const f = {};
+    if (input.reference)
+        f.reference = { contains: input.reference };
+    if (input.status)
+        f.status = { eq: input.status };
+    if (input.tag)
+        f.tags = { name: { eq: input.tag } };
+    if (input.type)
+        f.type = { eq: input.type };
+    if (input.startDate || input.endDate) {
+        const d = {};
+        if (input.startDate)
+            d.gte = input.startDate;
+        if (input.endDate)
+            d.lte = input.endDate;
+        f.valueDate = d;
+    }
+    return Object.keys(f).length > 0 ? f : undefined;
+}
+/** Build contact search filter (shared by CLI + tool + MCP). */
+export function buildContactFilter(input) {
+    const f = {};
+    if (input.query)
+        f.or = { billingName: { contains: input.query }, name: { contains: input.query } };
+    if (input.isCustomer !== undefined)
+        f.customer = { eq: input.isCustomer };
+    if (input.isSupplier !== undefined)
+        f.supplier = { eq: input.isSupplier };
+    if (input.status)
+        f.status = { eq: input.status };
+    if (input.email)
+        f.email = { contains: input.email };
+    return Object.keys(f).length > 0 ? f : undefined;
+}
+/** Build cashflow transaction search filter (shared by CLI + tool + MCP). */
+export function buildCashflowFilter(input) {
+    const f = {};
+    if (input.businessTransactionType)
+        f.businessTransactionType = { eq: input.businessTransactionType };
+    if (input.direction)
+        f.direction = { eq: input.direction };
+    if (input.status)
+        f.businessTransactionStatus = { eq: input.status };
+    if (input.reference)
+        f.transactionReference = { contains: input.reference };
+    if (input.startDate || input.endDate) {
+        const d = {};
+        if (input.startDate)
+            d.gte = input.startDate;
+        if (input.endDate)
+            d.lte = input.endDate;
+        f.valueDate = d;
+    }
+    return Object.keys(f).length > 0 ? f : undefined;
+}
 /** Build a bank record search filter (shared by CLI + MCP tool). */
 export function buildBankRecordFilter(input) {
     const f = {};

package/dist/core/registry/tools.js

@@ -29,7 +29,7 @@ import { downloadExport } from '../api/data-exports.js';
 import { listAttachments, addAttachment, fetchAttachmentTable } from '../api/attachments.js';
 import { createFromAttachment, searchMagicWorkflows } from '../api/magic.js';
 import { messageToPdf } from '../api/message-pdf.js';
-import { handlePaginationMode, buildCnFilter, buildBankRecordFilter } from './pagination.js';
+import { handlePagination, buildCnFilter, buildBankRecordFilter, buildInvoiceBillFilter, buildJournalFilter, buildContactFilter, buildCashflowFilter } from './pagination.js';
 // New API modules (200-tools expansion)
 import { listBankRules, getBankRule, searchBankRules, createBankRule, updateBankRule, deleteBankRule, } from '../api/bank-rules.js';
 import { listFixedAssets, getFixedAsset, searchFixedAssets, createFixedAsset, updateFixedAsset, deleteFixedAsset, discardFixedAsset, markFixedAssetSold, transferFixedAsset, undoFixedAssetDisposal, } from '../api/fixed-assets.js';
@@ -55,13 +55,12 @@ import { generateStatutoryFilingBlueprint } from '../jobs/statutory-filing/bluep
 import { buildDraftReport, INVOICE_REQUIRED_FIELDS, BILL_REQUIRED_FIELDS, CREDIT_NOTE_REQUIRED_FIELDS, JOURNAL_REQUIRED_FIELDS, } from '../drafts/index.js';
 // ── Shared param snippets (DRY) ─────────────────────────────────
 const PAGINATION_PARAMS = {
-    limit: { type: 'number', description: 'Max results per page (default 100, max 1000)' },
-    offset: { type: 'number', description: 'Pagination offset (use with limit to page through results)' },
-    mode: { type: 'string', enum: ['sample', 'all'], description: "Pagination mode: 'sample' (20 items + total count), 'all' (fetch everything — may be slow for large datasets). Omit for default limit/offset behavior." },
+    limit: { type: 'number', description: 'Max results per page (default 20, max 1000).' },
+    offset: { type: 'number', description: 'Page offset (0-indexed). Use with limit to paginate.' },
 };
 const SEARCH_PARAMS = {
     ...PAGINATION_PARAMS,
-    sortBy: { type: 'string', description: 'Sort field (overrides default)' },
+    sortBy: { type: 'string', description: 'Sort field (always sent with queries). Common: valueDate, reference, status, name. Default: valueDate' },
     order: { type: 'string', enum: ['ASC', 'DESC'], description: 'Sort direction' },
 };
 const CURRENCY_PARAM = {
@@ -122,13 +121,12 @@ const LINE_ITEM_PARAM = {
 };
 // ── Helper to extract common input fields ────────────────────────
 function extractPaginationInput(input) {
-    const mode = input.mode;
     const limit = input.limit;
     const offset = input.offset;
     const sortBy = input.sortBy;
     const rawOrder = input.order;
     const sortOrder = rawOrder === 'ASC' || rawOrder === 'DESC' ? rawOrder : undefined;
-    return { mode, limit, offset, sortBy, sortOrder };
+    return { limit, offset, sortBy, sortOrder };
 }
 // ── List tool factory (DRY — all 10 list tools share this) ───────
 function listTool(name, description, group, fetcher) {
@@ -140,8 +138,8 @@ function listTool(name, description, group, fetcher) {
         group,
         readOnly: true,
         execute: async (ctx, input) => {
-            const { mode, limit, offset } = extractPaginationInput(input);
-            return handlePaginationMode(mode, (off, lim) => fetcher(ctx.client, off, lim), limit, offset, 100);
+            const { limit, offset } = extractPaginationInput(input);
+            return handlePagination((off, lim) => fetcher(ctx.client, off, lim), limit, offset, 20);
         },
     };
 }
@@ -197,13 +195,13 @@ export const TOOL_DEFINITIONS = [
         group: 'accounts',
         readOnly: true,
         execute: async (ctx, input) => {
-            const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
             const query = input.query;
-            return handlePaginationMode(mode, (off, lim) => searchAccounts(ctx.client, {
+            return handlePagination((off, lim) => searchAccounts(ctx.client, {
                 filter: { or: { name: { contains: query }, code: { contains: query } } },
                 limit: lim, offset: off,
                 sort: { sortBy: [sortBy ?? 'code'], order: (sortOrder ?? 'ASC') },
-            }), limit, offset, 100);
+            }), limit, offset, 20);
         },
     },
     {
@@ -263,22 +261,25 @@ export const TOOL_DEFINITIONS = [
     listTool('list_contacts', 'List contacts (customers/suppliers). Returns billingName, name, emails, status. Paginated — response includes totalElements. Use limit/offset to page.', 'contacts', (client, off, lim) => listContacts(client, { limit: lim, offset: off })),
     {
         name: 'search_contacts',
-        description: 'Search contacts by name. Searches both billingName and name fields. Returns up to 100 by default. Use limit/offset to page through large result sets.',
+        description: 'Search contacts with filters. Searches both billingName and name fields when query is provided.',
         params: {
-            query: { type: 'string', description: 'Search term' },
+            query: { type: 'string', description: 'Search by name or billing name' },
+            isCustomer: { type: 'boolean', description: 'Filter to customers only' },
+            isSupplier: { type: 'boolean', description: 'Filter to suppliers only' },
+            status: { type: 'string', enum: ['ACTIVE', 'INACTIVE'], description: 'Filter by status' },
+            email: { type: 'string', description: 'Filter by email (contains)' },
             ...SEARCH_PARAMS,
         },
-        required: ['query'],
+        required: [],
         group: 'contacts',
         readOnly: true,
         execute: async (ctx, input) => {
-            const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
-            const query = input.query;
-            return handlePaginationMode(mode, (off, lim) => searchContacts(ctx.client, {
-                filter: { or: { billingName: { contains: query }, name: { contains: query } } },
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
+            return handlePagination((off, lim) => searchContacts(ctx.client, {
+                filter: buildContactFilter(input),
                 limit: lim, offset: off,
                 sort: { sortBy: [sortBy ?? 'billingName'], order: (sortOrder ?? 'ASC') },
-            }), limit, offset, 100);
+            }), limit, offset, 20);
         },
     },
     {
@@ -334,42 +335,32 @@ 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, contact name, and/or date range. Provide any combination of filters.',
+        description: 'Search invoices with filters. Provide any combination: reference, contact, status, date range, due date range, amount range, tag, currency.',
         params: {
             query: { type: 'string', description: 'Search by invoice reference number' },
             contactName: { type: 'string', description: 'Search by contact name' },
+            status: { type: 'string', enum: ['DRAFT', 'UNPAID', 'PARTIALLY_PAID', 'PAID', 'OVERDUE', 'VOID'], description: 'Filter by status' },
+            tag: { type: 'string', description: 'Filter by tag 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)' },
+            dueDateFrom: { type: 'string', description: 'Filter by due date from (YYYY-MM-DD)' },
+            dueDateTo: { type: 'string', description: 'Filter by due date to (YYYY-MM-DD)' },
+            minAmount: { type: 'number', description: 'Minimum total amount' },
+            maxAmount: { type: 'number', description: 'Maximum total amount' },
+            currencyCode: { type: 'string', description: 'Filter by currency code (e.g. USD, SGD)' },
             ...SEARCH_PARAMS,
         },
         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: Object.keys(filter).length > 0 ? filter : undefined,
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
+            const filterInput = { ...input, reference: input.reference ?? input.query };
+            return handlePagination((off, lim) => searchInvoices(ctx.client, {
+                filter: buildInvoiceBillFilter(filterInput),
                 limit: lim, offset: off,
                 sort: { sortBy: [sortBy ?? 'valueDate'], order: (sortOrder ?? 'DESC') },
-            }), limit, offset, 100);
+            }), limit, offset, 20);
         },
     },
     {
@@ -493,6 +484,11 @@ export const TOOL_DEFINITIONS = [
         readOnly: false,
         execute: async (ctx, input) => {
             const { resourceId: rid, ...data } = input;
+            // API requires lineItems on PUT even for status-only changes — fetch if not provided
+            if (!data.lineItems) {
+                const current = await getInvoice(ctx.client, rid);
+                data.lineItems = current.lineItems;
+            }
             return finalizeInvoice(ctx.client, rid, data);
         },
     },
@@ -534,41 +530,32 @@ 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, contact name, and/or date range. Provide any combination of filters.',
+        description: 'Search bills with filters. Provide any combination: reference, contact, status, date range, due date range, amount range, tag, currency.',
         params: {
             query: { type: 'string', description: 'Search by bill reference number' },
             contactName: { type: 'string', description: 'Search by contact name' },
+            status: { type: 'string', enum: ['DRAFT', 'UNPAID', 'PARTIALLY_PAID', 'PAID', 'OVERDUE', 'VOID'], description: 'Filter by status' },
+            tag: { type: 'string', description: 'Filter by tag 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)' },
+            dueDateFrom: { type: 'string', description: 'Filter by due date from (YYYY-MM-DD)' },
+            dueDateTo: { type: 'string', description: 'Filter by due date to (YYYY-MM-DD)' },
+            minAmount: { type: 'number', description: 'Minimum total amount' },
+            maxAmount: { type: 'number', description: 'Maximum total amount' },
+            currencyCode: { type: 'string', description: 'Filter by currency code (e.g. USD, SGD)' },
             ...SEARCH_PARAMS,
         },
         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: Object.keys(filter).length > 0 ? filter : undefined,
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
+            const filterInput = { ...input, reference: input.reference ?? input.query };
+            return handlePagination((off, lim) => searchBills(ctx.client, {
+                filter: buildInvoiceBillFilter(filterInput),
                 limit: lim, offset: off,
                 sort: { sortBy: [sortBy ?? 'valueDate'], order: (sortOrder ?? 'DESC') },
-            }), limit, offset, 100);
+            }), limit, offset, 20);
         },
     },
     {
@@ -644,7 +631,7 @@ export const TOOL_DEFINITIONS = [
     },
     {
         name: 'pay_bill',
-        description: 'Record a payment against a bill.',
+        description: 'Record a payment against a bill. Bill must be APPROVED before payment — draft or voided bills cannot be paid.',
         params: {
             resourceId: { type: 'string' },
             paymentAmount: { type: 'number' },
@@ -695,6 +682,11 @@ export const TOOL_DEFINITIONS = [
         readOnly: false,
         execute: async (ctx, input) => {
             const { resourceId: rid, ...data } = input;
+            // API requires lineItems on PUT even for status-only changes — fetch if not provided
+            if (!data.lineItems) {
+                const current = await getBill(ctx.client, rid);
+                data.lineItems = current.lineItems;
+            }
             return finalizeBill(ctx.client, rid, data);
         },
     },
@@ -725,22 +717,27 @@ export const TOOL_DEFINITIONS = [
     listTool('list_journals', 'List journal entries. Paginated — response includes totalElements. Use limit/offset to page.', 'journals', (client, off, lim) => listJournals(client, { limit: lim, offset: off })),
     {
         name: 'search_journals',
-        description: 'Search journals by reference. Returns up to 100 by default. Use limit/offset to page through large result sets.',
-        params: {
-            query: { type: 'string' },
+        description: 'Search journals with filters. Provide any combination: reference, status, tag, type, date range.',
+        params: {
+            query: { type: 'string', description: 'Search by reference (contains)' },
+            status: { type: 'string', enum: ['DRAFT', 'FINALIZED', 'VOID'], description: 'Filter by status' },
+            tag: { type: 'string', description: 'Filter by tag name' },
+            type: { type: 'string', description: 'Filter by type (e.g. JOURNAL_MANUAL, JOURNAL_DIRECT_CASH_IN, JOURNAL_DIRECT_CASH_OUT)' },
+            startDate: { type: 'string', description: 'Filter journals on or after this date (YYYY-MM-DD)' },
+            endDate: { type: 'string', description: 'Filter journals on or before this date (YYYY-MM-DD)' },
             ...SEARCH_PARAMS,
         },
-        required: ['query'],
+        required: [],
         group: 'journals',
         readOnly: true,
         execute: async (ctx, input) => {
-            const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
-            const query = input.query;
-            return handlePaginationMode(mode, (off, lim) => searchJournals(ctx.client, {
-                filter: { reference: { contains: query } },
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
+            const filterInput = { ...input, reference: input.reference ?? input.query };
+            return handlePagination((off, lim) => searchJournals(ctx.client, {
+                filter: buildJournalFilter(filterInput),
                 limit: lim, offset: off,
                 sort: { sortBy: [sortBy ?? 'valueDate'], order: (sortOrder ?? 'DESC') },
-            }), limit, offset, 100);
+            }), limit, offset, 20);
         },
     },
     {
@@ -802,13 +799,16 @@ export const TOOL_DEFINITIONS = [
         name: 'generate_balance_sheet',
         description: 'Generate a balance sheet report.',
         params: {
-            snapshotDate: { type: 'string', description: 'Snapshot date (YYYY-MM-DD)' },
+            snapshotDate: { type: 'string', description: 'Snapshot date (YYYY-MM-DD). Defaults to today if omitted.' },
             currencyCode: { type: 'string' },
         },
-        required: ['snapshotDate'],
+        required: [],
         group: 'reports',
         readOnly: true,
-        execute: async (ctx, input) => generateBalanceSheet(ctx.client, input),
+        execute: async (ctx, input) => {
+            const date = input.snapshotDate ?? new Date().toISOString().slice(0, 10);
+            return generateBalanceSheet(ctx.client, { primarySnapshotDate: date, currencyCode: input.currencyCode });
+        },
     },
     {
         name: 'generate_profit_and_loss',
@@ -913,7 +913,7 @@ export const TOOL_DEFINITIONS = [
         group: 'items',
         readOnly: true,
         execute: async (ctx, input) => {
-            const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
             const filter = {};
             if (input.appliesToSale !== undefined)
                 filter.appliesToSale = { eq: input.appliesToSale };
@@ -923,11 +923,11 @@ export const TOOL_DEFINITIONS = [
                 filter.status = { eq: input.status };
             if (input.itemCategory)
                 filter.itemCategory = { eq: input.itemCategory };
-            return handlePaginationMode(mode, (off, lim) => searchItems(ctx.client, {
+            return handlePagination((off, lim) => searchItems(ctx.client, {
                 filter: Object.keys(filter).length > 0 ? filter : undefined,
                 limit: lim, offset: off,
                 sort: { sortBy: [sortBy ?? 'internalName'], order: (sortOrder ?? 'ASC') },
-            }), limit, offset, 100);
+            }), limit, offset, 20);
         },
     },
     {
@@ -1006,13 +1006,13 @@ export const TOOL_DEFINITIONS = [
         group: 'tags',
         readOnly: true,
         execute: async (ctx, input) => {
-            const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
             const query = input.query;
-            return handlePaginationMode(mode, (off, lim) => searchTags(ctx.client, {
+            return handlePagination((off, lim) => searchTags(ctx.client, {
                 filter: { tagName: { contains: query } },
                 limit: lim, offset: off,
                 sort: { sortBy: [sortBy ?? 'tagName'], order: (sortOrder ?? 'ASC') },
-            }), limit, offset, 100);
+            }), limit, offset, 20);
         },
     },
     {
@@ -1059,13 +1059,13 @@ export const TOOL_DEFINITIONS = [
         group: 'capsules',
         readOnly: true,
         execute: async (ctx, input) => {
-            const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
             const query = input.query;
-            return handlePaginationMode(mode, (off, lim) => searchCapsules(ctx.client, {
+            return handlePagination((off, lim) => searchCapsules(ctx.client, {
                 filter: { title: { contains: query } },
                 limit: lim, offset: off,
                 sort: { sortBy: [sortBy ?? 'title'], order: (sortOrder ?? 'ASC') },
-            }), limit, offset, 100);
+            }), limit, offset, 20);
         },
     },
     {
@@ -1138,12 +1138,12 @@ export const TOOL_DEFINITIONS = [
         group: 'customer_credit_notes',
         readOnly: true,
         execute: async (ctx, input) => {
-            const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
-            return handlePaginationMode(mode, (off, lim) => searchCustomerCreditNotes(ctx.client, {
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
+            return handlePagination((off, lim) => searchCustomerCreditNotes(ctx.client, {
                 filter: buildCnFilter(input),
                 limit: lim, offset: off,
                 sort: { sortBy: [sortBy ?? 'valueDate'], order: (sortOrder ?? 'DESC') },
-            }), limit, offset, 100);
+            }), limit, offset, 20);
         },
     },
     {
@@ -1307,12 +1307,12 @@ export const TOOL_DEFINITIONS = [
         group: 'supplier_credit_notes',
         readOnly: true,
         execute: async (ctx, input) => {
-            const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
-            return handlePaginationMode(mode, (off, lim) => searchSupplierCreditNotes(ctx.client, {
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
+            return handlePagination((off, lim) => searchSupplierCreditNotes(ctx.client, {
                 filter: buildCnFilter(input),
                 limit: lim, offset: off,
                 sort: { sortBy: [sortBy ?? 'valueDate'], order: (sortOrder ?? 'DESC') },
-            }), limit, offset, 100);
+            }), limit, offset, 20);
         },
     },
     {
@@ -1493,9 +1493,9 @@ export const TOOL_DEFINITIONS = [
         group: 'currencies',
         readOnly: true,
         execute: async (ctx, input) => {
-            const { mode, limit, offset } = extractPaginationInput(input);
+            const { limit, offset } = extractPaginationInput(input);
             const cc = input.currencyCode;
-            return handlePaginationMode(mode, (off, lim) => listCurrencyRates(ctx.client, cc, { limit: lim, offset: off }), limit, offset, 100);
+            return handlePagination((off, lim) => listCurrencyRates(ctx.client, cc, { limit: lim, offset: off }), limit, offset, 100);
         },
     },
     {
@@ -1815,12 +1815,12 @@ export const TOOL_DEFINITIONS = [
         group: 'bank',
         readOnly: true,
         execute: async (ctx, input) => {
-            const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
-            return handlePaginationMode(mode, (off, lim) => searchBankRecords(ctx.client, input.accountResourceId, {
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
+            return handlePagination((off, lim) => searchBankRecords(ctx.client, input.accountResourceId, {
                 filter: buildBankRecordFilter(input),
                 limit: lim, offset: off,
                 sort: { sortBy: [sortBy ?? 'valueDate'], order: (sortOrder ?? 'DESC') },
-            }), limit, offset, 100);
+            }), limit, offset, 20);
         },
     },
     // ── Cashflow Transactions ──────────────────────────────────────
@@ -1828,25 +1828,24 @@ export const TOOL_DEFINITIONS = [
         name: 'search_cashflow_transactions',
         description: 'Search cashflow transactions (unified ledger: invoices, bills, credit notes, journals, payments). Useful for reconciliation.',
         params: {
-            ...SEARCH_PARAMS,
             businessTransactionType: { type: 'string', description: 'Filter by type (e.g., INVOICE, BILL, JOURNAL)' },
             direction: { type: 'string', enum: ['IN', 'OUT'], description: 'Filter by direction' },
+            startDate: { type: 'string', description: 'Filter from date (YYYY-MM-DD)' },
+            endDate: { type: 'string', description: 'Filter to date (YYYY-MM-DD)' },
+            status: { type: 'string', description: 'Filter by transaction status' },
+            reference: { type: 'string', description: 'Filter by reference (contains)' },
+            ...SEARCH_PARAMS,
         },
         required: [],
         group: 'cashflow',
         readOnly: true,
         execute: async (ctx, input) => {
-            const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
-            const filter = {};
-            if (input.businessTransactionType)
-                filter.businessTransactionType = { eq: input.businessTransactionType };
-            if (input.direction)
-                filter.direction = { eq: input.direction };
-            return handlePaginationMode(mode, (off, lim) => searchCashflowTransactions(ctx.client, {
-                filter: Object.keys(filter).length > 0 ? filter : undefined,
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
+            return handlePagination((off, lim) => searchCashflowTransactions(ctx.client, {
+                filter: buildCashflowFilter(input),
                 limit: lim, offset: off,
                 sort: { sortBy: [sortBy ?? 'valueDate'], order: (sortOrder ?? 'DESC') },
-            }), limit, offset, 100);
+            }), limit, offset, 20);
         },
     },
     // ── Bookmarks ──────────────────────────────────────────────────
@@ -1916,13 +1915,13 @@ export const TOOL_DEFINITIONS = [
         group: 'org_users',
         readOnly: true,
         execute: async (ctx, input) => {
-            const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
             const query = input.query;
-            return handlePaginationMode(mode, (off, lim) => searchOrgUsers(ctx.client, {
+            return handlePagination((off, lim) => searchOrgUsers(ctx.client, {
                 filter: { or: { firstName: { contains: query }, lastName: { contains: query }, email: { contains: query } } },
                 limit: lim, offset: off,
                 sort: { sortBy: [sortBy ?? 'firstName'], order: (sortOrder ?? 'ASC') },
-            }), limit, offset, 100);
+            }), limit, offset, 20);
         },
     },
     {
@@ -2017,7 +2016,7 @@ export const TOOL_DEFINITIONS = [
         group: 'payments',
         readOnly: true,
         execute: async (ctx, input) => {
-            const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
             const filter = {};
             if (input.businessTransactionType)
                 filter.businessTransactionType = { eq: input.businessTransactionType };
@@ -2035,11 +2034,11 @@ export const TOOL_DEFINITIONS = [
                     df.lte = input.toDate;
                 filter.valueDate = df;
             }
-            return handlePaginationMode(mode, (off, lim) => searchPayments(ctx.client, {
+            return handlePagination((off, lim) => searchPayments(ctx.client, {
                 filter: Object.keys(filter).length > 0 ? filter : undefined,
                 limit: lim, offset: off,
                 sort: { sortBy: [sortBy ?? 'valueDate'], order: (sortOrder ?? 'DESC') },
-            }), limit, offset, 100);
+            }), limit, offset, 20);
         },
     },
     // ── Data Exports ───────────────────────────────────────────────
@@ -2482,17 +2481,17 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
         group: 'magic',
         readOnly: true,
         execute: async (ctx, input) => {
-            const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
             const filter = {};
             if (input.status)
                 filter.status = input.status;
             if (input.documentType)
                 filter.documentType = input.documentType;
-            return handlePaginationMode(mode, (off, lim) => searchMagicWorkflows(ctx.client, {
+            return handlePagination((off, lim) => searchMagicWorkflows(ctx.client, {
                 filter: Object.keys(filter).length > 0 ? filter : undefined,
                 limit: lim, offset: off,
                 sort: { sortBy: [sortBy ?? 'createdAt'], order: (sortOrder ?? 'DESC') },
-            }), limit, offset, 100);
+            }), limit, offset, 20);
         },
     },
     {
@@ -2878,13 +2877,13 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
         group: 'bank_rules',
         readOnly: true,
         execute: async (ctx, input) => {
-            const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
             const query = input.query;
-            return handlePaginationMode(mode, (off, lim) => searchBankRules(ctx.client, {
+            return handlePagination((off, lim) => searchBankRules(ctx.client, {
                 filter: { name: { contains: query } },
                 limit: lim, offset: off,
-                sort: sortBy ? { sortBy: [sortBy], order: (sortOrder ?? 'ASC') } : undefined,
-            }), limit, offset, 100);
+                sort: { sortBy: [sortBy ?? 'name'], order: (sortOrder ?? 'ASC') },
+            }), limit, offset, 20);
         },
     },
     {
@@ -2981,13 +2980,14 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
             query: { type: 'string', description: 'Search term (name or reference)' },
             status: { type: 'string', enum: ['ONGOING', 'COMPLETED', 'DISPOSED', 'DRAFT'], description: 'Filter by status' },
             category: { type: 'string', enum: ['TANGIBLE', 'INTANGIBLE'], description: 'Filter by category' },
+            tag: { type: 'string', description: 'Filter by tag name' },
             ...SEARCH_PARAMS,
         },
         required: [],
         group: 'fixed_assets',
         readOnly: true,
         execute: async (ctx, input) => {
-            const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
             const filter = {};
             if (input.query)
                 filter.name = { contains: input.query };
@@ -2995,11 +2995,13 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
                 filter.status = { eq: input.status };
             if (input.category)
                 filter.category = { eq: input.category };
-            return handlePaginationMode(mode, (off, lim) => searchFixedAssets(ctx.client, {
+            if (input.tag)
+                filter.tags = { name: { eq: input.tag } };
+            return handlePagination((off, lim) => searchFixedAssets(ctx.client, {
                 filter: Object.keys(filter).length > 0 ? filter : undefined,
                 limit: lim, offset: off,
-                sort: sortBy ? { sortBy: [sortBy], order: (sortOrder ?? 'DESC') } : undefined,
-            }), limit, offset, 100);
+                sort: { sortBy: [sortBy ?? 'name'], order: (sortOrder ?? 'DESC') },
+            }), limit, offset, 20);
         },
     },
     {
@@ -3172,17 +3174,17 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
         group: 'subscriptions',
         readOnly: true,
         execute: async (ctx, input) => {
-            const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
             const filter = {};
             if (input.businessTransactionType)
                 filter.businessTransactionType = { eq: input.businessTransactionType };
             if (input.status)
                 filter.status = { eq: input.status };
-            return handlePaginationMode(mode, (off, lim) => searchScheduledTransactions(ctx.client, {
+            return handlePagination((off, lim) => searchScheduledTransactions(ctx.client, {
                 filter: Object.keys(filter).length > 0 ? filter : undefined,
                 limit: lim, offset: off,
-                sort: sortBy ? { sortBy: [sortBy], order: (sortOrder ?? 'DESC') } : undefined,
-            }), limit, offset, 100);
+                sort: { sortBy: [sortBy ?? 'valueDate'], order: (sortOrder ?? 'DESC') },
+            }), limit, offset, 20);
         },
     },
     // ══════════════════════════════════════════════════════════════
@@ -3318,13 +3320,13 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
         group: 'contact_groups',
         readOnly: true,
         execute: async (ctx, input) => {
-            const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
             const query = input.query;
-            return handlePaginationMode(mode, (off, lim) => searchContactGroups(ctx.client, {
+            return handlePagination((off, lim) => searchContactGroups(ctx.client, {
                 filter: { name: { contains: query } },
                 limit: lim, offset: off,
-                sort: sortBy ? { sortBy: [sortBy], order: (sortOrder ?? 'ASC') } : undefined,
-            }), limit, offset, 100);
+                sort: { sortBy: [sortBy ?? 'name'], order: (sortOrder ?? 'ASC') },
+            }), limit, offset, 20);
         },
     },
     {
@@ -3369,17 +3371,19 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
         group: 'custom_fields',
         readOnly: true,
         execute: async (ctx, input) => {
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
             const filter = {};
             if (input.customFieldName)
                 filter.customFieldName = { contains: input.customFieldName };
             if (input.datatypeCode)
                 filter.datatypeCode = { eq: input.datatypeCode };
             const searchFilter = Object.keys(filter).length > 0 ? filter : undefined;
-            return searchCustomFields(ctx.client, {
+            return handlePagination((off, lim) => searchCustomFields(ctx.client, {
                 filter: searchFilter,
-                limit: Number(input.limit) || 20,
-                offset: Number(input.offset) || 0,
-            });
+                limit: lim,
+                offset: off,
+                sort: { sortBy: [sortBy ?? 'customFieldName'], order: (sortOrder ?? 'ASC') },
+            }), limit, offset, 20);
         },
     },
     {
@@ -3443,18 +3447,19 @@ Auto-resolves accounts from chart of accounts. Provide bankAccountName for recip
         params: {
             query: { type: 'string', description: 'Search term (profile name or tax type code)' },
             ...SEARCH_PARAMS,
+            sortBy: { type: 'string', enum: ['name', 'taxTypeCode', 'status', 'vatValue'], description: 'Sort field for tax profiles' },
         },
         required: ['query'],
         group: 'tax_profiles',
         readOnly: true,
         execute: async (ctx, input) => {
-            const { mode, limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
+            const { limit, offset, sortBy, sortOrder } = extractPaginationInput(input);
             const query = input.query;
-            return handlePaginationMode(mode, (off, lim) => searchTaxProfiles(ctx.client, {
+            return handlePagination((off, lim) => searchTaxProfiles(ctx.client, {
                 filter: { or: { name: { contains: query }, taxTypeCode: { contains: query } } },
                 limit: lim, offset: off,
-                sort: sortBy ? { sortBy: [sortBy], order: (sortOrder ?? 'ASC') } : undefined,
-            }), limit, offset, 100);
+                sort: { sortBy: [sortBy ?? 'name'], order: (sortOrder ?? 'ASC') },
+            }), limit, offset, 20);
         },
     },
     getTool('get_tax_profile', 'Get full tax profile details including tax rate, type code, and status.', 'tax_profiles', (client, id) => getTaxProfile(client, id)),

package/package.json

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