@aderis-erp/cli 1.0.15 → 1.1.0

package/dist/commands/async-jobs.js

@@ -0,0 +1,1158 @@
+import { Command, Args, Flags } from '@oclif/core';
+import { apiRequest, ApiError, isTextualMediaType, normalizeSortBy } from '../lib/api-client.js';
+import { getCurrentContext, getContext, getBaseUrls, hasCredentials, missingCredentialsMessage } from '../lib/config.js';
+// Add 'import' action if both create and update exist
+const HAS_IMPORT = true;
+const HAS_EXPORT = true;
+const HAS_CAMT053 = false;
+const NESTED_IMPORTS = [];
+const SUBCOMMANDS = [...["list", "create", "get", "update", "delete", "submit", "list-attempts", "list-items", "payload"], ...(HAS_IMPORT ? ['import'] : []), ...(HAS_EXPORT ? ['export'] : []), ...NESTED_IMPORTS.map(n => `import-${n}`)];
+const ENDPOINTS = {
+    'list': { method: 'GET', path: '/v1/async-jobs', summary: 'List the jobs the caller may see', pathParams: [], hasBody: false, isMultipart: false, isBinaryResponse: false, hasBinaryVariant: false, bodyArrayFields: [] },
+    'create': { method: 'POST', path: '/v1/async-jobs', summary: 'Create a draft job', pathParams: [], hasBody: true, isMultipart: false, isBinaryResponse: false, hasBinaryVariant: false, bodyArrayFields: [] },
+    'get': { method: 'GET', path: '/v1/async-jobs/{id}', summary: 'Read one job back', pathParams: ['id'], hasBody: false, isMultipart: false, isBinaryResponse: false, hasBinaryVariant: false, bodyArrayFields: [] },
+    'update': { method: 'PATCH', path: '/v1/async-jobs/{id}', summary: 'Replace the input of a draft', pathParams: ['id'], hasBody: true, isMultipart: false, isBinaryResponse: false, hasBinaryVariant: false, bodyArrayFields: [] },
+    'delete': { method: 'DELETE', path: '/v1/async-jobs/{id}', summary: 'Throw a job away', pathParams: ['id'], hasBody: false, isMultipart: false, isBinaryResponse: false, hasBinaryVariant: false, bodyArrayFields: [] },
+    'submit': { method: 'POST', path: '/v1/async-jobs/{id}/submit', summary: 'Ask for the work of a draft', pathParams: ['id'], hasBody: false, isMultipart: false, isBinaryResponse: false, hasBinaryVariant: false, bodyArrayFields: [] },
+    'list-attempts': { method: 'GET', path: '/v1/async-jobs/{id}/attempts', summary: 'List the runs of one job', pathParams: ['id'], hasBody: false, isMultipart: false, isBinaryResponse: false, hasBinaryVariant: false, bodyArrayFields: [] },
+    'list-items': { method: 'GET', path: '/v1/async-jobs/{id}/items', summary: 'List the records of one job and how the work on each ended', pathParams: ['id'], hasBody: false, isMultipart: false, isBinaryResponse: false, hasBinaryVariant: false, bodyArrayFields: [] },
+    'payload': { method: 'GET', path: '/v1/async-jobs/{id}/payload', summary: 'Read the input a job holds', pathParams: ['id'], hasBody: false, isMultipart: false, isBinaryResponse: false, hasBinaryVariant: false, bodyArrayFields: [] },
+};
+export default class AsyncJobs extends Command {
+    static description = 'Manage async jobs';
+    static examples = [
+        '<%= config.bin %> async-jobs list',
+        '<%= config.bin %> async-jobs get <id>',
+        '<%= config.bin %> async-jobs create --data \'{...}\'',
+        '<%= config.bin %> async-jobs update <id> --set field=value',
+        '<%= config.bin %> async-jobs import --file data.json',
+        '<%= config.bin %> async-jobs export --csv > async-jobs.csv',
+    ];
+    static args = {
+        action: Args.string({ description: 'Action: ' + SUBCOMMANDS.join(', '), required: true }),
+        id: Args.string({ description: 'Resource ID (for get, update, delete operations)', required: false }),
+    };
+    static flags = {
+        context: Flags.string({ char: 'c', aliases: ['config'], env: 'ADERIS_CONTEXT', description: 'Context to use for this command, overriding the current context (alias: --config)' }),
+        output: Flags.string({ char: 'o', description: 'Output format (default: table for import, json for other commands)', options: ['json', 'table', 'csv'] }),
+        table: Flags.boolean({ char: 't', description: 'Output as table (shortcut for --output table)' }),
+        csv: Flags.boolean({ description: 'Output as CSV (shortcut for --output csv)' }),
+        data: Flags.string({ char: 'd', description: 'JSON data for request body' }),
+        file: Flags.string({ char: 'f', description: 'Read request body from file' }),
+        set: Flags.string({ char: 's', description: 'Set individual field (e.g. --set firstName=John)', multiple: true }),
+        page: Flags.string({ description: 'Page number' }),
+        limit: Flags.string({ description: 'Items per page' }),
+        include: Flags.string({ description: 'Relations to include' }),
+        search: Flags.string({ description: 'Search term' }),
+        'sort-by': Flags.string({ description: 'Sort field(s), comma-separated. Direction (:ASC/:DESC) is optional; date-like fields default to DESC, others to ASC.' }),
+        filter: Flags.string({ description: 'Filter (e.g. --filter status=ACTIVE). Operators: in:A,B, like:%, gt:, lt:, null:', multiple: true }),
+        query: Flags.string({ description: 'Additional query params as JSON' }),
+        fields: Flags.string({ description: 'Comma-separated list of fields to return, applied by the API (e.g. --fields=id,name,status)' }),
+        sanitize: Flags.boolean({ description: 'Remove null values, audit fields, and duplicate UUIDs from output' }),
+        'show-http-request': Flags.boolean({ description: 'Show HTTP request details (method, URL, body)' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(AsyncJobs);
+        // Handle import action specially
+        if (args.action === 'import') {
+            if (!HAS_IMPORT)
+                this.error('Import not available for this resource');
+            await this.runImport(flags);
+            return;
+        }
+        // Handle export action specially
+        if (args.action === 'export') {
+            if (!HAS_EXPORT)
+                this.error('Export not available for this resource');
+            await this.runExport(flags);
+            return;
+        }
+        // Handle CAMT.053 import specially - sends raw XML
+        if (args.action === 'import-camt053') {
+            if (!HAS_CAMT053)
+                this.error('CAMT.053 import not available for this resource');
+            await this.runCamt053Import(flags);
+            return;
+        }
+        // Handle nested resource imports (e.g., import-prices)
+        if (args.action.startsWith('import-')) {
+            const suffix = args.action.replace('import-', '');
+            if (NESTED_IMPORTS.includes(suffix)) {
+                await this.runNestedImport(suffix, args.id, flags);
+                return;
+            }
+        }
+        const endpoint = ENDPOINTS[args.action];
+        if (!endpoint)
+            this.error(`Unknown action: ${args.action}. Available: ${SUBCOMMANDS.join(', ')}`);
+        let apiPath = endpoint.path;
+        for (let i = 0; i < endpoint.pathParams.length; i++) {
+            const param = endpoint.pathParams[i];
+            let value;
+            if (i === 0) {
+                // First path param always comes from positional argument
+                value = args.id;
+                if (!value)
+                    this.error('Missing required argument: id. Usage: aderis async-jobs <action> <id>');
+            }
+            else {
+                const flagName = param.replace(/\./g, '-').replace(/([A-Z])/g, '-$1').toLowerCase().replace(/^-/, '');
+                value = flags[flagName];
+                if (!value)
+                    this.error(`Missing required parameter: --${flagName}`);
+            }
+            apiPath = apiPath.replace(`{${param}}`, String(value));
+        }
+        const context = flags.context ? getContext(flags.context) : getCurrentContext();
+        if (!context)
+            this.error(flags.context ? `Context "${flags.context}" not found. List contexts with: aderis config list` : 'No context configured. Run: aderis auth login --new');
+        if (!hasCredentials(context))
+            this.error(missingCredentialsMessage(context));
+        const queryParams = {};
+        if (flags.page)
+            queryParams.page = flags.page;
+        if (flags.limit)
+            queryParams.limit = flags.limit;
+        if (flags.include)
+            queryParams.include = flags.include;
+        if (flags.search)
+            queryParams.search = flags.search;
+        if (flags['sort-by'])
+            queryParams.sortBy = normalizeSortBy(flags['sort-by']);
+        if (flags.fields)
+            queryParams.fields = flags.fields;
+        if (flags.query) {
+            try {
+                Object.assign(queryParams, JSON.parse(flags.query));
+            }
+            catch {
+                this.error('Invalid JSON in --query');
+            }
+        }
+        // Parse --filter flags (e.g., --filter status=ACTIVE becomes filter.status=$eq:ACTIVE)
+        if (flags.filter && flags.filter.length > 0) {
+            for (const f of flags.filter) {
+                const eqIndex = f.indexOf('=');
+                if (eqIndex === -1)
+                    this.error(`Invalid --filter format: ${f}. Use: --filter key=value`);
+                const key = f.slice(0, eqIndex);
+                const value = this.parseFilterValue(f.slice(eqIndex + 1));
+                const filterKey = `filter.${key}`;
+                if (filterKey in queryParams) {
+                    // Multiple filters on same field: collect as array
+                    const existing = queryParams[filterKey];
+                    queryParams[filterKey] = Array.isArray(existing) ? [...existing, value] : [existing, value];
+                }
+                else {
+                    queryParams[filterKey] = value;
+                }
+            }
+        }
+        let data;
+        if (endpoint.isMultipart) {
+            if (!flags.file)
+                this.error('Missing required --file flag for file upload');
+            const fsModule = await import('node:fs');
+            const pathModule = await import('node:path');
+            const FormDataLib = (await import('form-data')).default;
+            const form = new FormDataLib();
+            form.append('file', fsModule.createReadStream(flags.file), pathModule.basename(flags.file));
+            // Append --set fields as extra form fields (e.g. --set type=CREDIT_CARD_STATEMENT)
+            if (flags.set && flags.set.length > 0) {
+                for (const pair of flags.set) {
+                    const eqIndex = pair.indexOf('=');
+                    if (eqIndex === -1)
+                        this.error(`Invalid --set format: ${pair}. Use: --set key=value`);
+                    form.append(pair.slice(0, eqIndex), pair.slice(eqIndex + 1));
+                }
+            }
+            data = form;
+        }
+        else if (endpoint.hasBody) {
+            // For binary-response endpoints, --file is the output path, not a JSON
+            // input file — skip the read-as-body branch.
+            if (flags.file && !endpoint.isBinaryResponse) {
+                const fsModule = await import('node:fs');
+                try {
+                    data = JSON.parse(fsModule.readFileSync(flags.file, 'utf-8'));
+                }
+                catch {
+                    this.error(`Failed to read file: ${flags.file}`);
+                }
+            }
+            else if (flags.data) {
+                try {
+                    data = JSON.parse(flags.data);
+                }
+                catch {
+                    this.error('Invalid JSON in --data');
+                }
+            }
+            // Apply --set flags (can be combined with --data or --file)
+            if (flags.set && flags.set.length > 0) {
+                if (!data)
+                    data = {};
+                const body = data;
+                const arrayFields = new Set(endpoint.bodyArrayFields);
+                for (const pair of flags.set) {
+                    const eqIndex = pair.indexOf('=');
+                    if (eqIndex === -1)
+                        this.error(`Invalid --set format: ${pair}. Use: --set key=value`);
+                    const key = pair.slice(0, eqIndex);
+                    let value = pair.slice(eqIndex + 1);
+                    // Try to parse as JSON for numbers, booleans, arrays, objects
+                    try {
+                        value = JSON.parse(value);
+                    }
+                    catch { /* keep as string */ }
+                    // For top-level keys typed as array in the API schema, split bare
+                    // comma-separated input (e.g. "1171,1170" -> ["1171","1170"]) and
+                    // wrap a lone scalar in a single-element array. Skips when --set
+                    // already provided a JSON array.
+                    const isArrayField = !key.includes('.') && arrayFields.has(key);
+                    if (isArrayField && !Array.isArray(value)) {
+                        if (typeof value === 'string') {
+                            value = value.split(',').map(v => v.trim()).filter(v => v.length > 0);
+                        }
+                        else if (value !== undefined && value !== null) {
+                            value = [value];
+                        }
+                    }
+                    // Support nested keys like "address.city"
+                    const keys = key.split('.');
+                    if (keys.some(k => k === '__proto__' || k === 'constructor' || k === 'prototype')) {
+                        this.error(`Invalid --set key: ${key}`);
+                    }
+                    let obj = body;
+                    for (let i = 0; i < keys.length - 1; i++) {
+                        if (!(keys[i] in obj) || typeof obj[keys[i]] !== 'object') {
+                            obj[keys[i]] = {};
+                        }
+                        obj = obj[keys[i]];
+                    }
+                    obj[keys[keys.length - 1]] = value;
+                }
+            }
+        }
+        else if (flags.set && flags.set.length > 0) {
+            // For GET endpoints, --set adds query params
+            for (const pair of flags.set) {
+                const eqIndex = pair.indexOf('=');
+                if (eqIndex === -1)
+                    this.error(`Invalid --set format: ${pair}. Use: --set key=value`);
+                const key = pair.slice(0, eqIndex);
+                let value = pair.slice(eqIndex + 1);
+                try {
+                    value = JSON.parse(value);
+                }
+                catch { /* keep as string */ }
+                queryParams[key] = value;
+            }
+        }
+        // Show HTTP request details if --show-http-request flag is set
+        if (flags['show-http-request']) {
+            const baseUrls = getBaseUrls(context.environment);
+            const queryString = Object.keys(queryParams).length > 0
+                ? '?' + Object.entries(queryParams).flatMap(([k, v]) => {
+                    const vals = Array.isArray(v) ? v : [v];
+                    return vals.map(val => `${encodeURIComponent(k)}=${encodeURIComponent(String(val))}`);
+                }).join('&')
+                : '';
+            process.stderr.write(`\n${endpoint.method.toUpperCase()} ${baseUrls.api}${apiPath}${queryString}\n`);
+            if (endpoint.isMultipart) {
+                process.stderr.write(`Body: [multipart/form-data file upload]\n`);
+            }
+            else if (data) {
+                process.stderr.write(`Body: ${JSON.stringify(data, null, 2)}\n`);
+            }
+            process.stderr.write('\n');
+        }
+        try {
+            // Binary response: to -f / --file, or to stdout when it is redirected.
+            if (endpoint.isBinaryResponse) {
+                const toStdout = !flags.file;
+                if (toStdout && process.stdout.isTTY) {
+                    this.error(`Endpoint returns a binary file. Specify the output path with -f / --file (e.g. -f report.xlsx), or redirect stdout to a file.`);
+                }
+                const binResponse = await apiRequest(endpoint.method, apiPath, {
+                    params: Object.keys(queryParams).length > 0 ? queryParams : undefined,
+                    data,
+                    contextName: flags.context,
+                    binary: true,
+                });
+                const binData = binResponse.data;
+                const buffer = Buffer.isBuffer(binData)
+                    ? binData
+                    : Buffer.from(binData);
+                if (toStdout) {
+                    // Nothing else may reach stdout here — it is the file.
+                    process.stdout.write(buffer);
+                    return;
+                }
+                const fsModule = await import('node:fs');
+                fsModule.writeFileSync(flags.file, buffer);
+                this.log(`Saved ${buffer.length} bytes to ${flags.file}`);
+                return;
+            }
+            let response;
+            if (endpoint.hasBinaryVariant) {
+                // This route answers JSON or a file depending on the request body, so the
+                // bytes are read first and the response's own content-type decides. Asking
+                // for text here would corrupt an xlsx/pdf before anything could inspect it.
+                const raw = await apiRequest(endpoint.method, apiPath, {
+                    params: Object.keys(queryParams).length > 0 ? queryParams : undefined,
+                    data,
+                    contextName: flags.context,
+                    binary: true,
+                });
+                const rawType = String(raw.headers['content-type'] || '').toLowerCase();
+                const rawData = raw.data;
+                const buffer = Buffer.isBuffer(rawData) ? rawData : Buffer.from(rawData);
+                if (!isTextualMediaType(rawType)) {
+                    if (process.stdout.isTTY) {
+                        this.error(`The API returned ${rawType || 'binary data'}. Redirect stdout to a file, e.g. ... > report.xlsx`);
+                    }
+                    // Nothing else may reach stdout here — it is the file.
+                    process.stdout.write(buffer);
+                    return;
+                }
+                response = { data: buffer.toString('utf8'), headers: raw.headers, status: raw.status };
+            }
+            else {
+                response = await apiRequest(endpoint.method, apiPath, {
+                    params: Object.keys(queryParams).length > 0 ? queryParams : undefined,
+                    data,
+                    contextName: flags.context,
+                    acceptAny: true,
+                });
+            }
+            // Check content-type for non-JSON responses (XML, text, etc.)
+            const contentType = (response.headers['content-type'] || '').toLowerCase();
+            if (isTextualMediaType(contentType) && !contentType.startsWith('application/json')) {
+                // Output raw content for XML/text responses (CSV, plain, HTML, etc.)
+                this.log(String(response.data));
+                return;
+            }
+            // Parse JSON if response came as string (due to acceptAny)
+            let output = response.data;
+            if (typeof output === 'string') {
+                try {
+                    output = JSON.parse(output);
+                }
+                catch { /* keep as string */ }
+            }
+            // Extract data array from paginated wrapper (e.g., { data: [...], total: 3 })
+            if (output && typeof output === 'object' && !Array.isArray(output) && 'data' in output && Array.isArray(output.data)) {
+                output = output.data;
+            }
+            // For table/csv on non-array responses, auto-extract the primary array
+            // e.g., { payments: [...], total: 3 } → extract payments array
+            if ((flags.table || flags.output === 'table' || flags.csv || flags.output === 'csv')
+                && output && typeof output === 'object' && !Array.isArray(output)) {
+                const obj = output;
+                const arrayKeys = Object.keys(obj).filter(k => Array.isArray(obj[k]));
+                if (arrayKeys.length === 1) {
+                    output = obj[arrayKeys[0]];
+                }
+            }
+            // Sanitize output if requested
+            if (flags.sanitize) {
+                output = this.sanitizeOutput(output);
+            }
+            const fieldList = flags.fields?.split(',').map(f => f.trim());
+            if (flags.csv || flags.output === 'csv')
+                this.printCsv(output, fieldList);
+            else if (flags.table || flags.output === 'table')
+                this.printTable(output, fieldList);
+            else
+                this.log(JSON.stringify(output, null, 2));
+        }
+        catch (error) {
+            if (error instanceof ApiError) {
+                if (error.status === 404)
+                    this.error(error.message);
+                this.error(`API Error (${error.status}): ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    async runImport(flags) {
+        const context = flags.context ? getContext(flags.context) : getCurrentContext();
+        if (!context)
+            this.error(flags.context ? `Context "${flags.context}" not found. List contexts with: aderis config list` : 'No context configured. Run: aderis auth login --new');
+        if (!hasCredentials(context))
+            this.error(missingCredentialsMessage(context));
+        // Get data from file, --data, or --set flags
+        let items = [];
+        if (flags.file) {
+            const fsModule = await import('node:fs');
+            try {
+                const content = JSON.parse(fsModule.readFileSync(flags.file, 'utf-8'));
+                items = Array.isArray(content) ? content : [content];
+            }
+            catch {
+                this.error(`Failed to read file: ${flags.file}`);
+            }
+        }
+        else if (flags.data) {
+            try {
+                const content = JSON.parse(flags.data);
+                items = Array.isArray(content) ? content : [content];
+            }
+            catch {
+                this.error('Invalid JSON in --data');
+            }
+        }
+        else if (flags.set && flags.set.length > 0) {
+            const item = {};
+            const arrayFields = new Set(ENDPOINTS['create']?.bodyArrayFields ?? []);
+            for (const pair of flags.set) {
+                const eqIndex = pair.indexOf('=');
+                if (eqIndex === -1)
+                    this.error(`Invalid --set format: ${pair}. Use: --set key=value`);
+                const key = pair.slice(0, eqIndex);
+                let value = pair.slice(eqIndex + 1);
+                try {
+                    value = JSON.parse(value);
+                }
+                catch { /* keep as string */ }
+                const isArrayField = !key.includes('.') && arrayFields.has(key);
+                if (isArrayField && !Array.isArray(value)) {
+                    if (typeof value === 'string') {
+                        value = value.split(',').map(v => v.trim()).filter(v => v.length > 0);
+                    }
+                    else if (value !== undefined && value !== null) {
+                        value = [value];
+                    }
+                }
+                const keys = key.split('.');
+                if (keys.some(k => k === '__proto__' || k === 'constructor' || k === 'prototype')) {
+                    this.error(`Invalid --set key: ${key}`);
+                }
+                let obj = item;
+                for (let i = 0; i < keys.length - 1; i++) {
+                    if (!(keys[i] in obj))
+                        obj[keys[i]] = {};
+                    obj = obj[keys[i]];
+                }
+                obj[keys[keys.length - 1]] = value;
+            }
+            items = [item];
+        }
+        else {
+            this.error('Import requires --file, --data, or --set flags');
+        }
+        const createEndpoint = ENDPOINTS['create'];
+        const updateEndpoint = ENDPOINTS['update'];
+        if (!createEndpoint || !updateEndpoint) {
+            this.error('Import requires both create and update endpoints');
+        }
+        // Helper to extract identifier from item (id, code, or xxxCode)
+        const getItemIdentifier = (item) => {
+            if (item.id)
+                return String(item.id);
+            if (item.code)
+                return String(item.code);
+            // Look for xxxCode fields (e.g., ledgerCode, accountCode)
+            for (const key of Object.keys(item)) {
+                if (key.endsWith('Code') && item[key])
+                    return String(item[key]);
+            }
+            // Look for name as fallback
+            if (item.name)
+                return String(item.name).slice(0, 30);
+            return '';
+        };
+        const results = [];
+        // Stream output row-by-row so progress is visible during long imports.
+        // Pre-compute the identifier column width from the input items so the
+        // table stays aligned without buffering all rows.
+        // When stdout is piped (IDE terminals, tee, CI), Node switches to async-buffered
+        // mode and rows accumulate in the pipe buffer until it fills. Force blocking
+        // mode so each \n-terminated write flushes immediately.
+        const stdoutHandle = process.stdout._handle;
+        if (stdoutHandle?.setBlocking)
+            stdoutHandle.setBlocking(true);
+        const outputFormat = flags.output || 'table';
+        const useCsv = outputFormat === 'csv' || Boolean(flags.csv);
+        const useJson = outputFormat === 'json';
+        const statusWidth = 8;
+        const identifierWidth = Math.max(10, ...items.map(i => getItemIdentifier(i).length));
+        if (useCsv) {
+            this.log('status,identifier,id,error');
+        }
+        else if (!useJson) {
+            this.log(`${'status'.padEnd(statusWidth)}  ${'identifier'.padEnd(identifierWidth)}  error`);
+            this.log(`${'-'.repeat(statusWidth)}  ${'-'.repeat(identifierWidth)}  ${'-'.repeat(50)}`);
+        }
+        const emitRow = (r) => {
+            if (useJson)
+                return;
+            if (useCsv) {
+                const err = (r.error || '').replace(/"/g, '""');
+                this.log(`${r.status},${r.identifier || ''},${r.id || ''},"${err}"`);
+            }
+            else {
+                this.log(`${r.status.padEnd(statusWidth)}  ${(r.identifier || '').padEnd(identifierWidth)}  ${r.error || ''}`);
+            }
+        };
+        // Server-managed fields the API rejects in create/update bodies. Stripped
+        // before every request so re-importing a previously-exported payload Just Works.
+        const STRIP_FIELDS = new Set(['id', '_type', 'tenantId', 'createdAt', 'updatedAt', 'createdBy', 'updatedBy']);
+        const stripServerFields = (item) => {
+            const out = {};
+            for (const [k, v] of Object.entries(item)) {
+                if (!STRIP_FIELDS.has(k))
+                    out[k] = v;
+            }
+            return out;
+        };
+        const processItem = async (item) => {
+            const identifier = getItemIdentifier(item);
+            const body = stripServerFields(item);
+            // If the payload carries an id (e.g. re-importing an export), PATCH directly.
+            // Fall through to POST only on 404 (so a missing record still gets created).
+            const itemId = typeof item.id === 'string' ? item.id : undefined;
+            if (itemId) {
+                try {
+                    const updatePath = updateEndpoint.path.replace('{id}', itemId);
+                    await apiRequest('PATCH', updatePath, {
+                        data: body,
+                        contextName: flags.context,
+                    });
+                    return { status: 'updated', id: itemId, identifier };
+                }
+                catch (error) {
+                    if (!(error instanceof ApiError && error.status === 404)) {
+                        const msg = error instanceof ApiError ? `(${error.status}) ${error.message}` : String(error);
+                        return { status: 'error', id: itemId, identifier, error: msg };
+                    }
+                    // 404 → record gone, try create below
+                }
+            }
+            try {
+                const response = await apiRequest('POST', createEndpoint.path, {
+                    data: body,
+                    contextName: flags.context,
+                });
+                const id = response.data?.id;
+                return { status: 'created', id: id ? String(id) : undefined, identifier };
+            }
+            catch (error) {
+                if (error instanceof ApiError && error.status === 409) {
+                    const errorData = error.data;
+                    const existingId = errorData?.existingId;
+                    if (existingId) {
+                        try {
+                            const updatePath = updateEndpoint.path.replace('{id}', existingId);
+                            await apiRequest('PATCH', updatePath, {
+                                data: body,
+                                contextName: flags.context,
+                            });
+                            return { status: 'updated', id: existingId, identifier };
+                        }
+                        catch (updateError) {
+                            const msg = updateError instanceof ApiError ? updateError.message : String(updateError);
+                            return { status: 'error', id: existingId, identifier, error: `Update failed: ${msg}` };
+                        }
+                    }
+                    return { status: 'error', identifier, error: 'Conflict but no existingId returned' };
+                }
+                const msg = error instanceof ApiError ? `(${error.status}) ${error.message}` : String(error);
+                return { status: 'error', identifier, error: msg };
+            }
+        };
+        // Worker pool: keep N requests in flight at all times. Rows are emitted as
+        // each request resolves (so output order may differ from input order). The
+        // summary at the end remains accurate regardless.
+        const concurrency = 4;
+        const queue = [...items];
+        await Promise.all(Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
+            for (;;) {
+                const item = queue.shift();
+                if (!item)
+                    return;
+                const r = await processItem(item);
+                results.push(r);
+                emitRow(r);
+            }
+        }));
+        // Summary counts
+        const created = results.filter(r => r.status === 'created').length;
+        const updated = results.filter(r => r.status === 'updated').length;
+        const errors = results.filter(r => r.status === 'error');
+        if (useJson) {
+            this.log(JSON.stringify(results, null, 2));
+        }
+        // Always show summary at the end
+        this.log('');
+        this.log(`Summary: ${created} created, ${updated} updated, ${errors.length} failed`);
+    }
+    async runExport(flags) {
+        const context = flags.context ? getContext(flags.context) : getCurrentContext();
+        if (!context)
+            this.error(flags.context ? `Context "${flags.context}" not found. List contexts with: aderis config list` : 'No context configured. Run: aderis auth login --new');
+        if (!hasCredentials(context))
+            this.error(missingCredentialsMessage(context));
+        const listEndpoint = ENDPOINTS['list'];
+        if (!listEndpoint)
+            this.error('Export requires a list endpoint');
+        const allItems = [];
+        let page = 1;
+        const limit = 100;
+        let hasMore = true;
+        // Build base query params
+        const baseParams = {};
+        if (flags.search)
+            baseParams.search = flags.search;
+        if (flags['sort-by'])
+            baseParams.sortBy = normalizeSortBy(flags['sort-by']);
+        if (flags.include)
+            baseParams.include = flags.include;
+        if (flags.fields)
+            baseParams.fields = flags.fields;
+        if (flags.query) {
+            try {
+                Object.assign(baseParams, JSON.parse(flags.query));
+            }
+            catch {
+                this.error('Invalid JSON in --query');
+            }
+        }
+        // Parse --filter flags (auto-prepend $eq: if no operator specified)
+        if (flags.filter && flags.filter.length > 0) {
+            for (const f of flags.filter) {
+                const eqIndex = f.indexOf('=');
+                if (eqIndex === -1)
+                    this.error(`Invalid --filter format: ${f}. Use: --filter key=value`);
+                const key = f.slice(0, eqIndex);
+                const value = this.parseFilterValue(f.slice(eqIndex + 1));
+                const filterKey = `filter.${key}`;
+                if (filterKey in baseParams) {
+                    const existing = baseParams[filterKey];
+                    baseParams[filterKey] = Array.isArray(existing) ? [...existing, value] : [existing, value];
+                }
+                else {
+                    baseParams[filterKey] = value;
+                }
+            }
+        }
+        // Fetch all pages
+        process.stderr.write('Exporting...');
+        while (hasMore) {
+            const params = { ...baseParams, page, limit };
+            const response = await apiRequest('GET', listEndpoint.path, {
+                params,
+                contextName: flags.context,
+            });
+            let items = [];
+            const data = response.data;
+            // Handle paginated response format
+            if (data && typeof data === 'object' && 'data' in data && Array.isArray(data.data)) {
+                items = data.data;
+            }
+            else if (Array.isArray(response.data)) {
+                items = response.data;
+            }
+            allItems.push(...items);
+            process.stderr.write(` ${allItems.length}`);
+            // Check if there are more pages
+            if (items.length < limit) {
+                hasMore = false;
+            }
+            else {
+                page++;
+            }
+        }
+        process.stderr.write(' done\n');
+        let output = allItems;
+        // Sanitize output if requested
+        if (flags.sanitize) {
+            output = this.sanitizeOutput(output);
+        }
+        // Output in requested format
+        const fieldList = flags.fields ? flags.fields.split(',').map(f => f.trim()) : undefined;
+        if (flags.csv || flags.output === 'csv') {
+            this.printCsv(output, fieldList);
+        }
+        else {
+            this.log(JSON.stringify(output, null, 2));
+        }
+    }
+    async runCamt053Import(flags) {
+        const context = flags.context ? getContext(flags.context) : getCurrentContext();
+        if (!context)
+            this.error(flags.context ? `Context "${flags.context}" not found. List contexts with: aderis config list` : 'No context configured. Run: aderis auth login --new');
+        if (!hasCredentials(context))
+            this.error(missingCredentialsMessage(context));
+        if (!flags.file) {
+            this.error('CAMT.053 import requires --file (-f) flag with path to XML file');
+        }
+        const fsModule = await import('node:fs');
+        let xmlContent;
+        try {
+            xmlContent = fsModule.readFileSync(flags.file, 'utf-8');
+        }
+        catch {
+            this.error(`Failed to read file: ${flags.file}`);
+        }
+        const endpoint = ENDPOINTS['import-camt053'];
+        try {
+            const response = await apiRequest(endpoint.method, endpoint.path, {
+                data: xmlContent,
+                contextName: flags.context,
+                contentType: 'application/xml',
+            });
+            // Extract transactions array and counts from response
+            let transactions = [];
+            let imported = 0;
+            let skipped = 0;
+            if (response.data && typeof response.data === 'object') {
+                const data = response.data;
+                if ('data' in data && Array.isArray(data.data)) {
+                    transactions = data.data;
+                }
+                else if ('transactions' in data && Array.isArray(data.transactions)) {
+                    transactions = data.transactions;
+                }
+                else if (Array.isArray(response.data)) {
+                    transactions = response.data;
+                }
+                if (typeof data.imported === 'number')
+                    imported = data.imported;
+                if (typeof data.skipped === 'number')
+                    skipped = data.skipped;
+            }
+            else if (Array.isArray(response.data)) {
+                transactions = response.data;
+            }
+            if (imported === 0 && skipped === 0 && transactions.length > 0) {
+                for (const tx of transactions) {
+                    const t = tx;
+                    if (t.status === 'skipped' || t.skipped === true) {
+                        skipped++;
+                    }
+                    else {
+                        imported++;
+                    }
+                }
+                if (imported === 0 && skipped === 0) {
+                    imported = transactions.length;
+                }
+            }
+            let output = transactions;
+            if (flags.sanitize) {
+                output = this.sanitizeOutput(transactions);
+            }
+            const fieldList = flags.fields ? flags.fields.split(',').map(f => f.trim()) : undefined;
+            if (flags.csv || flags.output === 'csv') {
+                this.printCsv(output, fieldList);
+            }
+            else if (flags.table || flags.output === 'table') {
+                this.printTable(output, fieldList);
+            }
+            else {
+                this.log(JSON.stringify(output, null, 2));
+            }
+            this.log('');
+            this.log(`Summary: ${imported} imported, ${skipped} skipped`);
+        }
+        catch (error) {
+            if (error instanceof ApiError) {
+                if (error.status === 404)
+                    this.error(error.message);
+                this.error(`API Error (${error.status}): ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    async runNestedImport(suffix, parentId, flags) {
+        if (!parentId) {
+            this.error(`Missing required argument: id. Usage: aderis async-jobs import-${suffix} <parent-id> --file data.json`);
+        }
+        const context = flags.context ? getContext(flags.context) : getCurrentContext();
+        if (!context)
+            this.error(flags.context ? `Context "${flags.context}" not found. List contexts with: aderis config list` : 'No context configured. Run: aderis auth login --new');
+        if (!hasCredentials(context))
+            this.error(missingCredentialsMessage(context));
+        // Get data from file, --data, or --set flags
+        let items = [];
+        if (flags.file) {
+            const fsModule = await import('node:fs');
+            try {
+                const content = JSON.parse(fsModule.readFileSync(flags.file, 'utf-8'));
+                items = Array.isArray(content) ? content : [content];
+            }
+            catch {
+                this.error(`Failed to read file: ${flags.file}`);
+            }
+        }
+        else if (flags.data) {
+            try {
+                const content = JSON.parse(flags.data);
+                items = Array.isArray(content) ? content : [content];
+            }
+            catch {
+                this.error('Invalid JSON in --data');
+            }
+        }
+        else if (flags.set && flags.set.length > 0) {
+            const item = {};
+            const arrayFields = new Set(ENDPOINTS[`create-${suffix}`]?.bodyArrayFields ?? []);
+            for (const pair of flags.set) {
+                const eqIndex = pair.indexOf('=');
+                if (eqIndex === -1)
+                    this.error(`Invalid --set format: ${pair}. Use: --set key=value`);
+                const key = pair.slice(0, eqIndex);
+                let value = pair.slice(eqIndex + 1);
+                try {
+                    value = JSON.parse(value);
+                }
+                catch { /* keep as string */ }
+                const isArrayField = !key.includes('.') && arrayFields.has(key);
+                if (isArrayField && !Array.isArray(value)) {
+                    if (typeof value === 'string') {
+                        value = value.split(',').map(v => v.trim()).filter(v => v.length > 0);
+                    }
+                    else if (value !== undefined && value !== null) {
+                        value = [value];
+                    }
+                }
+                const keys = key.split('.');
+                if (keys.some(k => k === '__proto__' || k === 'constructor' || k === 'prototype')) {
+                    this.error(`Invalid --set key: ${key}`);
+                }
+                let obj = item;
+                for (let i = 0; i < keys.length - 1; i++) {
+                    if (!(keys[i] in obj))
+                        obj[keys[i]] = {};
+                    obj = obj[keys[i]];
+                }
+                obj[keys[keys.length - 1]] = value;
+            }
+            items = [item];
+        }
+        else {
+            this.error(`Import requires --file, --data, or --set flags`);
+        }
+        const createEndpoint = ENDPOINTS[`create-${suffix}`];
+        const updateEndpoint = ENDPOINTS[`update-${suffix}`];
+        if (!createEndpoint || !updateEndpoint) {
+            this.error(`Import requires both create-${suffix} and update-${suffix} endpoints`);
+        }
+        // Build the base path with parent ID (first path param)
+        const firstParam = createEndpoint.pathParams[0];
+        const basePath = createEndpoint.path.replace(`{${firstParam}}`, parentId);
+        // Helper to extract identifier from item
+        const getItemIdentifier = (item) => {
+            if (item.id)
+                return String(item.id);
+            if (item.itemId)
+                return String(item.itemId);
+            if (item.code)
+                return String(item.code);
+            for (const key of Object.keys(item)) {
+                if (key.endsWith('Id') && item[key])
+                    return String(item[key]);
+                if (key.endsWith('Code') && item[key])
+                    return String(item[key]);
+            }
+            return '';
+        };
+        const results = [];
+        const stdoutHandle = process.stdout._handle;
+        if (stdoutHandle?.setBlocking)
+            stdoutHandle.setBlocking(true);
+        const outputFormat = flags.output || 'table';
+        const useCsv = outputFormat === 'csv' || Boolean(flags.csv);
+        const useJson = outputFormat === 'json';
+        const statusWidth = 8;
+        const identifierWidth = Math.max(10, ...items.map(i => getItemIdentifier(i).length));
+        if (useCsv) {
+            this.log('status,identifier,id,error');
+        }
+        else if (!useJson) {
+            this.log(`${'status'.padEnd(statusWidth)}  ${'identifier'.padEnd(identifierWidth)}  error`);
+            this.log(`${'-'.repeat(statusWidth)}  ${'-'.repeat(identifierWidth)}  ${'-'.repeat(50)}`);
+        }
+        const emitRow = (r) => {
+            if (useJson)
+                return;
+            if (useCsv) {
+                const err = (r.error || '').replace(/"/g, '""');
+                this.log(`${r.status},${r.identifier || ''},${r.id || ''},"${err}"`);
+            }
+            else {
+                this.log(`${r.status.padEnd(statusWidth)}  ${(r.identifier || '').padEnd(identifierWidth)}  ${r.error || ''}`);
+            }
+        };
+        const STRIP_FIELDS = new Set(['id', '_type', 'tenantId', 'createdAt', 'updatedAt', 'createdBy', 'updatedBy']);
+        const stripServerFields = (item) => {
+            const out = {};
+            for (const [k, v] of Object.entries(item)) {
+                if (!STRIP_FIELDS.has(k))
+                    out[k] = v;
+            }
+            return out;
+        };
+        const buildUpdatePath = (existingId) => {
+            const firstUpdateParam = updateEndpoint.pathParams[0];
+            const nestedIdParam = updateEndpoint.pathParams.find((p, i) => i > 0);
+            let updatePath = updateEndpoint.path.replace(`{${firstUpdateParam}}`, parentId);
+            if (nestedIdParam) {
+                updatePath = updatePath.replace(`{${nestedIdParam}}`, existingId);
+            }
+            return updatePath;
+        };
+        const processItem = async (item) => {
+            const identifier = getItemIdentifier(item);
+            const body = stripServerFields(item);
+            const itemId = typeof item.id === 'string' ? item.id : undefined;
+            if (itemId) {
+                try {
+                    await apiRequest('PATCH', buildUpdatePath(itemId), {
+                        data: body,
+                        contextName: flags.context,
+                    });
+                    return { status: 'updated', id: itemId, identifier };
+                }
+                catch (error) {
+                    if (!(error instanceof ApiError && error.status === 404)) {
+                        const msg = error instanceof ApiError ? `(${error.status}) ${error.message}` : String(error);
+                        return { status: 'error', id: itemId, identifier, error: msg };
+                    }
+                    // 404 → fall through and try create
+                }
+            }
+            try {
+                const response = await apiRequest('POST', basePath, {
+                    data: body,
+                    contextName: flags.context,
+                });
+                const id = response.data?.id;
+                return { status: 'created', id: id ? String(id) : undefined, identifier };
+            }
+            catch (error) {
+                if (error instanceof ApiError && error.status === 409) {
+                    const errorData = error.data;
+                    const existingId = errorData?.existingId || item.id;
+                    if (existingId) {
+                        try {
+                            await apiRequest('PATCH', buildUpdatePath(existingId), {
+                                data: body,
+                                contextName: flags.context,
+                            });
+                            return { status: 'updated', id: existingId, identifier };
+                        }
+                        catch (updateError) {
+                            const msg = updateError instanceof ApiError ? updateError.message : String(updateError);
+                            return { status: 'error', id: existingId, identifier, error: `Update failed: ${msg}` };
+                        }
+                    }
+                    return { status: 'error', identifier, error: 'Conflict but no existingId returned' };
+                }
+                const msg = error instanceof ApiError ? `(${error.status}) ${error.message}` : String(error);
+                return { status: 'error', identifier, error: msg };
+            }
+        };
+        // Worker pool: 4 requests in flight at a time. Rows are emitted as each
+        // request resolves so output order may differ from input order.
+        const concurrency = 4;
+        const queue = [...items];
+        await Promise.all(Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
+            for (;;) {
+                const item = queue.shift();
+                if (!item)
+                    return;
+                const r = await processItem(item);
+                results.push(r);
+                emitRow(r);
+            }
+        }));
+        // Summary counts
+        const created = results.filter(r => r.status === 'created').length;
+        const updated = results.filter(r => r.status === 'updated').length;
+        const errors = results.filter(r => r.status === 'error');
+        if (useJson) {
+            this.log(JSON.stringify(results, null, 2));
+        }
+        this.log('');
+        this.log(`Summary: ${created} created, ${updated} updated, ${errors.length} failed`);
+    }
+    parseFilterValue(value) {
+        // Recognises the nestjs-paginate operator set (with or without the leading $)
+        // and recursively unwraps chained operators like 'not:null' -> '$not:$null'
+        // or 'not:like:John' -> '$not:$like:John'. Falls back to '$eq:<value>' when
+        // no operator prefix is present.
+        const opRe = /^\$?(and|or|not|eq|gt|gte|in|null|lt|lte|btw|ne|ilike|like|sw|contains)(?::|$)/;
+        const m = value.match(opRe);
+        if (!m)
+            return `\$eq:${value}`;
+        const op = m[1];
+        const rest = value.slice(m[0].length);
+        if (rest === '')
+            return `\$${op}`;
+        return opRe.test(rest) ? `\$${op}:${this.parseFilterValue(rest)}` : `\$${op}:${rest}`;
+    }
+    sanitizeOutput(data) {
+        const auditFields = ['_type', 'tenantId', 'createdAt', 'updatedAt', 'createdBy', 'updatedBy'];
+        const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+        const sanitize = (obj, parentUuids = new Set()) => {
+            if (obj === null || obj === undefined)
+                return undefined;
+            if (Array.isArray(obj)) {
+                const result = obj.map(item => sanitize(item, new Set(parentUuids))).filter(item => item !== undefined);
+                return result.length > 0 ? result : undefined;
+            }
+            if (typeof obj === 'object') {
+                const input = obj;
+                // Use a Map to avoid any prototype-pollution risk on the result object
+                const collected = new Map();
+                // Collect UUIDs from this level to pass to children
+                const currentUuids = new Set(parentUuids);
+                for (const [, value] of Object.entries(input)) {
+                    if (typeof value === 'string' && uuidRegex.test(value)) {
+                        currentUuids.add(value);
+                    }
+                }
+                for (const [key, value] of Object.entries(input)) {
+                    // Skip prototype-pollution keys
+                    if (key === '__proto__' || key === 'constructor' || key === 'prototype')
+                        continue;
+                    // Skip audit fields
+                    if (auditFields.includes(key))
+                        continue;
+                    // Skip null/undefined values
+                    if (value === null || value === undefined)
+                        continue;
+                    // Skip UUID values that exist in parent
+                    if (typeof value === 'string' && uuidRegex.test(value) && parentUuids.has(value))
+                        continue;
+                    // Recursively sanitize nested objects/arrays
+                    const sanitized = sanitize(value, currentUuids);
+                    if (sanitized !== undefined) {
+                        collected.set(key, sanitized);
+                    }
+                }
+                if (collected.size === 0)
+                    return undefined;
+                return Object.fromEntries(collected);
+            }
+            return obj;
+        };
+        return sanitize(data) ?? (Array.isArray(data) ? [] : {});
+    }
+    getColumns(data, fields, flatten = false) {
+        const items = Array.isArray(data) ? data : [data];
+        if (items.length === 0)
+            return { cols: [], items: [] };
+        const first = items[0];
+        const hiddenFields = ['tenantId', '_type'];
+        if (fields) {
+            return { cols: fields, items: items };
+        }
+        // Recursively collect all column paths, flattening objects (but not arrays)
+        const collectPaths = (obj, prefix = '') => {
+            const paths = [];
+            for (const key of Object.keys(obj)) {
+                const fullKey = prefix ? `${prefix}.${key}` : key;
+                if (hiddenFields.includes(key))
+                    continue;
+                const val = obj[key];
+                if (val !== null && typeof val === 'object' && !Array.isArray(val)) {
+                    // Flatten nested objects (but not arrays)
+                    if (flatten) {
+                        paths.push(...collectPaths(val, fullKey));
+                    }
+                    // Skip objects when not flattening
+                }
+                else if (!Array.isArray(val)) {
+                    // Include primitives (and null)
+                    paths.push(fullKey);
+                }
+                // Skip arrays entirely
+            }
+            return paths;
+        };
+        // Scan multiple items to discover all columns (handles fields absent/null in first item)
+        const cols = collectPaths(first);
+        const colSet = new Set(cols);
+        const scanCount = Math.min(items.length, 50);
+        for (let i = 1; i < scanCount; i++) {
+            for (const p of collectPaths(items[i])) {
+                if (!colSet.has(p)) {
+                    cols.push(p);
+                    colSet.add(p);
+                }
+            }
+        }
+        return { cols: flatten ? cols : cols.slice(0, 8), items: items };
+    }
+    getValue(row, col) {
+        if (!col.includes('.'))
+            return String(row[col] ?? '');
+        const parts = col.split('.');
+        // Walk the dot-path; descending through an array branches into every
+        // element so leaf values get collected from each one. Multiple leaves are
+        // joined with ';' (e.g. dunningReminders.id -> "uuid1;uuid2").
+        const walk = (o, idx) => {
+            if (idx >= parts.length)
+                return [o];
+            if (o == null)
+                return [];
+            if (Array.isArray(o))
+                return o.flatMap(item => walk(item, idx));
+            if (typeof o === 'object')
+                return walk(o[parts[idx]], idx + 1);
+            return [];
+        };
+        return walk(row, 0).filter(v => v !== undefined && v !== null).map(v => String(v)).join(';');
+    }
+    printTable(data, fields) {
+        const { cols, items } = this.getColumns(data, fields);
+        if (items.length === 0) {
+            this.log('No results');
+            return;
+        }
+        // Calculate column widths
+        const widths = cols.map(c => c.length);
+        for (const item of items) {
+            cols.forEach((col, i) => {
+                const val = this.getValue(item, col).slice(0, 40);
+                widths[i] = Math.max(widths[i], val.length);
+            });
+        }
+        // Print header
+        const header = cols.map((c, i) => c.padEnd(widths[i])).join('  ');
+        this.log(header);
+        this.log(widths.map(w => '-'.repeat(w)).join('  '));
+        // Print rows
+        for (const item of items) {
+            const row = cols.map((col, i) => {
+                const val = this.getValue(item, col).slice(0, 40);
+                return val.padEnd(widths[i]);
+            }).join('  ');
+            this.log(row);
+        }
+    }
+    printCsv(data, fields) {
+        const { cols, items } = this.getColumns(data, fields, true); // flatten=true for CSV
+        if (items.length === 0) {
+            this.log('No results');
+            return;
+        }
+        const escape = (val) => {
+            if (val.includes(',') || val.includes('"') || val.includes('\n')) {
+                return '"' + val.replace(/"/g, '""') + '"';
+            }
+            return val;
+        };
+        // Print header
+        this.log(cols.map(escape).join(','));
+        // Print rows
+        for (const item of items) {
+            const row = cols.map(col => escape(this.getValue(item, col)));
+            this.log(row.join(','));
+        }
+    }
+}