jaz-clio 5.40.5 → 5.41.0

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.40.5
+version: 5.41.0
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 159 production gotchas, error
@@ -181,7 +181,7 @@ The rest of this skill — field names, gotchas, error catalog, dependency order
 50a. **`query` field — Jaz search operators** — 14 endpoints accept an optional `query` string alongside `filter`: invoices, bills, customer/supplier credit notes, journals, cashflow-transactions, bank-records, contacts, items, capsules, fixed-assets, scheduled-transactions, chart-of-accounts, tax-profiles. Example: `{ "query": "status:unpaid AND $500+", "limit": 50 }`. Key syntax: amounts (`$500+`, `$100-500`, `amount:>2m`, magnitude suffixes `5k`/`2m`/`1b`), negative (`$-500`), absolute value (`abs:1000+`), dates (`date:this month`, `date:-30d`, `due:overdue`, `submitted:last week`, `lastpayment:-7d`), status/enum (`status:unpaid`, `currency:SGD,USD` — comma = OR), string fields (`customer:acme`, `ref:INV-*` wildcard, `=ref:INV-001` exact, `ref:/\d{4}/` regex), blank checks (`ref:blank`, `tag:!blank`), booleans (`hasattachment:yes`, `customer:yes`), negation (`!status:paid` or `NOT status:void` — **never `-`** for negation), logic (`AND`/`OR` with implicit AND on space), grouping, inline sort (`sort:amount:desc`). Full syntax spec (all fields, aliases, entity field lists, examples): **`references/search-syntax.md`**.
 50b. **`query` + `filter` merge** — When both are present, they are merged at the filter level. Explicit `filter` keys win on conflict. Use `query` for human-readable shorthand, `filter` for programmatic precision, or combine both: `{ "query": "date:this year", "filter": { "currencyCode": { "in": ["SGD"] } } }`.
 50c. **`query` error handling** — Unknown field name → `query_not_understood` (400). Bad enum value (e.g. `status:BADVALUE`) → **empty results, no error** (silent miss). Unsupported endpoint → `query_not_supported` (400). Parser unavailable → `query_parse_error` (502). Empty/null/whitespace query → passthrough (ignored). In CLI/MCP: use `--query` / `query` param only on supported entities — unsupported entities have no `--query` flag.
