jaz-clio 4.34.5 → 4.34.6

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 4.34.5
+version: 4.34.6
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 117 production gotchas, error
@@ -150,7 +150,8 @@ You are working with the **Jaz REST API** — the accounting platform backend. A
 ### Jaz Magic — Extraction & Autofill
 57. **When the user starts from an attachment, always use Jaz Magic** — if the input is a PDF, JPG, or any document image (invoice, bill, receipt), the correct path is `POST /magic/createBusinessTransactionFromAttachment`. Do NOT manually construct a `POST /invoices` or `POST /bills` payload from an attachment — Jaz Magic handles the entire extraction-and-autofill pipeline server-side: OCR, line item detection, contact matching, CoA auto-mapping via ML learning, and draft creation with all fields pre-filled. Only use `POST /invoices` or `POST /bills` when building transactions from structured data (JSON, CSV, database rows) where the fields are already known.
 58. **Two upload modes with different content types** — `sourceType: "FILE"` requires **multipart/form-data** with `sourceFile` blob (JSON body fails with 400 "sourceFile is a required field"). `sourceType: "URL"` accepts **application/json** with `sourceURL` string. The OAS only documents URL mode — FILE mode (the common case) is undocumented.
-59. **Three required fields**: `sourceFile` (multipart blob — NOT `file`), `businessTransactionType` (`"INVOICE"`, `"BILL"`, `"CUSTOMER_CREDIT_NOTE"`, or `"SUPPLIER_CREDIT_NOTE"` — `EXPENSE` rejected), `sourceType` (`"FILE"` or `"URL"`). All three are validated server-side. **CRITICAL: multipart form field names are camelCase** — `businessTransactionType`, `sourceType`, `sourceFile`, NOT snake_case. Using `business_transaction_type` returns 422 "businessTransactionType is a required field". The File blob must include a filename and correct MIME type (e.g. `application/pdf`, `image/jpeg`) — bare `application/octet-stream` blobs are rejected with 400 "Invalid file type".
+59. **Three required fields + one optional**: `sourceFile` (multipart blob — NOT `file`), `businessTransactionType` (`"INVOICE"`, `"BILL"`, `"CUSTOMER_CREDIT_NOTE"`, or `"SUPPLIER_CREDIT_NOTE"` — `EXPENSE` rejected), `sourceType` (`"FILE"` or `"URL"`). Optional: `uploadMode` (`"SEPARATE"` default, or `"MERGED"` for a single PDF containing multiple documents — the backend splits it via boundary detection before extraction). All required fields are validated server-side. **CRITICAL: multipart form field names are camelCase** — `businessTransactionType`, `sourceType`, `sourceFile`, `uploadMode`, NOT snake_case. Using `business_transaction_type` returns 422 "businessTransactionType is a required field". The File blob must include a filename and correct MIME type (e.g. `application/pdf`, `image/jpeg`) — bare `application/octet-stream` blobs are rejected with 400 "Invalid file type".
+59a. **MERGED upload workflow tracking** — When `uploadMode: "MERGED"`, the upload response `workflowResourceId` is a **parent** tracking ID. The backend splits the PDF, then creates **child** workflows for each split page — these child IDs appear in `POST /magic/workflows/search` (by fileName or createdAt), NOT the parent ID. To track MERGED progress, search by `fileName` rather than the parent `workflowResourceId`.
 60. **Response maps transaction types**: Request `INVOICE` → response `SALE`. Request `BILL` → response `PURCHASE`. Request `CUSTOMER_CREDIT_NOTE` → response `SALE_CREDIT_NOTE`. Request `SUPPLIER_CREDIT_NOTE` → response `PURCHASE_CREDIT_NOTE`. S3 paths follow the response type. The response `validFiles[]` array contains `workflowResourceId` for tracking extraction progress via `POST /magic/workflows/search`.
 61. **Extraction is asynchronous** — the API response is immediate (file upload confirmation only). The actual Magic pipeline — OCR, line item extraction, contact matching, CoA learning, and autofill — runs asynchronously. Use `POST /magic/workflows/search` with `filter.resourceId.eq: "<workflowResourceId>"` to check status (SUBMITTED → PROCESSING → COMPLETED/FAILED). When COMPLETED, `businessTransactionDetails.businessTransactionResourceId` contains the created draft BT ID. The `subscriptionFBPath` in the response is a Firebase Realtime Database path for real-time status updates (alternative to polling).
 62. **Accepts PDF and JPG/JPEG** — both file types confirmed working. Handwritten documents are accepted at upload stage (extraction quality varies). `fileType` in response reflects actual format: `"PDF"`, `"JPEG"`.

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 4.34.5
+version: 4.34.6
 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: 4.34.5
