jaz-clio 5.59.0 → 5.59.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/assets/skills/api/SKILL.md +4 -4
- package/assets/skills/api/references/bank-rule-column-mapping.md +1 -1
- package/assets/skills/cli/SKILL.md +1 -1
- package/assets/skills/conversion/SKILL.md +1 -1
- package/assets/skills/jaz-kit/SKILL.md +1 -1
- package/assets/skills/jaz-pseudo-sql/SKILL.md +1 -1
- package/assets/skills/jobs/SKILL.md +1 -1
- package/assets/skills/jobs/references/bank-recon.md +16 -3
- package/assets/skills/transaction-recipes/SKILL.md +1 -1
- package/cli.mjs +3 -1
- package/dashboard-routes-manifest.json +10 -0
- package/package.json +1 -1
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: jaz-api
|
|
3
|
-
version: 5.59.
|
|
3
|
+
version: 5.59.1
|
|
4
4
|
description: >-
|
|
5
5
|
Use this skill whenever you call, debug, or review code that touches the Jaz
|
|
6
6
|
REST API. Covers field names, response shapes, 159 production gotchas, error
|
|
@@ -286,8 +286,8 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
|
|
|
286
286
|
### Bank Rules
|
|
287
287
|
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]`. **Field asymmetry**: Request uses `appliesToReconciliationAccount` (string UUID), response returns it as an object `{ code, currencyCode, name }`.
|
|
288
288
|
90. **Bank rules search uses `/bank-rules/search`** — Standard search pattern with filter/sort/limit/offset. Filter fields: `appliesToReconciliationAccount`, `name`, `reference`, `resourceId`, `actionType`, `businessTransactionType`. Sort fields: `resourceId`, `name`, `actionType`, `businessTransactionType`, `reference`, `appliesToReconciliationAccount`, `createdAt`.
|
|
289
|
-
90a. **Bank rules create field is `appliesToReconciliationAccount`** (NOT `appliesToReconciliationAccountResourceId`) — the bank account UUID. `configuration` must nest under `reconcileWithDirectCashEntry` key. `configuration.reconcileWithDirectCashEntry.reference` is REQUIRED (omitting causes GENERAL_ERROR). `amountAllocationType`: use `"PERCENTAGE"` or `"FIXED"` — `"FIXED_AND_PERCENTAGE"` is read-only (include both `fixedAllocation` + `percentageAllocation` arrays and the server infers it). Optional config fields: `contactResourceId`, `internalNotes`, `tags`, `currencySettings`, `taxCurrencySettings`, `classifierConfig` on allocation lines.
|
|
290
|
-
90b. **Bank rules PUT is FULL REPLACEMENT** — `PUT /bank-rules/:id` replaces the entire rule. Must send `resourceId`, `appliesToReconciliationAccount`, and full `configuration` every time. Omitting any required field causes GENERAL_ERROR. Use read-modify-write pattern: GET current rule, merge changes, PUT full payload. Same pattern as items PUT (Rule 72) and capsules PUT (Rule 73).
|
|
289
|
+
90a. **Bank rules create field is `appliesToReconciliationAccount`** (NOT `appliesToReconciliationAccountResourceId`) — the bank account UUID. `configuration` must nest under `reconcileWithDirectCashEntry` key. `configuration.reconcileWithDirectCashEntry.reference` is REQUIRED (omitting causes GENERAL_ERROR). `amountAllocationType`: use `"PERCENTAGE"` or `"FIXED"` — `"FIXED_AND_PERCENTAGE"` is read-only (include both `fixedAllocation` + `percentageAllocation` arrays and the server infers it). Optional config fields: `contactResourceId`, `internalNotes`, `tags`, `currencySettings`, `taxCurrencySettings`, `classifierConfig` on allocation lines. **Send `searchFilter` too** — see 90d; a rule without one is never suggested.
|
|
290
|
+
90b. **Bank rules PUT is FULL REPLACEMENT** — `PUT /bank-rules/:id` replaces the entire rule. Must send `resourceId`, `appliesToReconciliationAccount`, and full `configuration` every time. Omitting any required field causes GENERAL_ERROR. Use read-modify-write pattern: GET current rule, merge changes, PUT full payload. Same pattern as items PUT (Rule 72) and capsules PUT (Rule 73). **`searchFilter` is the one exception**: omit it and the API keeps the stored condition, send `null` to remove it, send an object to replace it.
|
|
291
291
|
90c. **Bank rule POST canonical create payload** (verified live 2026-04, NOT obvious from any single field error):
|
|
292
292
|
```json
|
|
293
293
|
{
|
|
@@ -315,7 +315,7 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
|
|
|
315
315
|
|
|
316
316
|
**actionShortcutResourceId** for `apply_bank_rule` IS the rule's own `resourceId` from create response (no separate "action shortcut" entity).
|
|
317
317
|
|
|
318
|
-
90d. **Bank rules support column-value mapping** — `reconcileWithDirectCashEntry` can resolve fields per row from a custom bank-statement column: `amountSourceColumnKey` (set amount by a column; mutually exclusive with `amount`), `organizationAccountResourceIdMap`/`taxProfileResourceIdMap`/`classifierConfigMap` on each `fixedAllocation` line, and `contactResourceIdMap`/`tagsMap` on the shortcut. Each `*Map` is a `ColumnValueMapConfig` (`columnKey` + ordered `mappings[]`, first match wins, blank `matchValue` = catch-all); `targetResourceId` is a UUID (tag NAME for `tagsMap`). `reference` also takes `{{column:<key>}}` / `{{column_abs:<key>}}` tokens. Full shape: `references/bank-rule-column-mapping.md`.
|
|
318
|
+
90d. **Bank rules support column-value mapping** — `reconcileWithDirectCashEntry` can resolve fields per row from a custom bank-statement column: `amountSourceColumnKey` (set amount by a column; mutually exclusive with `amount`), `organizationAccountResourceIdMap`/`taxProfileResourceIdMap`/`classifierConfigMap` on each `fixedAllocation` line, and `contactResourceIdMap`/`tagsMap` on the shortcut. Each `*Map` is a `ColumnValueMapConfig` (`columnKey` + ordered `mappings[]`, first match wins, blank `matchValue` = catch-all); `targetResourceId` is a UUID (tag NAME for `tagsMap`). `reference` also takes `{{column:<key>}}` / `{{column_abs:<key>}}` tokens. Full shape: `references/bank-rule-column-mapping.md`. **The rule's WHEN side is the inline `searchFilter`, and without one the rule is never suggested.** Auto-reconciliation only considers rules whose stored condition is non-null, so a rule created without it exists, lists, and applies manually, but is never offered. Shape: `{"version": 1, "raw": "description:grab", "parsed": {"description": {"contains": "grab"}}}` — `raw` is the one-line form shown in the app and **may be blank**; `parsed` is what the matcher compiles. Condition fields: `description`, `extReference`, `extContactName`, `netAmount`, `valueDate`, plus the account's active custom Bank Fields. Operators (15, from the matcher's own map): TEXT `eq`/`contains`/`notContains`/`startWith`/`notStartWith`/`isBlank`/`isNotBlank`, compared case-insensitively, the blank pair taking no value; NUMERIC `eq`/`gt`/`gte`/`lt`/`lte`/`inRange`/`notInRange`; DATE `eq`/`gt`/`gte`/`lt`/`lte`/`between`/`notBetween`. Combine with `{"and": {...}}` or `{"orGroup": [{"and": {...}}]}`. **An unsupported field path does not error** — the rule saves, lists, and then never fires, because the matcher logs a warning server-side and skips it; use only the fields above. `relatedSearchShortcutResourceIds` (the retired saved-search path) is not exposed by this API at all; the platform rejects a request that sets both.
|
|
319
319
|
|
|
320
320
|
### Fixed Assets
|
|
321
321
|
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.
|
|
@@ -6,7 +6,7 @@ A bank rule's `reconcileWithDirectCashEntry` shortcut can resolve fields **per r
|
|
|
6
6
|
|
|
7
7
|
The columns referenced by `columnKey` are **Bank Fields** — typed custom columns (`DATE` / `STRING` / `AMOUNT`) defined per bank account and captured when a statement is imported. They make any statement column (branch code, bank charge, cost centre, settlement ref) first-class: usable in a rule's **conditions** (matching) and in its **outputs** (the maps below). `AMOUNT` fields keep their sign; `amountSourceColumnKey` uses the **absolute** value.
|
|
8
8
|
|
|
9
|
-
Scope note: the maps here are the rule **outputs** (what `create_bank_rule` / `update_bank_rule` set via `configuration`). The rule **conditions** (which statement lines the rule matches,
|
|
9
|
+
Scope note: the maps here are the rule **outputs** (what `create_bank_rule` / `update_bank_rule` set via `configuration`). The rule **conditions** (which statement lines the rule matches) are a separate field, `searchFilter`, which those same tools now set directly — `{ version: 1, raw, parsed }`, and a rule without one is never suggested by magic reconciliation. See jaz-api skill rule 90d for the condition grammar. The older linked-search-shortcut path (`relatedSearchShortcutResourceIds`) was retired upstream and is not exposed by this API.
|
|
10
10
|
|
|
11
11
|
## ColumnValueMapConfig shape
|
|
12
12
|
|
|
@@ -192,11 +192,24 @@ After creating, loop back to step 4 to reconcile.
|
|
|
192
192
|
```
|
|
193
193
|
create_bank_rule(
|
|
194
194
|
name: 'Monthly DBS Service Charge',
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
195
|
+
appliesToReconciliationAccount: '<bank-account-uuid>',
|
|
196
|
+
searchFilter: {
|
|
197
|
+
version: 1,
|
|
198
|
+
raw: 'description:service charge',
|
|
199
|
+
parsed: {and: {description: {contains: 'service charge'}, netAmount: {inRange: [20, 30]}}}
|
|
200
|
+
},
|
|
201
|
+
configuration: {
|
|
202
|
+
reconcileWithDirectCashEntry: {
|
|
203
|
+
reference: 'AUTO-{{bankReference}}',
|
|
204
|
+
amountAllocationType: 'PERCENTAGE',
|
|
205
|
+
percentageAllocation: [{organizationAccountResourceId: '<Bank Charges uuid>', amount: 100}]
|
|
206
|
+
}
|
|
207
|
+
}
|
|
198
208
|
)
|
|
199
209
|
```
|
|
210
|
+
`searchFilter` is the WHEN side and is what makes the rule eligible for suggestion at all — a rule
|
|
211
|
+
without one is never offered by auto-reconciliation. `configuration` is the THEN side. Condition
|
|
212
|
+
fields: `description`, `extReference`, `extContactName`, `netAmount`, `valueDate`.
|
|
200
213
|
Next month's same charge auto-reconciles via `apply_bank_rule`.
|
|
201
214
|
|
|
202
215
|
**Path D — flag for investigation:** if no match and no source document, surface to the user with the `extContactName + description` and the `netAmount`. Common: personal transactions, refunds, intercompany unrecorded, bank-feed errors. Record the unresolved item so it carries forward.
|
package/cli.mjs
CHANGED
|
@@ -820,7 +820,9 @@ Required: name, appliesToReconciliationAccount (bank account UUID, no "ResourceI
|
|
|
820
820
|
|
|
821
821
|
configuration MUST nest under reconcileWithDirectCashEntry: reference (REQUIRED), amountAllocationType ("PERCENTAGE" | "FIXED" \u2014 don't send "FIXED_AND_PERCENTAGE"), percentageAllocation[] / fixedAllocation[] of { organizationAccountResourceId, amount }. Advanced: column-value mapping \u2014 amountSourceColumnKey + the *Map fields drive amount/account/tax/classifier/contact/tags from a bank column (amount XOR amountSourceColumnKey).
|
|
822
822
|
|
|
823
|
-
|
|
823
|
+
searchFilter = the WHEN side; without it the rule is never suggested.
|
|
824
|
+
|
|
825
|
+
Optional fields, the minimum payload, the mapping shape and the condition grammar: jaz-api skill (bank rules, 90d). Dynamic strings: {{bankReference}}, {{bankPayee}}, {{bankDescription}}.`,params:{name:{type:"string",description:"Rule name \u2014 supports dynamic strings: {{bankReference}}, {{bankPayee}}, {{bankDescription}}"},appliesToReconciliationAccount:{type:"string",description:"Bank account UUID this rule applies to"},configuration:{type:"object",description:"MUST nest under reconcileWithDirectCashEntry key. reference is REQUIRED. See tool description for full structure."},searchFilter:{type:"object",description:"Condition { version: 1, raw, parsed }; raw may be blank."}},required:["name","appliesToReconciliationAccount","configuration"],group:"bank_rules",readOnly:!1,searchHint:"create automatic bank reconciliation rule",execute:async(t,e)=>dG(t.client,e)},{name:"update_bank_rule",description:"Update an existing bank reconciliation rule. FULL REPLACEMENT \u2014 the API replaces the entire rule on update. You MUST provide the complete configuration, appliesToReconciliationAccount, and name every time. Use get_bank_rule first to read the current state, merge your changes, then call this tool with the full payload. searchFilter is the ONE exception: omit keeps it, null removes it. Dynamic strings: {{bankReference}}, {{bankPayee}}, {{bankDescription}}.",params:{resourceId:{type:"string",description:"Bank rule resourceId"},name:{type:"string",description:"Rule name \u2014 supports dynamic strings: {{bankReference}}, {{bankPayee}}, {{bankDescription}}"},appliesToReconciliationAccount:{type:"string",description:"Bank account UUID this rule applies to (required for update \u2014 full replacement)"},configuration:{type:"object",description:"Full configuration object \u2014 must nest under reconcileWithDirectCashEntry key (same structure as create). reference is REQUIRED."},searchFilter:{type:"object",description:"Condition { version: 1, raw, parsed }. Omit keeps the stored one, null removes it."}},required:["resourceId","name","appliesToReconciliationAccount","configuration"],group:"bank_rules",readOnly:!1,searchHint:"update bank rule conditions actions matching",execute:async(t,e)=>fG(t.client,e.resourceId,{resourceId:e.resourceId,name:e.name,appliesToReconciliationAccount:e.appliesToReconciliationAccount,configuration:e.configuration,...e.searchFilter!==void 0?{searchFilter:e.searchFilter}:{}})},Xr("delete_bank_rule","Delete a bank reconciliation rule.","bank_rules",(t,e)=>pG(t,e),"permanently delete a bank reconciliation rule"),{name:"view_auto_reconciliation",description:'Generate auto-reconciliation suggestions for specific bank statement entries (no account-wide mode). READ-ONLY \u2014 does NOT write. Returns execution-ready `suggestions[]`: each carries `recommendedTool` (the commit tool to call), `execute` (ready-to-pass args \u2014 merge bankAccountResourceId for reconcile_magic_match), `confidenceTier` (high/medium/low), and `autoCommitEligible` (true \u21D2 safe to commit without review). Drive the flow: for each suggestion, if `autoCommitEligible` call its `recommendedTool` with `execute`; otherwise surface for confirmation \u2014 pass `includeReviewDetails:true` to also get `review[]` (the not-auto lines enriched with the bank line + the matched bill/invoice) for a side-by-side "does this match?" card. Pass `includeRaw:true` to also get the unmapped payload. Cost tracks entries passed \u2014 batch large backlogs. On a 500 the tool returns `{degraded:true}`; recover via the `clio jobs bank-recon match` cascade matcher. A line whose bank line could not be read omits `bankLine`; the reason is in `partialFailures` \u2014 read it before concluding a line has none.',params:{bankAccountResourceId:{type:"string",description:"Bank account resourceId"},bankStatementEntryResourceIds:{type:"array",items:{type:"string"},description:"Entries to suggest for. Source from search_bank_records (status UNRECONCILED)."},recommendationType:{type:"string",enum:[...vP],description:"What to compute. RECOMMENDATIONS returns every type except MAGIC_MATCH in one ranked call and is cheaper; MAGIC_MATCH scans open transactions so it is asked for alone. No value returns everything."},autoCommitMaxAmount:{type:"number",description:"Optional hard cap \u2014 a suggestion whose amount exceeds this is never autoCommitEligible (forces checkpoint)."},includeRaw:{type:"boolean",description:"Also return the raw unmapped generateMagicRecommendations payload (default false)."},includeReviewDetails:{type:"boolean",description:'Also return `review[]`: the lines needing human review (have a plan but NOT auto-committable), each enriched with the bank line (date, amount, counterparty) and the matched bill/invoice (reference + amount) \u2014 for an interactive side-by-side "does this match?" card. Default false (an extra bank-records + per-line lookup).'}},required:["recommendationType","bankStatementEntryResourceIds"],group:"bank",maxResultSizeChars:2e4,readOnly:!0,searchHint:"view automatic bank reconciliation matches suggestions execution ready",isConcurrencySafe:!0,execute:async(t,e)=>{let r=e.bankAccountResourceId,n;try{n=await t.client.post("/api/v1/search-magic-reconciliation",{bankAccountResourceId:r,recommendationType:e.recommendationType,bankStatementEntryResourceIds:e.bankStatementEntryResourceIds})}catch(s){let a=s.status??s.response?.status;if(a===404)return{notSupported:!0,reason:"Endpoint /search-magic-reconciliation not available"};if(a===500)return{degraded:!0,reason:"Suggestion engine returned 500 (likely high-volume OOM). Recover via the `clio jobs bank-recon match` cascade matcher, which does not hit this endpoint."};throw s}let i=Nst(n,{bankAccountResourceId:r,autoCommitMaxAmount:e.autoCommitMaxAmount}),o=e.includeReviewDetails===!0?await Ost(t.client,r,i):void 0;return{...o?.partialFailures?.length?{partialFailures:o.partialFailures}:{},suggestions:i,...o?{review:o.items}:{},...e.includeRaw===!0?{raw:n}:{}}}},Ar("list_fixed_assets","List fixed assets. Returns name, reference, type, category, status, purchase amount, net book value.","fixed_assets",(t,e,r)=>hG(t,{limit:r,offset:e}),"list fixed assets with depreciation status"),Bi("get_fixed_asset","Get full fixed asset details including depreciation schedule, accounts, disposal info.","fixed_assets",(t,e)=>yk(t,e),"get fixed asset details depreciation schedule"),Xt({name:"search_fixed_assets",description:"Search fixed assets.",group:"fixed_assets",fields:oR,defaults:sR,fetcher:mG,searchHint:"find fixed assets FA register PPE by name status category tag type date amount range"}),{name:"create_fixed_asset",description:`Register a fixed asset linked to an existing purchase transaction (bill or journal).
|
|
824
826
|
- saveAsDraft defaults to true. Set to false to activate \u2014 requires ALL fields below.
|
|
825
827
|
- ACTIVE assets require: purchaseBusinessTransactionType + purchaseBusinessTransactionResourceId
|
|
826
828
|
(the purchase LINE ITEM on that bill/journal, NOT the document resourceId \u2014 see the param).
|
|
@@ -811,6 +811,11 @@
|
|
|
811
811
|
"path": "/purchase-payments/all-payments/due-purchase-payments",
|
|
812
812
|
"label": "Due Purchase Payments"
|
|
813
813
|
},
|
|
814
|
+
{
|
|
815
|
+
"key": "purchase-payments.all-payments.unapplied-batch-purchase-payments",
|
|
816
|
+
"path": "/purchase-payments/all-payments/unapplied-batch-purchase-payments",
|
|
817
|
+
"label": "Unapplied Batch Purchase Payments"
|
|
818
|
+
},
|
|
814
819
|
{
|
|
815
820
|
"key": "purchase-payments.disbursements.cancelled",
|
|
816
821
|
"path": "/purchase-payments/disbursements/cancelled",
|
|
@@ -1116,6 +1121,11 @@
|
|
|
1116
1121
|
"path": "/sale-payments/all-payments/due-sale-payments",
|
|
1117
1122
|
"label": "Due Sale Payments"
|
|
1118
1123
|
},
|
|
1124
|
+
{
|
|
1125
|
+
"key": "sale-payments.all-payments.unapplied-batch-sale-payments",
|
|
1126
|
+
"path": "/sale-payments/all-payments/unapplied-batch-sale-payments",
|
|
1127
|
+
"label": "Unapplied Batch Sale Payments"
|
|
1128
|
+
},
|
|
1119
1129
|
{
|
|
1120
1130
|
"key": "sale-payments.due-payments.due-customer-credit-refunds",
|
|
1121
1131
|
"path": "/sale-payments/due-payments/due-customer-credit-refunds",
|