-51. **Filter operator reference** — String: `eq`, `neq`, `contains`, `in` (array, max 100), `likeIn` (array, max 100), `reg` (regex array, max 100), `isNull` (bool). Numeric: `eq`, `gt`, `gte`, `lt`, `lte`, `in`. Date (YYYY-MM-DD): `eq`, `gt`, `gte`, `lt`, `lte`, `between` (exactly 2 values). DateTime (RFC3339): same operators, converted to epoch ms internally. Boolean: `eq`. JSON: `jsonIn`, `jsonNotIn`. Logical: nest with `and`/`or`/`not` objects, or use `andGroup`/`orGroup` arrays (invoices, bills, journals, credit notes).
+51. **Filter operator reference** — An operator the target type does not declare is now rejected with a 400 naming it, not ignored, so use the exact set. String: `eq`, `neq`, `contains`, `notContains`, `in` (array, max 100), `likeIn` (array, max 100), `reg` (substring array, max 100 — a term match despite the name, not a regex), `startWith`, `notStartWith`, `endWith`, `notEndWith`, `isNull`, `isBlank`, `isNotBlank` (each takes the **string** `"true"`/`"false"`, not a bool). Numeric: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `inRange`/`notInRange` (exactly 2 values, low then high). Date (YYYY-MM-DD): `eq`, `gt`, `gte`, `lt`, `lte`, `between`/`notBetween` (exactly 2 values), `isNull`, `isNotNull`. DateTime (RFC3339): `eq`, `gt`, `gte`, `lt`, `lte`, `between`, converted to epoch ms internally. Boolean: `eq`. JSON: `jsonIn`, `jsonNotIn`. Logical: `and`/`or` objects everywhere; `andGroup`/`orGroup` arrays on invoices, bills, journals, cashflow transactions, payments, batch payments and the order family (orders, quotes, requests, line items) — **not** on credit notes. `not` exists only on contacts, items, tags, custom fields, tax profiles and nano classifiers; it is **not** available on invoices, bills or journals.
 52. **Date format asymmetry (CRITICAL)** — Request dates: `YYYY-MM-DD` strings (all create/update and DateExpression filters). Request datetimes: RFC3339 strings (DateTimeExpression filters for `createdAt`, `updatedAt`, `approvedAt`, `submittedAt`). **ALL response dates**: `int64` epoch milliseconds — including `valueDate`, `createdAt`, `updatedAt`, `approvedAt`, `submittedAt`, `matchDate`. Convert: `new Date(epochMs).toISOString().slice(0,10)`. **Timezone convention**: ALL business dates (`valueDate`, `dueDate`, `startDate`, `endDate`, etc.) are in the **organization's timezone** — never UTC. The epoch ms stored in the DB represents the org-local date (no timezone conversion is ever needed). Only audit timestamps (`createdAt`, `updatedAt`, `action_at`) are UTC.
 53. **Field aliases on create endpoints** — Middleware transparently maps: `issueDate`/`date` → `valueDate` (invoices, bills, credit notes, journals). `name` → `tagName` (tags) or `internalName` (items). `paymentDate` → `valueDate`, `bankAccountResourceId` → `accountResourceId` (payments). `paymentAmount` → `refundAmount`, `paymentMethod` → `refundMethod` (credit note refunds). `accountType` → `classificationType`, `currencyCode` → `currency` (CoA). Canonical names always work; aliases are convenience only.
 54. **All search/list responses are flat** — every search and list endpoint returns `{ totalElements, totalPages, data: [...] }` directly (no outer `data` wrapper). Access the array via `response.data`, pagination via `response.totalElements`. **Two exceptions**: (a) `GET /bank-accounts` returns a plain array `[{...}]` (see Rule 18), (b) `GET /invoices/:id` returns a flat object `{...}` (no `data` wrapper) — unlike `GET /bills/:id`, `GET /contacts/:id`, `GET /journals/:id` which wrap in `{ data: {...} }`. Normalize the invoice GET response before use.

package/assets/skills/api/references/search-reference.md

@@ -87,9 +87,13 @@ When both are present, merged at filter level. Explicit `filter` keys win on con
 | `neq` | string | `{ "status": { "neq": "DRAFT" } }` | Not equal |
 | `contains` | string | `{ "reference": { "contains": "INV" } }` | Substring match |
 | `in` | string[] | `{ "status": { "in": ["ACTIVE", "DRAFT"] } }` | Max 100 values |
-| `reg` | string[] | `{ "name": { "reg": ["^Acme.*"] } }` | Regex patterns, max 100 |
-| `likeIn` | string[] | `{ "name": { "likeIn": ["Acme%"] } }` | SQL LIKE patterns, max 100 |
-| `isNull` | string | `{ "reference": { "isNull": "true" } }` | Null check |
+| `reg` | string[] | `{ "name": { "reg": ["Acme"] } }` | Substring match despite the name, max 100 |
+| `likeIn` | string[] | `{ "name": { "likeIn": ["Acme"] } }` | Substring match, max 100 |
+| `isNull` | string | `{ "reference": { "isNull": "true" } }` | Null check, takes "true"/"false" |
+| `notContains` | string | `{ "reference": { "notContains": "DRAFT" } }` | Substring exclusion |
+| `startWith` / `notStartWith` | string | `{ "reference": { "startWith": "INV-" } }` | Prefix match, case sensitive |
+| `endWith` / `notEndWith` | string | `{ "reference": { "endWith": "-01" } }` | Suffix match, case sensitive |
+| `isBlank` / `isNotBlank` | string | `{ "terms": { "isBlank": "true" } }` | Null-or-empty check, takes "true"/"false" |
 
 ### Numeric Operators (`BigDecimalExpression`)
 
