@aderis-erp/cli 1.1.2 → 1.1.4

package/dist/commands/event-mapping-rules.js

@@ -0,0 +1,1324 @@
+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';
+// 'upsert' loops create/update from the CLI, one request per record. It exists
+// only where the API has no import endpoint of its own; those keep the name
+// 'import' and are listed in SERVER_IMPORTS.
+const HAS_UPSERT = false;
+const HAS_EXPORT = false;
+const HAS_CAMT053 = false;
+const SERVER_IMPORTS = [];
+const NESTED_UPSERTS = [];
+const SUBCOMMANDS = [...["fields"], ...(HAS_UPSERT ? ['upsert'] : []), ...(HAS_EXPORT ? ['export'] : []), ...NESTED_UPSERTS.map(n => `upsert-${n}`)];
+const ENDPOINTS = {
+    'fields': { method: 'GET', path: '/v1/event-mapping-rules/fields', summary: 'List the fields an event mapping’s conditions may test', pathParams: [], hasBody: false, isMultipart: false, isBinaryResponse: false, hasBinaryVariant: false, bodyArrayFields: [] },
+};
+export default class EventMappingRules extends Command {
+    static description = 'Manage event mapping rules';
+    static examples = [];
+    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 upsert, 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' }),
+        meta: Flags.boolean({ description: 'Keep the API envelope in JSON output: data plus page, totals and sums' }),
+        'show-http-request': Flags.boolean({ description: 'Show HTTP request details (method, URL, body)' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(EventMappingRules);
+        // Bulk actions. 'import' is the API's own endpoint: one request, answered
+        // by a run that records what happened to every record. 'upsert' is the CLI
+        // looping create/update. A resource has one or the other, never both.
+        if (args.action === 'upsert') {
+            if (!HAS_UPSERT) {
+                this.error(SERVER_IMPORTS.includes('import')
+                    ? 'This resource is imported by the API. Use: aderis event-mapping-rules import --file data.json'
+                    : 'Upsert needs both a create and an update endpoint, which this resource does not have');
+            }
+            await this.runUpsert(flags);
+            return;
+        }
+        if (args.action.startsWith('upsert-')) {
+            const suffix = args.action.replace('upsert-', '');
+            if (!NESTED_UPSERTS.includes(suffix)) {
+                this.error(SERVER_IMPORTS.includes('import-' + suffix)
+                    ? `That resource is imported by the API. Use: aderis event-mapping-rules import-${suffix} <id> --file data.json`
+                    : `Unknown action: ${args.action}. Available: ${SUBCOMMANDS.join(', ')}`);
+            }
+            await this.runNestedUpsert(suffix, args.id, 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;
+        }
+        if (SERVER_IMPORTS.includes(args.action)) {
+            await this.runServerImport(args.action, args.id, flags);
+            return;
+        }
+        // 'import' used to name the CLI's create/update loop on every resource. It
+        // now names the API endpoint, which most resources do not have.
+        if (args.action === 'import' || args.action.startsWith('import-')) {
+            const suffix = args.action === 'import' ? '' : '-' + args.action.replace('import-', '');
+            const loops = args.action === 'import' ? HAS_UPSERT : NESTED_UPSERTS.includes(args.action.replace('import-', ''));
+            if (loops) {
+                this.error(`This resource has no import endpoint. Use: aderis event-mapping-rules upsert${suffix}${suffix ? ' <id>' : ''} --file data.json`);
+            }
+        }
+        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 event-mapping-rules <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 */ }
+            }
+            // A paginated answer is { data, meta, links, totals }. The records are
+            // unwrapped for output, but what the API said about the page is kept:
+            // dropping it silently let a script read one page as the whole result
+            // (AderisERP/product#61).
+            let envelope;
+            if (output && typeof output === 'object' && !Array.isArray(output) && 'data' in output && Array.isArray(output.data)) {
+                const page = output;
+                envelope = page;
+                output = page.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 (envelope)
+                this.warnShortPage(envelope, flags.limit);
+            if (flags.csv || flags.output === 'csv') {
+                this.printCsv(output, fieldList);
+            }
+            else if (flags.table || flags.output === 'table') {
+                this.printTable(output, fieldList);
+                if (envelope)
+                    this.printPageSummary(envelope);
+            }
+            else if (envelope && flags.meta) {
+                // The whole envelope, for a caller that asked for it; the default stays
+                // a bare array so existing scripts are unaffected.
+                this.log(JSON.stringify({ ...envelope, data: output }, null, 2));
+            }
+            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 runUpsert(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('Upsert requires --file, --data, or --set flags');
+        }
+        const createEndpoint = ENDPOINTS['create'];
+        const updateEndpoint = ENDPOINTS['update'];
+        if (!createEndpoint || !updateEndpoint) {
+            this.error('Upsert 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`);
+    }
+    /**
+     * The API's own import: the whole array goes up in one request and comes
+     * back as an import run, which records what happened to every record. A bad
+     * record lands in errorLog and the rest are still applied, and the run stays
+     * readable afterwards with: aderis imports get <id>.
+     */
+    async runServerImport(action, parentId, flags) {
+        const endpoint = ENDPOINTS[action];
+        if (!endpoint)
+            this.error(`Unknown action: ${action}. Available: ${SUBCOMMANDS.join(', ')}`);
+        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));
+        let apiPath = endpoint.path;
+        if (endpoint.pathParams.length > 0) {
+            if (!parentId)
+                this.error(`Missing required argument: id. Usage: aderis event-mapping-rules ${action} <parent-id> --file data.json`);
+            apiPath = apiPath.replace(`{${endpoint.pathParams[0]}}`, parentId);
+        }
+        // The endpoint takes an array. A single object is wrapped, so importing
+        // one record reads the same as importing many.
+        let records = [];
+        if (flags.file) {
+            const fsModule = await import('node:fs');
+            try {
+                const content = JSON.parse(fsModule.readFileSync(flags.file, 'utf-8'));
+                records = 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);
+                records = Array.isArray(content) ? content : [content];
+            }
+            catch {
+                this.error('Invalid JSON in --data');
+            }
+        }
+        else {
+            this.error('Import requires --file or --data holding a JSON array of records');
+        }
+        if (records.length === 0)
+            this.error('Nothing to import: the input is an empty array');
+        const params = { format: 'json' };
+        if (flags.mode)
+            params.mode = flags.mode;
+        if (flags.reference)
+            params.reference = flags.reference;
+        if (flags.async)
+            params.async = true;
+        const headers = {};
+        if (flags['idempotency-key'])
+            headers['Idempotency-Key'] = flags['idempotency-key'];
+        if (flags['show-http-request']) {
+            const baseUrls = getBaseUrls(context.environment);
+            const queryString = '?' + Object.entries(params).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`).join('&');
+            process.stderr.write(`\n${endpoint.method.toUpperCase()} ${baseUrls.api}${apiPath}${queryString}\n`);
+            process.stderr.write(`Body: [${records.length} record${records.length === 1 ? '' : 's'}]\n\n`);
+        }
+        try {
+            const response = await apiRequest(endpoint.method, apiPath, {
+                contextName: flags.context,
+                data: records,
+                headers,
+                params,
+            });
+            this.printImportRun(response.data, flags);
+        }
+        catch (error) {
+            if (error instanceof ApiError) {
+                this.error(`API Error (${error.status}): ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    /** Renders an import run: its counts, then whatever the server refused. */
+    printImportRun(run, flags) {
+        if (flags.output === 'json') {
+            this.log(JSON.stringify(run, null, 2));
+            return;
+        }
+        const record = (run ?? {});
+        const count = (key) => (typeof record[key] === 'number' ? record[key] : 0);
+        const id = record.id ? String(record.id) : '';
+        this.log(`Import ${id} - ${String(record.status ?? 'UNKNOWN')}${record.async ? ' (background)' : ''}`);
+        this.log(`  ${count('inputSize')} submitted, ${count('createdCount')} created, ${count('updatedCount')} updated, ${count('unchangedCount')} unchanged`);
+        if (count('errorCount') > 0)
+            this.log(`  ${count('errorCount')} not applied: ${count('refusedCount')} refused, ${count('failedCount')} failed`);
+        if (count('warningCount') > 0)
+            this.log(`  ${count('warningCount')} applied with a warning`);
+        // errorLog is keyed by the record's identifier, then by field name.
+        const errorLog = record.errorLog;
+        if (errorLog && Object.keys(errorLog).length > 0) {
+            this.log('');
+            for (const [key, fields] of Object.entries(errorLog)) {
+                for (const [field, messages] of Object.entries(fields ?? {})) {
+                    for (const message of messages ?? [])
+                        this.log(`  ${key}  ${field}: ${message}`);
+                }
+            }
+        }
+        if (record.async && id) {
+            this.log('');
+            this.log(`Follow it with: aderis imports get ${id}`);
+        }
+    }
+    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 runNestedUpsert(suffix, parentId, flags) {
+        if (!parentId) {
+            this.error(`Missing required argument: id. Usage: aderis event-mapping-rules upsert-${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('Upsert requires --file, --data, or --set flags');
+        }
+        const createEndpoint = ENDPOINTS[`create-${suffix}`];
+        const updateEndpoint = ENDPOINTS[`update-${suffix}`];
+        if (!createEndpoint || !updateEndpoint) {
+            this.error(`Upsert 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}`;
+    }
+    /** The page line under a table: which page, how many, and any sums the API returned. */
+    printPageSummary(envelope) {
+        const meta = envelope.meta;
+        if (meta && typeof meta.currentPage === 'number' && typeof meta.totalPages === 'number') {
+            const shown = Array.isArray(envelope.data) ? envelope.data.length : 0;
+            this.log(`
+Page ${meta.currentPage}/${meta.totalPages} — ${shown} of ${meta.totalItems ?? '?'} records`);
+        }
+        for (const total of envelope.totals ?? []) {
+            const { currency, ...sums } = total;
+            const parts = Object.entries(sums).map(([column, value]) => `${column} ${value}`).join(', ');
+            this.log(`Total ${currency ?? ''}: ${parts}`.trim());
+        }
+    }
+    /**
+     * The API caps how many records a page may hold. Asking for more and getting
+     * fewer looks like "that is everything" unless it is said out loud.
+     */
+    warnShortPage(envelope, requestedLimit) {
+        const asked = requestedLimit === undefined ? undefined : Number(requestedLimit);
+        const perPage = envelope.meta?.itemsPerPage;
+        if (asked === undefined || Number.isNaN(asked) || typeof perPage !== 'number' || perPage >= asked)
+            return;
+        const pages = envelope.meta?.totalPages;
+        const more = typeof pages === 'number' && pages > 1 ? ` Use --page, or the export action for every page.` : '';
+        process.stderr.write(`! Asked for ${asked} records per page; the API returned at most ${perPage}.${more}
+`);
+    }
+    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(','));
+        }
+    }
+}