+version: 4.34.6
 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/jobs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-jobs
-version: 4.34.5
+version: 4.34.6
 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: 4.34.5
+version: 4.34.6
 description: >-
   Use this skill when modeling complex multi-step accounting transactions —
   anything that spans multiple periods, involves changing amounts, or requires

package/dist/commands/magic.js

@@ -51,6 +51,7 @@ export function registerMagicCommand(program) {
         .option('--file <path>', 'Local file path (PDF, JPG, PNG, HEIC, XLS, XLSX, EML, ZIP). ZIP: extracts and uploads each file. Encrypted PDFs: name__pw__password.pdf')
         .option('--url <url>', 'Remote file URL (alternative to --file)')
         .option('--type <type>', `Document type: ${VALID_TYPES}`)
+        .option('--merged', 'Treat file as a merged PDF containing multiple documents (split before extraction)')
         .option('--api-key <key>', 'API key (overrides stored/env)')
         .option('--json', 'Output as JSON')
         .action(apiAction(async (client, opts) => {
@@ -72,6 +73,18 @@ export function registerMagicCommand(program) {
             console.error(chalk.red(`Error: invalid type "${opts.type}". Valid: ${VALID_TYPES}`));
             process.exit(1);
         }
+        // Validate --merged constraints
+        if (opts.merged) {
+            if (opts.url) {
+                console.error(chalk.red('Error: --merged is only supported with --file, not --url'));
+                process.exit(1);
+            }
+            const ext = extname(opts.file).toLowerCase();
+            if (ext !== '.pdf') {
+                console.error(chalk.red('Error: --merged requires a PDF file (got ' + ext + ')'));
+                process.exit(1);
+            }
+        }
         let sourceFile;
         let sourceFileName;
         let decryptedPath;
@@ -105,6 +118,7 @@ export function registerMagicCommand(program) {
             sourceFile,
             sourceFileName,
             sourceUrl: opts.url,
+            uploadMode: opts.merged ? 'MERGED' : undefined,
         });
         const data = res.data;
         const validFile = data.validFiles?.[0];

package/dist/core/api/magic.js

@@ -1,9 +1,3 @@
-// ── API Functions ────────────────────────────────────────────────
-/**
- * Upload a file or URL to create a draft business transaction via OCR extraction.
- * Processing is async — response returns immediately with workflowResourceId.
- * Use searchMagicWorkflows() to check status.
- */
 export async function createFromAttachment(client, data) {
     const formData = new FormData();
     formData.append('businessTransactionType', data.businessTransactionType);
@@ -14,6 +8,8 @@ export async function createFromAttachment(client, data) {
         formData.append('sourceUrl', data.sourceUrl);
     if (data.attachmentId)
         formData.append('attachmentId', data.attachmentId);
+    if (data.uploadMode)
+        formData.append('uploadMode', data.uploadMode);
     return client.postMultipart('/api/v1/magic/createBusinessTransactionFromAttachment', formData);
 }
 /**

package/dist/core/registry/tools.js

@@ -2675,6 +2675,7 @@ Dynamic strings for reference/name/notes: {{Day}}, {{Date}}, {{Date+X}}, {{DateR
             },
             sourceUrl: { type: 'string', description: 'URL of the source file' },
             attachmentId: { type: 'string', description: 'Attachment ID (alternative to URL)' },
+            uploadMode: { type: 'string', enum: ['SEPARATE', 'MERGED'], description: 'Upload mode: SEPARATE (default, one doc per file) or MERGED (single PDF with multiple docs, auto-split before extraction). MERGED only works with PDF files.' },
         },
         required: ['businessTransactionType'],
         group: 'magic',
@@ -2687,6 +2688,7 @@ Dynamic strings for reference/name/notes: {{Day}}, {{Date}}, {{Date+X}}, {{DateR
                 businessTransactionType: input.businessTransactionType,
                 sourceUrl: input.sourceUrl,
                 attachmentId: input.attachmentId,
+                uploadMode: input.uploadMode,
             });
         },
     },

package/package.json

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