jaz-clio 4.20.1 → 4.22.0

package/README.md

@@ -128,7 +128,7 @@ Every command supports `--json` for structured output — ideal for piping to ot
 
 ## MCP Server
 
-Expose all 145 CLI tools to AI coding assistants via the [Model Context Protocol](https://modelcontextprotocol.io). The server runs locally on your machine — no cloud, no ports. API calls go directly from your machine to the Jaz API.
+Expose all 200 CLI tools to AI coding assistants via the [Model Context Protocol](https://modelcontextprotocol.io). The server runs locally on your machine — no cloud, no ports. API calls go directly from your machine to the Jaz API.
 
 **Claude Code:**
 
@@ -167,6 +167,18 @@ clio init --platform claude            # Force a specific platform
 
 See the [full README](https://github.com/teamtinvio/jaz-ai) for skill details, reference file catalogs, and plugin installation.
 
+## Privacy & Security
+
+Jaz AI runs entirely on your machine. API calls go directly from your machine to the Jaz API over HTTPS. This tool does not include telemetry or collect data. Your API key is stored locally in `~/.config/jaz-clio/credentials.json`.
+
+See our full privacy policy: [jaz.ai/legal](https://jaz.ai/legal)
+
+## Support
+
+- Help center: [help.jaz.ai](https://help.jaz.ai)
+- GitHub Issues: [github.com/teamtinvio/jaz-ai/issues](https://github.com/teamtinvio/jaz-ai/issues)
+- Email: api-support@jaz.ai
+
 ## License
 
 [MIT](https://github.com/teamtinvio/jaz-ai/blob/main/LICENSE) - Copyright (c) 2026 Tinvio / Jaz

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 4.20.1
+version: 4.22.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.
@@ -77,8 +77,8 @@ You are working with the **Jaz REST API** — the accounting platform backend. A
 31. **Cash transfers use `cashOut`/`cashIn` sub-objects** — NOT flat `fromAccountResourceId`/`toAccountResourceId`. Each: `{ accountResourceId, amount }`.
 
 ### Schedulers
-32. **Scheduled invoices/bills wrap in `{ invoice: {...} }` or `{ bill: {...} }`** — not flat. Recurrence field is `repeat` (NOT `frequency`/`interval`). `saveAsDraft: false` required.
-33. **Scheduled journals use FLAT structure** with `schedulerEntries` — not nested in `journal` wrapper.
+32. **Scheduled invoices/bills wrap in `{ invoice: {...} }` or `{ bill: {...} }`** — not flat. Recurrence field is `repeat` (NOT `frequency`/`interval`). `saveAsDraft: false` required. **`reference` is required** inside the `invoice`/`bill` wrapper — omitting it causes 422.
+33. **Scheduled journals use FLAT structure** with `schedulerEntries` — not nested in `journal` wrapper. **`valueDate` is required** at the top level (alongside `startDate`, `repeat`, etc.).
 
 ### Bookmarks
 34. **Bookmarks use `items` array wrapper** with `name`, `value`, `categoryCode`, `datatypeCode`.
@@ -113,11 +113,11 @@ You are working with the **Jaz REST API** — the accounting platform backend. A
 41. **Invoice GET uses `organizationAccountResourceId`** for line item accounts — POST uses `accountResourceId`. Request-side aliases resolve `issueDate` → `valueDate`, `bankAccountResourceId` → `accountResourceId`, etc.
 42. **Scheduler GET returns `interval`** — POST uses `repeat`. (Response-side asymmetry remains.)
 43. **Search sort is an object** — `{ sort: { sortBy: ["valueDate"], order: "DESC" } }`. Required when `offset` is present (even `offset: 0`).
-44. **Bank records: two import methods** — Multipart CSV/OFX via `POST /magic/importBankStatementFromAttachment` (camelCase fields: `sourceFile`, `accountResourceId`, `businessTransactionType: "BANK_STATEMENT"`, `sourceType: "FILE"` — same camelCase rule as rule 59). JSON via `POST /bank-records/:accountResourceId` with `{ records: [{description, netAmount, valueDate, ...}] }`.
+44. **Bank records** — **Create**: Multipart CSV/OFX via `POST /magic/importBankStatementFromAttachment` or JSON via `POST /bank-records/:accountResourceId` with `{ records: [{amount, transactionDate, description?, payerOrPayee?, reference?}] }` (positive = cash-in, negative = cash-out, response: `{data: {errors: []}}`). **Search**: `POST /bank-records/:accountResourceId/search` — filter fields: `valueDate` (DateExpression), `status` (StringExpression: UNRECONCILED, RECONCILED, ARCHIVED, POSSIBLE_DUPLICATE), `description`, `extContactName` (payer/payee), `extReference`, `netAmount` (BigDecimalExpression), `extAccountNumber`. Sort by `valueDate` DESC default.
 45. **Withholding tax** on bills/supplier CNs only. Retry pattern: if `WITHHOLDING_CODE_NOT_FOUND`, strip field and retry.
-46. **Known API bugs (500s)**: Contact groups PUT, custom fields PUT, capsules POST, catalogs POST, inventory balances GET — all return 500.
+46. **Known API bugs (500s/404s)**: Contact groups PUT, custom fields PUT, capsules POST, catalogs POST, inventory balances by status GET (`/inventory-balances/:status`) — all return 500. Auto-reconciliation view (`POST /view-auto-reconciliation`) returns 404 (endpoint may not be deployed).
 47. **Non-existent endpoints**: `POST /deposits`, `POST /inventory/adjustments`, `GET /payments` (list), and `POST /payments/search` return 404 — these endpoints are not implemented. To list/search payments, use `POST /cashflow-transactions/search` (the unified transaction ledger — see Rule 63).
-48. **Attachments require PDF/PNG**: `POST /:type/:id/attachments` uses multipart `file` field but rejects `text/plain`. Use `application/pdf` or `image/png`.
+48. **Attachments require multipart `file` field**: `POST /:type/:id/attachments` expects a binary file in the `file` form-data field — NOT a `sourceUrl` text field. Rejects `text/plain`. Use `application/pdf` or `image/png`. CLI: `clio attachments add --file <path>` (local file) or `--url <url>` (downloads first, then uploads as `file`).
 49. **Currency rate direction: `rate` = functionalToSource (1 base = X foreign)** — POST `rate: 0.74` for a SGD org means 1 SGD = 0.74 USD. **If your data stores rates as "1 USD = 1.35 SGD" (sourceToFunctional), you MUST invert: `rate = 1 / 1.35 = 0.74`.** GET confirms both: `rateFunctionalToSource` (what you POSTed) and `rateSourceToFunctional` (the inverse).
 
 ### Search & Filter
@@ -222,6 +222,30 @@ Step 3:  For each draft where ready = true:
 
 Bills, invoices, and credit notes share identical mandatory field specs. Adding `clio invoices draft` or `clio customer-credit-notes draft` later reuses all validation, formatting, and CLI flag logic from `draft-helpers.ts` — only the API calls differ.
 
+### Bank Rules
+89. **Bank rules GET by ID has double-nested response** — `GET /bank-rules/:id` returns `{ data: { data: [...], totalElements, totalPages } }` (double `data` wrapper). Unlike standard `GET /:type/:id` which returns `{ data: {...} }`. The inner `data` is an array containing the single rule. Unwrap with `response.data.data[0]`.
+90. **Bank rules search uses `/bank-rules/search`** — Standard search pattern with filter/sort/limit/offset. Sort fields: standard (name, createdAt, etc.).
+
+### Fixed Assets
+91. **Fixed asset search does NOT support `createdAt` sort** — Valid sort fields: `resourceId`, `name`, `purchaseDate`, `typeName`, `purchaseAmount`, `bookValueNetBookValueAmount`, `depreciationMethod`, `status`. Using `createdAt` returns 422. Default to `purchaseDate` DESC.
+92. **Fixed asset disposal/sale/transfer use different endpoint patterns** — Discard: `POST /discard-fixed-assets/:id` (body includes `resourceId` + dates). Mark sold: `POST /mark-as-sold/fixed-assets` (body-only, no path param). Transfer: `POST /transfer-fixed-assets` (body-only). Undo: `POST /undo-disposal/fixed-assets/:id`.
+
+### Subscriptions & Scheduled Transactions
+93. **Subscription endpoints are under `/scheduled/subscriptions`** — List, GET, POST, PUT, DELETE all at `/api/v1/scheduled/subscriptions[/:id]`. Cancel is at `/api/v1/scheduled/cancel-subscriptions/:id` (different path pattern).
+94. **Scheduled transaction search does NOT support `createdAt` sort** — `POST /scheduled-transaction/search` sort fields: `startDate`, `nextScheduleDate`, etc. Default to `startDate` DESC. This is a cross-entity search across all scheduled types (invoices, bills, journals, subscriptions).
+
+### Universal Search
+95. **Universal search uses `query` param (NOT `q`)** — `GET /search?query=<term>` returns categorized results across contacts, invoices, bills, credit notes, journals. Response is a flat object with category keys, each containing an array of matches. No pagination — returns top matches per category.
+
+### Contact Groups
+96. **Contact groups have `associatedContacts` array** — Each group contains `{ name, resourceId, associatedContacts: [{ name, resourceId }] }`. Search via `POST /contact-groups/search`. Known bug: PUT returns 500 (Rule 46).
+
+### Inventory
+97. **Inventory balance uses `GET /inventory-item-balance/:itemResourceId`** — Returns `{ itemResourceId, latestAverageCostAmount, baseQty, baseUnit }`. Note: this is the ITEM resourceId, not an inventory-specific ID. The `/inventory-balances/:status` endpoint returns 500 (Rule 46).
+
+### Withholding Tax
+98. **Withholding tax codes via `GET /withholding-tax-codes`** — Returns a flat array of 1,360+ entries (PH PSIC codes). Each entry: `{ code, description, taxRate, ... }`. No pagination — full list in one call. Use for PH/SG tax compliance.
+
 ## Supporting Files
 
 For detailed reference, read these files in this skill directory:
@@ -269,6 +293,7 @@ The backend DX overhaul is live. Key improvements now available:
 - **Field names**: All request bodies use camelCase
 - **Date serialization**: Python `date` type → `YYYY-MM-DD` strings
 - **Bill payments**: Embed in bill creation body (safest). Standalone `POST /bills/{id}/payments` also works.
-- **Bank records**: Use multipart `POST /magic/importBankStatementFromAttachment`
-- **Scheduled bills**: Wrap as `{ status, startDate, endDate, repeat, bill: {...} }`
+- **Bank records**: Create via JSON `POST /bank-records/:id` or multipart `POST /magic/importBankStatementFromAttachment`. Search via `POST /bank-records/:id/search` with filters (valueDate, status, description, extContactName, netAmount, extReference).
+- **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.

package/assets/skills/api/references/errors.md

@@ -322,10 +322,14 @@ if (acct.code) ctx.coaIds[acct.code] = acct.resourceId;
 
 ## Bank Record Errors
 
-### No JSON POST endpoint exists
-There is no JSON POST endpoint for creating bank records. Use multipart import:
+### Bank record creation
 
-**Workaround**: Use multipart import instead:
+Two methods for creating bank records:
+
+**Method 1: JSON POST** (programmatic)
+`POST /api/v1/bank-records/:accountResourceId` with `{ records: [{amount, transactionDate, description?, payerOrPayee?, reference?}] }`. Returns `{ data: { errors: [] } }` on success. 1-100 records per call.
+
+**Method 2: Multipart import** (file upload)
 ```
 POST /api/v1/magic/importBankStatementFromAttachment
 Content-Type: multipart/form-data
@@ -337,12 +341,7 @@ Fields:
   - sourceType: "FILE" (valid values: URL, FILE)
 ```
 
-Production clients use this multipart endpoint exclusively. Multipart import is the more reliable method.
-
-**Legacy guidance** (still valid for general bank record handling):
-1. Always use `Math.abs()` on amounts — amounts must be positive
-2. Use `type: "CREDIT"` or `type: "DEBIT"` to indicate direction
-3. Check that `bankAccountResourceId` is a valid CoA entry with `accountType: "Bank Accounts"`
+**Amount rules**: For JSON POST, positive = cash-in, negative = cash-out. Dates in YYYY-MM-DD format. `accountResourceId` must be a bank-type CoA account.
 
 ---
 

package/assets/skills/api/references/field-map.md

@@ -326,12 +326,20 @@ DELETE → expects "A" (parentEntityResourceId, via /cashflow-journals/:id)
 
 | What You'd Guess | Actual API Field | Notes |
 |------------------|-------------------|-------|
-| `date` | `transactionDate` | ISO date string |
-| `direction` | `type` | `"CREDIT"` or `"DEBIT"` (uppercase) |
+| `date` (create) | `transactionDate` | ISO date string (YYYY-MM-DD) |
+| `date` (search response) | `valueDate` | Returned as ISO 8601 UTC |
+| `amount` (create) | `amount` | Positive = cash-in, negative = cash-out |
+| `amount` (search response) | `netAmount` | Same sign convention |
+| `payer` / `payee` (create) | `payerOrPayee` | Free text |
+| `payer` / `payee` (search) | `extContactName` | Search filter field |
+| `reference` (search) | `extReference` | Search filter field |
 | `memo` | `description` | Free text |
-| (negative amount) | `amount` (positive) + `type` | Always positive, direction via type |
+| `source` | `bankStatementEntrySource` | `FILE_IMPORT` or `API` (read-only) |
+| `status` | `status` | `UNRECONCILED`, `RECONCILED`, `ARCHIVED`, `POSSIBLE_DUPLICATE` |
 
-**Creating bank records**: Use multipart `POST /api/v1/magic/importBankStatementFromAttachment` — the only endpoint for creating bank records. No JSON POST endpoint exists.
+**Creating bank records**: Two methods. JSON POST via `POST /bank-records/:accountResourceId` with `{ records: [{amount, transactionDate, ...}] }` (1-100 records). Multipart via `POST /magic/importBankStatementFromAttachment` for CSV/OFX file uploads.
+
+**Searching bank records**: `POST /bank-records/:accountResourceId/search` with filter fields: `valueDate` (DateExpression), `status` (StringExpression), `description` (StringExpression), `extContactName` (StringExpression), `extReference` (StringExpression), `netAmount` (BigDecimalExpression), `extAccountNumber` (StringExpression). Sort by `valueDate` DESC default.
 
 ---
 
@@ -510,7 +518,7 @@ Battle-tested patterns from production Jaz API clients:
 | Alias generator | `alias_generator=to_camel` (snake_case to camelCase) |
 | Date type | Python `date` type serializes to `YYYY-MM-DD` strings |
 | Bill payments | Always embedded in bill creation body, never standalone |
-| Bank records | Multipart import via `importBankStatementFromAttachment` — the only endpoint |
+| Bank records | JSON POST `/bank-records/:id` or multipart `/magic/importBankStatementFromAttachment`. Search via `/bank-records/:id/search`. |
 | Scheduled bills | Wrapped as `{ repeat, startDate, endDate, bill: {...} }`. Field is `repeat` (NOT `frequency`/`interval`) |
 | FX currency | MUST use `currency` OBJECT on ALL transaction types (invoices, bills, credit notes, journals): `{ sourceCurrency: "USD" }` (auto platform rate) or `{ sourceCurrency: "USD", exchangeRate: 1.35 }` (custom). String `currencyCode` silently ignored. |
 

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 4.20.1
+version: 4.22.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.20.1
+version: 4.22.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.20.1
+version: 4.22.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/attachments.js

@@ -1,7 +1,21 @@
 import chalk from 'chalk';
+import { readFileSync } from 'node:fs';
+import { basename, extname, resolve } from 'node:path';
 import { listAttachments, addAttachment, fetchAttachmentTable } from '../core/api/attachments.js';
 import { apiAction } from './api-action.js';
 const BT_TYPES = ['invoices', 'bills', 'journals', 'scheduled_journals', 'customer-credit-notes', 'supplier-credit-notes'];
+const ATTACHMENT_MIME_MAP = {
+    '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.csv': 'text/csv',
+    '.xls': 'application/vnd.ms-excel',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+};
 export function registerAttachmentsCommand(program) {
     const attachments = program
         .command('attachments')
@@ -35,11 +49,12 @@ export function registerAttachmentsCommand(program) {
     // ── clio attachments add ───────────────────────────────────────
     attachments
         .command('add')
-        .description('Add an attachment to a transaction')
+        .description('Add an attachment to a transaction (file upload or URL download)')
         .requiredOption('--type <type>', `Transaction type (${BT_TYPES.join(', ')})`)
         .requiredOption('--id <resourceId>', 'Transaction resourceId')
-        .option('--attachment-id <id>', 'Attachment ID')
-        .option('--url <url>', 'Source file URL')
+        .option('--file <path>', 'Local file path (PDF, PNG, JPG, etc.)')
+        .option('--url <url>', 'Download file from URL and attach')
+        .option('--attachment-id <id>', 'Link existing attachment by ID')
         .option('--api-key <key>', 'API key')
         .option('--json', 'Output as JSON')
         .action(apiAction(async (client, opts) => {
@@ -48,15 +63,41 @@ export function registerAttachmentsCommand(program) {
             console.error(chalk.red(`Invalid type. Use one of: ${BT_TYPES.join(', ')}`));
             process.exit(1);
         }
-        if (!opts.attachmentId && !opts.url) {
-            console.error(chalk.red('Provide --attachment-id or --url'));
+        if (!opts.attachmentId && !opts.url && !opts.file) {
+            console.error(chalk.red('Provide --file, --url, or --attachment-id'));
             process.exit(1);
         }
+        let file;
+        let fileName;
+        if (opts.file) {
+            // Local file upload
+            const filePath = resolve(opts.file);
+            const ext = extname(filePath).toLowerCase();
+            const mime = ATTACHMENT_MIME_MAP[ext] ?? 'application/octet-stream';
+            const buffer = readFileSync(filePath);
+            file = new Blob([buffer], { type: mime });
+            fileName = basename(filePath);
+        }
+        else if (opts.url) {
+            // Download from URL, then upload as file
+            const res = await fetch(opts.url);
+            if (!res.ok) {
+                console.error(chalk.red(`Failed to download: ${res.status} ${res.statusText}`));
+                process.exit(1);
+            }
+            const buffer = await res.arrayBuffer();
+            const contentType = res.headers.get('content-type') ?? 'application/octet-stream';
+            file = new Blob([buffer], { type: contentType });
+            // Extract filename from URL path
+            const urlPath = new URL(opts.url).pathname;
+            fileName = basename(urlPath) || 'attachment';
+        }
         const result = await addAttachment(client, {
             businessTransactionType: btType,
             businessTransactionResourceId: opts.id,
+            file,
+            fileName,
             attachmentId: opts.attachmentId,
-            sourceUrl: opts.url,
         });
         if (opts.json) {
             console.log(JSON.stringify(result, null, 2));

package/dist/commands/bank-rules.js

@@ -0,0 +1,101 @@
+import chalk from 'chalk';
+import { listBankRules, getBankRule, searchBankRules, createBankRule, deleteBankRule, } from '../core/api/bank-rules.js';
+import { apiAction } from './api-action.js';
+import { parsePositiveInt, parseNonNegativeInt, readBodyInput } from './parsers.js';
+import { paginatedFetch, paginatedJson, displaySlice } from './pagination.js';
+export function registerBankRulesCommand(program) {
+    const cmd = program
+        .command('bank-rules')
+        .description('Manage bank reconciliation rules');
+    cmd
+        .command('list')
+        .description('List bank rules')
+        .option('--limit <n>', 'Max results', parsePositiveInt)
+        .option('--offset <n>', 'Offset', parseNonNegativeInt)
+        .option('--all', 'Fetch all pages')
+        .option('--api-key <key>', 'API key')
+        .option('--json', 'JSON output')
+        .action(apiAction(async (client, opts) => {
+        const result = await paginatedFetch(opts, (p) => listBankRules(client, p), { label: 'Fetching bank rules' });
+        if (opts.json) {
+            console.log(paginatedJson(result, opts));
+            return;
+        }
+        console.log(chalk.bold(`Bank Rules (${result.data.length} of ${result.totalElements}):\n`));
+        const { items, overflow } = displaySlice(result.data);
+        for (const r of items)
+            console.log(`  ${chalk.cyan(r.resourceId)}  ${r.name}  ${chalk.dim(r.actionType)}`);
+        if (overflow > 0)
+            console.log(chalk.dim(`  ... and ${overflow} more`));
+    }));
+    cmd
+        .command('get <resourceId>')
+        .description('Get a bank rule')
+        .option('--api-key <key>', 'API key')
+        .option('--json', 'JSON output')
+        .action((resourceId, opts) => apiAction(async (client) => {
+        const res = await getBankRule(client, resourceId);
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
+            return;
+        }
+        console.log(chalk.bold('Name:'), res.data.name);
+        console.log(chalk.bold('Action:'), res.data.actionType);
+        console.log(chalk.bold('ID:'), res.data.resourceId);
+    })(opts));
+    cmd
+        .command('search <query>')
+        .description('Search bank rules')
+        .option('--limit <n>', 'Max results', parsePositiveInt)
+        .option('--offset <n>', 'Offset', parseNonNegativeInt)
+        .option('--api-key <key>', 'API key')
+        .option('--json', 'JSON output')
+        .action((query, opts) => apiAction(async (client) => {
+        const result = await paginatedFetch(opts, ({ limit, offset }) => searchBankRules(client, { filter: { name: { contains: query } }, limit, offset }), { label: 'Searching bank rules', defaultLimit: 20 });
+        if (opts.json) {
+            console.log(paginatedJson(result, opts));
+            return;
+        }
+        if (result.data.length === 0) {
+            console.log('No bank rules found.');
+            return;
+        }
+        console.log(chalk.bold(`Found ${result.data.length} rule(s):\n`));
+        for (const r of result.data)
+            console.log(`  ${chalk.cyan(r.resourceId)}  ${r.name}`);
+    })(opts));
+    cmd
+        .command('create')
+        .description('Create a bank rule')
+        .option('--input <file>', 'Read request body from JSON file')
+        .option('--api-key <key>', 'API key')
+        .option('--json', 'JSON output')
+        .action(apiAction(async (client, opts) => {
+        const body = readBodyInput(opts);
+        if (!body) {
+            console.error(chalk.red('Use --input <file> to provide rule configuration.'));
+            process.exit(1);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const res = await createBankRule(client, body);
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
+            return;
+        }
+        console.log(chalk.green('Bank rule created.'));
+        console.log(chalk.bold('ID:'), res.data.resourceId);
+    }));
+    cmd
+        .command('delete <resourceId>')
+        .description('Delete a bank rule')
+        .option('--api-key <key>', 'API key')
+        .option('--json', 'JSON output')
+        .action((resourceId, opts) => apiAction(async (client) => {
+        await deleteBankRule(client, resourceId);
+        if (opts.json) {
+            console.log(JSON.stringify({ deleted: true, resourceId }));
+            return;
+        }
+        console.log(chalk.green(`Bank rule ${resourceId} deleted.`));
+    })(opts));
+}

package/dist/commands/bank.js

@@ -1,7 +1,8 @@
 import chalk from 'chalk';
 import { readFileSync } from 'node:fs';
 import { basename, extname, resolve } from 'node:path';
-import { listBankAccounts, getBankAccount, searchBankRecords, importBankStatement, } from '../core/api/bank.js';
+import { listBankAccounts, getBankAccount, searchBankRecords, addBankRecords, importBankStatement, } from '../core/api/bank.js';
+import { buildBankRecordFilter } from '../core/registry/pagination.js';
 import { apiAction } from './api-action.js';
 import { parsePositiveInt } from './parsers.js';
 const BANK_MIME_MAP = {
@@ -61,27 +62,31 @@ export function registerBankCommand(program) {
         .description('Search bank records for a bank account')
         .option('--from <YYYY-MM-DD>', 'Filter from date (inclusive)')
         .option('--to <YYYY-MM-DD>', 'Filter to date (inclusive)')
-        .option('--status <status>', 'Filter by status (UNRECONCILED, RECONCILED)')
+        .option('--status <status>', 'Filter by status (UNRECONCILED, RECONCILED, ARCHIVED, POSSIBLE_DUPLICATE)')
+        .option('--description <text>', 'Filter by description (contains)')
+        .option('--payer <name>', 'Filter by payer/payee name (contains)')
+        .option('--reference <ref>', 'Filter by reference (contains)')
+        .option('--amount-min <n>', 'Filter by minimum amount', parseFloat)
+        .option('--amount-max <n>', 'Filter by maximum amount', parseFloat)
         .option('--limit <n>', 'Max results (default 50)', parsePositiveInt)
         .option('--api-key <key>', 'API key (overrides stored/env)')
         .option('--json', 'Output as JSON')
         .action((accountResourceId, opts) => apiAction(async (client) => {
-        const filter = {};
-        if (opts.status)
-            filter.status = { eq: opts.status };
-        if (opts.from || opts.to) {
-            const dateFilter = {};
-            if (opts.from)
-                dateFilter.gte = opts.from;
-            if (opts.to)
-                dateFilter.lte = opts.to;
-            filter.date = dateFilter;
-        }
+        const filter = buildBankRecordFilter({
+            status: opts.status,
+            from: opts.from,
+            to: opts.to,
+            description: opts.description,
+            payer: opts.payer,
+            reference: opts.reference,
+            amountMin: opts.amountMin,
+            amountMax: opts.amountMax,
+        });
         const res = await searchBankRecords(client, accountResourceId, {
-            filter: Object.keys(filter).length > 0 ? filter : undefined,
+            filter,
             limit: opts.limit ?? 50,
             offset: 0,
-            sort: { sortBy: ['date'], order: 'DESC' },
+            sort: { sortBy: ['valueDate'], order: 'DESC' },
         });
         if (opts.json) {
             console.log(JSON.stringify(res, null, 2));
@@ -93,10 +98,49 @@ export function registerBankCommand(program) {
             }
             console.log(chalk.bold(`Bank Records (${res.data.length} of ${res.totalElements}):\n`));
             for (const r of res.data) {
-                const amount = r.amount >= 0
-                    ? chalk.green(`+${r.amount.toFixed(2)}`)
-                    : chalk.red(r.amount.toFixed(2));
-                console.log(`  ${chalk.cyan(r.resourceId)}  ${r.date}  ${amount}  ${r.description}  ${chalk.dim(r.status)}`);
+                const net = typeof r.netAmount === 'number' && Number.isFinite(r.netAmount) ? r.netAmount : 0;
+                const amount = net >= 0
+                    ? chalk.green(`+${net.toFixed(2)}`)
+                    : chalk.red(net.toFixed(2));
+                const payer = r.extContactName ? `  ${chalk.yellow(r.extContactName)}` : '';
+                console.log(`  ${chalk.cyan(r.resourceId)}  ${r.valueDate}  ${amount}  ${r.description ?? ''}${payer}  ${chalk.dim(r.status)}`);
+            }
+        }
+    })(opts));
+    // ── clio bank add-records ──────────────────────────────────────
+    bank
+        .command('add-records <accountResourceId>')
+        .description('Add bank records via JSON (1-100 records per call)')
+        .requiredOption('--records <json>', 'JSON array: [{amount, transactionDate, description?, payerOrPayee?, reference?}]')
+        .option('--api-key <key>', 'API key (overrides stored/env)')
+        .option('--json', 'Output as JSON')
+        .action((accountResourceId, opts) => apiAction(async (client) => {
+        const parsed = JSON.parse(opts.records);
+        if (!Array.isArray(parsed))
+            throw new Error('--records must be a JSON array');
+        if (parsed.length < 1 || parsed.length > 100)
+            throw new Error('--records must contain 1-100 entries');
+        for (const [i, r] of parsed.entries()) {
+            if (typeof r !== 'object' || r === null)
+                throw new Error(`records[${i}] must be an object`);
+            if (typeof r.amount !== 'number' || !Number.isFinite(r.amount))
+                throw new Error(`records[${i}].amount must be a finite number`);
+            if (typeof r.transactionDate !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(r.transactionDate))
+                throw new Error(`records[${i}].transactionDate must be YYYY-MM-DD`);
+        }
+        const res = await addBankRecords(client, accountResourceId, parsed);
+        const errors = Array.isArray(res?.data?.errors) ? res.data.errors : [];
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
+        }
+        else {
+            if (errors.length > 0) {
+                console.log(chalk.red(`${errors.length} error(s):`));
+                for (const e of errors)
+                    console.log(`  ${chalk.red(String(e))}`);
+            }
+            else {
+                console.log(chalk.green(`Created ${parsed.length} bank record(s).`));
             }
         }
     })(opts));

package/dist/commands/contact-groups.js

@@ -0,0 +1,86 @@
+import chalk from 'chalk';
+import { listContactGroups, getContactGroup, searchContactGroups, createContactGroup, } from '../core/api/contact-groups.js';
+import { apiAction } from './api-action.js';
+import { parsePositiveInt, parseNonNegativeInt, requireFields } from './parsers.js';
+import { paginatedFetch, paginatedJson, displaySlice } from './pagination.js';
+export function registerContactGroupsCommand(program) {
+    const cmd = program
+        .command('contact-groups')
+        .description('Manage contact groups');
+    cmd
+        .command('list')
+        .description('List contact groups')
+        .option('--limit <n>', 'Max results', parsePositiveInt)
+        .option('--offset <n>', 'Offset', parseNonNegativeInt)
+        .option('--all', 'Fetch all pages')
+        .option('--api-key <key>', 'API key')
+        .option('--json', 'JSON output')
+        .action(apiAction(async (client, opts) => {
+        const result = await paginatedFetch(opts, (p) => listContactGroups(client, p), { label: 'Fetching contact groups' });
+        if (opts.json) {
+            console.log(paginatedJson(result, opts));
+            return;
+        }
+        console.log(chalk.bold(`Contact Groups (${result.data.length} of ${result.totalElements}):\n`));
+        const { items, overflow } = displaySlice(result.data);
+        for (const g of items)
+            console.log(`  ${chalk.cyan(g.resourceId)}  ${g.name}  ${chalk.dim(`${g.associatedContacts.length} contacts`)}`);
+        if (overflow > 0)
+            console.log(chalk.dim(`  ... and ${overflow} more`));
+    }));
+    cmd
+        .command('get <resourceId>')
+        .description('Get contact group details')
+        .option('--api-key <key>', 'API key')
+        .option('--json', 'JSON output')
+        .action((resourceId, opts) => apiAction(async (client) => {
+        const res = await getContactGroup(client, resourceId);
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
+            return;
+        }
+        const g = res.data;
+        console.log(chalk.bold('Name:'), g.name);
+        console.log(chalk.bold('Contacts:'), g.associatedContacts.length);
+        for (const c of g.associatedContacts)
+            console.log(`  ${chalk.cyan(c.resourceId)}  ${c.name}`);
+        console.log(chalk.bold('ID:'), g.resourceId);
+    })(opts));
+    cmd
+        .command('search <query>')
+        .description('Search contact groups by name')
+        .option('--limit <n>', 'Max results', parsePositiveInt)
+        .option('--offset <n>', 'Offset', parseNonNegativeInt)
+        .option('--api-key <key>', 'API key')
+        .option('--json', 'JSON output')
+        .action((query, opts) => apiAction(async (client) => {
+        const result = await paginatedFetch(opts, ({ limit, offset }) => searchContactGroups(client, { filter: { name: { contains: query } }, limit, offset }), { label: 'Searching contact groups', defaultLimit: 20 });
+        if (opts.json) {
+            console.log(paginatedJson(result, opts));
+            return;
+        }
+        if (result.data.length === 0) {
+            console.log('No contact groups found.');
+            return;
+        }
+        console.log(chalk.bold(`Found ${result.data.length} group(s):\n`));
+        for (const g of result.data)
+            console.log(`  ${chalk.cyan(g.resourceId)}  ${g.name}`);
+    })(opts));
+    cmd
+        .command('create')
+        .description('Create a contact group')
+        .option('--name <name>', 'Group name')
+        .option('--api-key <key>', 'API key')
+        .option('--json', 'JSON output')
+        .action(apiAction(async (client, opts) => {
+        requireFields(opts, [{ flag: '--name', key: 'name' }]);
+        const res = await createContactGroup(client, { name: opts.name });
+        if (opts.json) {
+            console.log(JSON.stringify(res.data, null, 2));
+            return;
+        }
+        console.log(chalk.green(`Contact group "${opts.name}" created.`));
+        console.log(chalk.bold('ID:'), res.data.resourceId);
+    }));
+}