@@ -101,10 +105,13 @@ When both are present, merged at filter level. Explicit `filter` keys win on con
 | `lt` | number | `{ "totalAmount": { "lt": 10000 } }` |
 | `lte` | number | `{ "totalAmount": { "lte": 10000 } }` |
 | `in` | number[] | `{ "totalAmount": { "in": [100, 200, 300] } }` |
+| `neq` | number | `{ "totalAmount": { "neq": 1000 } }` |
+| `inRange` | number[2] | `{ "totalAmount": { "inRange": [100, 1000] } }` |
+| `notInRange` | number[2] | `{ "totalAmount": { "notInRange": [100, 1000] } }` |
 
 ### Integer Operators (`IntExpression`)
 
-Same as numeric: `eq`, `gt`, `gte`, `lt`, `lte`, `in` (used by `terms` field on invoices/bills).
+Same as numeric minus `neq`: `eq`, `gt`, `gte`, `lt`, `lte`, `in`, `inRange`, `notInRange` (used by `terms` field on invoices/bills).
 
 ### Date Operators (`DateExpression`) — format: `YYYY-MM-DD`
 
@@ -116,8 +123,10 @@ Same as numeric: `eq`, `gt`, `gte`, `lt`, `lte`, `in` (used by `terms` field on
 | `lt` | string | `{ "valueDate": { "lt": "2026-12-31" } }` |
 | `lte` | string | `{ "valueDate": { "lte": "2026-12-31" } }` |
 | `between` | string[2] | `{ "valueDate": { "between": ["2026-01-01", "2026-03-31"] } }` |
+| `notBetween` | string[2] | `{ "valueDate": { "notBetween": ["2026-01-01", "2026-03-31"] } }` |
+| `isNull` / `isNotNull` | string | `{ "dueDate": { "isNull": "0001-01-01" } }` | takes the placeholder DATE, not "true" |
 
-**CRITICAL**: `between` requires EXACTLY 2 values. All date strings must be `YYYY-MM-DD`.
+**CRITICAL**: `between`, `notBetween`, `inRange` and `notInRange` require EXACTLY 2 values, low then high. Date `isNull`/`isNotNull` take the placeholder date `"0001-01-01"` — unlike the string ones, which take `"true"`/`"false"`. All date strings must be `YYYY-MM-DD`.
 
 ### DateTime Operators (`DateTimeExpression`) — format: RFC3339
 

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.40.5
+version: 5.41.0
 description: >-
   Use this skill when running Clio CLI commands, building shell scripts with
   Clio, debugging auth issues, understanding --json output, paginating results,

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 5.40.5
+version: 5.41.0
 description: >-
   Use this skill when migrating accounting data into Jaz — importing from Xero,
   QuickBooks, Sage, MYOB, or Excel exports. Covers the full conversion pipeline:

package/assets/skills/jaz-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-kit
-version: 5.40.5
+version: 5.41.0
 description: >-
   Use this skill when an accountant, bookkeeper, or owner is running real books
   in Jaz across one or more organizations from the terminal — setting up a

package/assets/skills/jaz-pseudo-sql/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-pseudo-sql
-version: 5.40.5
+version: 5.41.0
 description: >-
   Use this skill when answering ad-hoc data questions that aren't covered by
   download_export (canonical reports — anomaly, audit, aging, P&L, BS, GL,

package/assets/skills/jobs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-jobs
-version: 5.40.5
+version: 5.41.0
 description: >-
   Use this skill for recurring accounting workflows — month/quarter/year-end
   close, bank reconciliation, GST/VAT filing, payment runs, credit control,

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

@@ -1,6 +1,6 @@
 ---
 name: jaz-recipes
-version: 5.40.5
+version: 5.41.0
 description: >-
   Use this skill when modeling complex multi-step accounting transactions —
   anything that spans multiple periods, involves changing amounts, or requires