sfmc-dataloader 1.1.0 → 2.0.0

package/README.md

@@ -24,7 +24,9 @@ Run from your mcdev project root (where `.mcdevrc.json` lives).
 mcdata export MyCred/MyBU --de MyDE_CustomerKey --format csv
 ```
 
-Writes to `./data/MyCred/MyBU/<encodedKey>+MCDATA+<timestamp>.csv` (TSV/JSON with `--format`).
+Writes to `./data/MyCred/MyBU/<encodedKey>.mcdata.<timestamp>.csv` (TSV/JSON with `--format`). Timestamps use the same filesystem-safe ISO format as before.
+
+Use **`--git`** for a stable name without a timestamp: `<encodedKey>.mcdata.csv` (useful for version control).
 
 ### Export — multiple BUs at once
 
@@ -34,49 +36,62 @@ Use `--from` (repeatable) instead of the positional argument to export the same
 mcdata export --from MyCred/Dev --from MyCred/QA --de Contact_DE --de Order_DE
 ```
 
-Creates one timestamped file per BU/DE combination:
-
-```
-./data/MyCred/Dev/Contact_DE+MCDATA+<timestamp>.csv
-./data/MyCred/Dev/Order_DE+MCDATA+<timestamp>.csv
-./data/MyCred/QA/Contact_DE+MCDATA+<timestamp>.csv
-./data/MyCred/QA/Order_DE+MCDATA+<timestamp>.csv
-```
+Creates one file per BU/DE combination using the same `.mcdata.` naming rules.
 
 ### Import — single BU
 
 ```bash
-mcdata import MyCred/MyBU --de MyDE_CustomerKey --format csv --api async --mode upsert
+mcdata import MyCred/MyBU --de MyDE_CustomerKey --format csv --mode upsert
 ```
 
+Imports use the **asynchronous** bulk row API only: `POST` for `--mode insert`, `PUT` for `--mode upsert` (same endpoint path).
+
 Resolves the latest matching export file under `./data/MyCred/MyBU/` for that DE key.
 
-Import from explicit paths (DE key is recovered from the `+MCDATA+` filename):
+Import from explicit paths (the DE key is taken from the `.mcdata.` basename):
 
 ```bash
-mcdata import MyCred/MyBU --file ./data/MyCred/MyBU/encoded%2Bkey+MCDATA+2026-04-06T12-00-00.000Z.csv
+mcdata import MyCred/MyBU --file ./data/MyCred/MyBU/encoded%2Bkey.mcdata.2026-04-06T12-00-00.000Z.csv
 ```
 
-### Import — one source BU into multiple target BUs
+#### Upsert vs insert
+
+- **Upsert** follows the platform’s usual behaviour: update when a primary key matches, otherwise insert. For Data Extensions **without** a primary key, upsert may not behave as expected; prefer **`--mode insert`** for those.
+- **Insert** always adds new rows. Running import twice with insert can create **duplicate** rows if the same file is applied again—use upsert when keys are defined and you need idempotent runs.
 
-Use `--from` (one source) and `--to` (repeatable targets) for a cross-BU import:
+### Import — one source BU into multiple target BUs (API mode)
+
+Use `--from` (one source) and `--to` (repeatable targets) for a cross-BU import where rows are fetched live from the source BU:
 
 ```bash
 mcdata import --from MyCred/Dev --to MyCred/QA --to MyCred/Prod --de Contact_DE
 ```
 
-Before the import starts you will be offered the option to export the current data from each target BU as a timestamped backup. A timestamped download file is also written to each target BU's data directory so there is a traceable record of exactly what was imported.
+Before the import starts you will be offered the option to export the current data from each target BU as a timestamped backup. A download file is also written to each target BU's data directory so there is a traceable record of exactly what was imported.
+
+### Import — local export files into multiple target BUs (file mode)
+
+Use `--to` (repeatable targets) and `--file` (repeatable file paths) to push previously exported data files to multiple BUs without connecting to a source BU. The DE customer key is derived from each filename automatically:
+
+```bash
+mcdata import --to MyCred/QA --to MyCred/Prod \
+  --file ./data/MyCred/Dev/Contact_DE.mcdata.2026-04-08T10-00-00.000Z.csv
+```
+
+Multiple files can be supplied to push several DEs in one command. Pass **`--git`** on export if you rely on stable `*.mcdata.<ext>` names for snapshots in this flow.
 
 ### Clear all rows before import
 
 **Dangerous:** removes every row in the target Data Extension(s) before uploading.
 
 Single-BU:
+
 ```bash
 mcdata import MyCred/MyBU --de MyKey --clear-before-import
 ```
 
 Cross-BU (warning lists every affected BU):
+
 ```bash
 mcdata import --from MyCred/Dev --to MyCred/QA --to MyCred/Prod \
   --de Contact_DE --clear-before-import
@@ -90,13 +105,15 @@ Interactive: type `YES` when prompted. In CI, add `--i-accept-clear-data-risk` a
 |--------|-------------|
 | `-p, --project` | Project root (default: cwd) |
 | `--format` | `csv` (default), `tsv`, or `json` |
-| `--api` | `async` (default) or `sync` |
-| `--mode` | `upsert` (default), `insert` and `update` require `--api sync` |
-| `--from <cred>/<bu>` | Export: source BU (repeatable). Import: single source BU (use with `--to`) |
-| `--to <cred>/<bu>` | Import: target BU (repeatable for multiple targets) |
+| `--git` | Stable export filenames: `<key>.mcdata.<ext>` (no timestamp segment) |
+| `--mode` | `upsert` (default) or `insert` — async bulk REST API only |
+| `--from <cred>/<bu>` | Export: source BU (repeatable). Import API mode: single source BU (use with `--to` and `--de`) |
+| `--to <cred>/<bu>` | Import: target BU (repeatable). API mode: use with `--from`/`--de`. File mode: use with `--file` (no `--from` needed) |
 | `--clear-before-import` | SOAP `ClearData` before REST import |
 | `--i-accept-clear-data-risk` | Non-interactive consent for clear |
 
+Log lines use paths **relative** to the project root (POSIX-style, `./…`) and include **row counts** where applicable.
+
 ## License
 
 MIT — Author: Jörn Berkefeld

package/lib/cli.mjs

@@ -8,7 +8,7 @@ import {
     resolveCredentialAndMid,
     buildSdkAuthObject,
 } from './config.mjs';
-import { dataDirectoryForBu } from './paths.mjs';
+import { dataDirectoryForBu, projectRelativePosix } from './paths.mjs';
 import { exportDataExtensionToFile } from './export-de.mjs';
 import { findImportCandidates, pickLatestByMtime } from './file-resolve.mjs';
 import { parseExportBasename } from './filename.mjs';
@@ -26,28 +26,30 @@ Usage:
   mcdata export --from <cred>/<bu> [--from <cred>/<bu> ...] --de <key> [--de <key> ...] [options]
   mcdata import <credential>/<bu> (--de <key> ... | --file <path> ...) [options]
   mcdata import --from <cred>/<bu> --to <cred>/<bu> [--to <cred>/<bu> ...] --de <key> ... [options]
+  mcdata import --to <cred>/<bu> [--to <cred>/<bu> ...] --file <path> [--file <path> ...] [options]
 
 Options:
   -p, --project <dir>     mcdev project root (default: cwd)
   --format <csv|tsv|json> File format (default: csv)
   --json-pretty           Pretty-print JSON on export
+  --git                   Stable filenames: <key>.mcdata.<ext> (no timestamp)
 
 Import options:
-  --api <async|sync>      REST row API family (default: async)
-  --mode <upsert|insert|update>  (default: upsert; insert/update require --api sync)
+  --mode <upsert|insert>  Row write mode (default: upsert; async REST bulk API)
   --clear-before-import   SOAP ClearData before import (destructive; see below)
   --i-accept-clear-data-risk  Non-interactive acknowledgement for --clear-before-import
 
 Multi-BU options:
   --from <cred>/<bu>      Export: source BU (repeatable for multiple sources)
-                          Import: single source BU (use with --to)
+                          Import (API mode): single source BU (use with --to and --de)
   --to <cred>/<bu>        Import: target BU (repeatable for multiple targets)
+                          Import (file mode): use with --file only (no --from needed)
 
 Notes:
-  Exports are written under ./data/<credential>/<bu>/ with "+MCDATA+" in the filename.
+  Exports are written under ./data/<credential>/<bu>/ using ".mcdata." in the filename.
   Import with --de resolves the latest matching file in that folder (by mtime).
-  Import with --file parses the DE key from the basename (+MCDATA+ prefix).
-  Cross-BU import stores a timestamped download file in each target BU's data directory.
+  Import with --file parses the DE key from the basename (.mcdata. format).
+  Cross-BU import stores a download file in each target BU's data directory.
 
 Clear data warning:
   --clear-before-import deletes ALL existing rows in the target DE(s) before upload.
@@ -72,10 +74,10 @@ export async function main(argv) {
                 format: { type: 'string' },
                 de: { type: 'string', multiple: true },
                 file: { type: 'string', multiple: true },
-                api: { type: 'string' },
-                mode: { type: 'string' },
                 from: { type: 'string', multiple: true },
                 to: { type: 'string', multiple: true },
+                git: { type: 'boolean', default: false },
+                mode: { type: 'string' },
                 'clear-before-import': { type: 'boolean', default: false },
                 'i-accept-clear-data-risk': { type: 'boolean', default: false },
                 'json-pretty': { type: 'boolean', default: false },
@@ -109,6 +111,7 @@ export async function main(argv) {
         return 1;
     }
 
+    const useGit = values.git === true;
     const fromFlags = values.from ?? [];
     const toFlags = values.to ?? [];
     const hasFrom = fromFlags.length > 0;
@@ -140,7 +143,6 @@ export async function main(argv) {
         }
 
         if (hasFrom) {
-            // Multi-BU export
             let sources;
             try {
                 sources = fromFlags.map(parseCredBu);
@@ -157,46 +159,78 @@ export async function main(argv) {
                 deKeys: des,
                 format: /** @type {'csv'|'tsv'|'json'} */ (fmt),
                 jsonPretty: values['json-pretty'],
+                useGit,
             });
             return 0;
         }
 
-        // Single-BU export (original behavior)
         const { credential, bu } = parseCredBu(credBuRaw);
         const { mcdevrc, mcdevAuth } = loadMcdevProject(projectRoot);
         const { mid, authCred } = resolveCredentialAndMid(mcdevrc, mcdevAuth, credential, bu);
         const sdk = new SDK(buildSdkAuthObject(authCred, mid), { requestAttempts: 3 });
         for (const deKey of des) {
-            const out = await exportDataExtensionToFile(sdk, {
+            const { path: out, rowCount } = await exportDataExtensionToFile(sdk, {
                 projectRoot,
                 credentialName: credential,
                 buName: bu,
                 deKey,
                 format: /** @type {'csv'|'tsv'|'json'} */ (fmt),
                 jsonPretty: values['json-pretty'],
+                useGit,
             });
-            console.error(`Exported: ${out}`);
+            const rel = projectRelativePosix(projectRoot, out);
+            console.error(`Exported: ${rel} (${rowCount} rows)`);
         }
         return 0;
     }
 
     // ── import ──────────────────────────────────────────────────────────────
     if (sub === 'import') {
-        const api = values.api ?? 'async';
         const mode = values.mode ?? 'upsert';
-        if (!['async', 'sync'].includes(api)) {
-            console.error(`Invalid --api: ${api}`);
-            return 1;
-        }
-        if (!['upsert', 'insert', 'update'].includes(mode)) {
-            console.error(`Invalid --mode: ${mode}`);
+        if (!['upsert', 'insert'].includes(mode)) {
+            console.error(`Invalid --mode: ${mode} (use upsert or insert)`);
             return 1;
         }
 
         const clear = values['clear-before-import'];
         const acceptRisk = values['i-accept-clear-data-risk'];
 
-        // ── Cross-BU import: --from + --to ──────────────────────────────────
+        // ── File-to-multi-BU import: --to + --file (no --from) ─────────────
+        if (hasTo && !hasFrom && values.file?.length > 0) {
+            if (hasPositional) {
+                console.error('Cannot mix a positional <credential>/<bu> with --to/--file. Use one or the other.');
+                return 1;
+            }
+            if (values.de?.length > 0) {
+                console.error('Cannot mix --de with --file in multi-target import. Use --file only.');
+                return 1;
+            }
+            const filePaths = values.file;
+            let targets;
+            try {
+                targets = toFlags.map(parseCredBu);
+            } catch (e) {
+                console.error(e.message);
+                return 1;
+            }
+            const { mcdevrc, mcdevAuth } = loadMcdevProject(projectRoot);
+            await crossBuImport({
+                projectRoot,
+                mcdevrc,
+                mcdevAuth,
+                filePaths,
+                targets,
+                format: /** @type {'csv'|'tsv'|'json'} */ (fmt),
+                mode: /** @type {'upsert'|'insert'} */ (mode),
+                clearBeforeImport: clear,
+                acceptRiskFlag: acceptRisk,
+                isTTY: process.stdin.isTTY === true,
+                useGit,
+            });
+            return 0;
+        }
+
+        // ── Cross-BU import (API mode): --from + --to + --de ────────────────
         if (hasFrom || hasTo) {
             if (hasPositional) {
                 console.error('Cannot mix a positional <credential>/<bu> with --from/--to. Use one or the other.');
@@ -215,7 +249,7 @@ export async function main(argv) {
                 return 1;
             }
             if (values.file?.length > 0) {
-                console.error('--file cannot be combined with --from/--to. Use --de instead.');
+                console.error('--file cannot be combined with --from/--to/--de. For file-based multi-target import use --to + --file (without --from).');
                 return 1;
             }
             const deKeys = [].concat(values.de ?? []);
@@ -242,11 +276,11 @@ export async function main(argv) {
                 targets,
                 deKeys,
                 format: /** @type {'csv'|'tsv'|'json'} */ (fmt),
-                api: /** @type {'async'|'sync'} */ (api),
-                mode: /** @type {'upsert'|'insert'|'update'} */ (mode),
+                mode: /** @type {'upsert'|'insert'} */ (mode),
                 clearBeforeImport: clear,
                 acceptRiskFlag: acceptRisk,
                 isTTY: process.stdin.isTTY === true,
+                useGit,
             });
             return 0;
         }
@@ -286,19 +320,19 @@ export async function main(argv) {
             for (const deKey of deKeys) {
                 const candidates = await findImportCandidates(dataDir, deKey, fmt);
                 if (candidates.length === 0) {
-                    console.error(`No ${fmt} file found for DE "${deKey}" under ${dataDir}`);
+                    console.error(`No ${fmt} file found for DE "${deKey}" under ${projectRelativePosix(projectRoot, dataDir)}`);
                     return 1;
                 }
                 const filePath =
                     candidates.length === 1 ? candidates[0] : await pickLatestByMtime(candidates);
-                await importFromFile(sdk, {
+                const n = await importFromFile(sdk, {
                     filePath,
                     deKey,
                     format: /** @type {'csv'|'tsv'|'json'} */ (fmt),
-                    api: /** @type {'async'|'sync'} */ (api),
-                    mode: /** @type {'upsert'|'insert'|'update'} */ (mode),
+                    mode: /** @type {'upsert'|'insert'} */ (mode),
                 });
-                console.error(`Imported ${filePath} -> DE ${deKey}`);
+                const rel = projectRelativePosix(projectRoot, filePath);
+                console.error(`Imported: ${rel} (${n} rows) -> DE ${deKey}`);
             }
             return 0;
         }
@@ -318,14 +352,14 @@ export async function main(argv) {
         for (const filePath of fileList) {
             const base = path.basename(filePath);
             const { customerKey } = parseExportBasename(base);
-            await importFromFile(sdk, {
+            const n = await importFromFile(sdk, {
                 filePath,
                 deKey: customerKey,
                 format: /** @type {'csv'|'tsv'|'json'} */ (fmt),
-                api: /** @type {'async'|'sync'} */ (api),
-                mode: /** @type {'upsert'|'insert'|'update'} */ (mode),
+                mode: /** @type {'upsert'|'insert'} */ (mode),
             });
-            console.error(`Imported ${filePath}`);
+            const rel = projectRelativePosix(projectRoot, filePath);
+            console.error(`Imported: ${rel} (${n} rows)`);
         }
         return 0;
     }

package/lib/cross-bu-import.mjs

@@ -4,13 +4,13 @@ import readline from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import SDK from 'sfmc-sdk';
 import { resolveCredentialAndMid, buildSdkAuthObject } from './config.mjs';
-import { fetchAllRowObjects, serializeRows } from './export-de.mjs';
-import { exportDataExtensionToFile } from './export-de.mjs';
+import { fetchAllRowObjects, serializeRows, exportDataExtensionToFile } from './export-de.mjs';
 import { importRowsForDe } from './import-de.mjs';
+import { readRowsFromFile } from './read-rows.mjs';
 import { clearDataExtensionRows } from './clear-de.mjs';
 import { confirmClearBeforeImport } from './confirm-clear.mjs';
-import { dataDirectoryForBu } from './paths.mjs';
-import { buildExportBasename, filesystemSafeTimestamp } from './filename.mjs';
+import { dataDirectoryForBu, projectRelativePosix } from './paths.mjs';
+import { buildExportBasename, filesystemSafeTimestamp, parseExportBasename } from './filename.mjs';
 
 /**
  * @typedef {{ credential: string, bu: string }} CredBuTarget
@@ -51,27 +51,31 @@ async function offerPreExportBackup({ targets, deKeys, stdin: stdinStream, stdou
  * Imports Data Extension rows from a single source BU into one or more target
  * BUs.
  *
- * Before the import each target BU:
- * 1. Optionally exports its current DE data as a timestamped backup (TTY only).
- * 2. Optionally clears all existing rows (with danger warning covering every target).
- * 3. Receives the source rows written to a timestamped "download" file in its
- *    own `./data/<credential>/<bu>/` directory (mirroring mcdev retrieve).
- * 4. Has the rows imported via the REST API.
+ * Two source modes are supported:
+ *
+ * **API mode** (default): rows are fetched live from the source BU via the
+ * SFMC REST API.  Requires `sourceCred`, `sourceBu`, and `deKeys`.
+ *
+ * **File mode**: rows are read from local export files (e.g. previously
+ * created by `mcdata export`).  Requires `filePaths`; `deKeys` and
+ * `sourceCred`/`sourceBu` must be omitted.  The DE customer key is derived
+ * from each filename via `parseExportBasename`.
  *
  * @param {object} params
  * @param {string} params.projectRoot
  * @param {import('./config.mjs').Mcdevrc} params.mcdevrc
  * @param {Record<string, import('./config.mjs').AuthCredential>} params.mcdevAuth
- * @param {string} params.sourceCred
- * @param {string} params.sourceBu
+ * @param {string} [params.sourceCred] - API mode only
+ * @param {string} [params.sourceBu]   - API mode only
+ * @param {string[]} [params.deKeys]   - API mode only
+ * @param {string[]} [params.filePaths] - File mode only; mutually exclusive with sourceCred/sourceBu/deKeys
  * @param {CredBuTarget[]} params.targets
- * @param {string[]} params.deKeys
  * @param {'csv'|'tsv'|'json'} params.format
- * @param {'async'|'sync'} params.api
- * @param {'upsert'|'insert'|'update'} params.mode
+ * @param {'upsert'|'insert'} params.mode
  * @param {boolean} params.clearBeforeImport
  * @param {boolean} params.acceptRiskFlag
  * @param {boolean} params.isTTY
+ * @param {boolean} [params.useGit] - stable snapshot basename (no timestamp)
  * @param {NodeJS.ReadableStream} [params.stdin]  Override for testing
  * @param {NodeJS.WritableStream} [params.stdout] Override for testing
  * @returns {Promise<void>}
@@ -81,28 +85,48 @@ export async function crossBuImport(params) {
         projectRoot,
         mcdevrc,
         mcdevAuth,
-        sourceCred,
-        sourceBu,
         targets,
-        deKeys,
         format,
-        api,
         mode,
         clearBeforeImport,
         acceptRiskFlag,
         isTTY,
+        useGit = false,
     } = params;
     const stdin = params.stdin;
     const stdout = params.stdout;
 
-    // Validate all BU configurations upfront before making any API calls
-    const { mid: srcMid, authCred: srcAuth } = resolveCredentialAndMid(mcdevrc, mcdevAuth, sourceCred, sourceBu);
+    // Determine source mode
+    const filePaths = params.filePaths ?? null;
+    const isFileBased = filePaths !== null && filePaths.length > 0;
+
+    // Derive DE keys: from explicit list (API mode) or from filenames (file mode)
+    const deKeys = isFileBased
+        ? filePaths.map((fp) => parseExportBasename(path.basename(fp)).customerKey)
+        : (params.deKeys ?? []);
+
+    // Build a lookup map from deKey → filePath for file mode
+    /** @type {Map<string, string>} */
+    const fileByDeKey = new Map();
+    if (isFileBased) {
+        for (const fp of filePaths) {
+            fileByDeKey.set(parseExportBasename(path.basename(fp)).customerKey, fp);
+        }
+    }
+
+    // Validate all target BU configurations upfront
     for (const { credential, bu } of targets) {
         resolveCredentialAndMid(mcdevrc, mcdevAuth, credential, bu);
     }
 
-    // Connect to source BU
-    const srcSdk = new SDK(buildSdkAuthObject(srcAuth, srcMid), { requestAttempts: 3 });
+    // Connect to source BU (API mode only)
+    let srcSdk = null;
+    if (!isFileBased) {
+        const { mid: srcMid, authCred: srcAuth } = resolveCredentialAndMid(
+            mcdevrc, mcdevAuth, params.sourceCred, params.sourceBu
+        );
+        srcSdk = new SDK(buildSdkAuthObject(srcAuth, srcMid), { requestAttempts: 3 });
+    }
 
     // Optional pre-import backup of target BU data
     if (isTTY) {
@@ -112,14 +136,16 @@ export async function crossBuImport(params) {
                 const { mid, authCred } = resolveCredentialAndMid(mcdevrc, mcdevAuth, credential, bu);
                 const tgtSdk = new SDK(buildSdkAuthObject(authCred, mid), { requestAttempts: 3 });
                 for (const deKey of deKeys) {
-                    const outPath = await exportDataExtensionToFile(tgtSdk, {
+                    const { path: outPath, rowCount } = await exportDataExtensionToFile(tgtSdk, {
                         projectRoot,
                         credentialName: credential,
                         buName: bu,
                         deKey,
                         format,
+                        useGit: false,
                     });
-                    console.error(`Backup export: ${outPath}`);
+                    const rel = projectRelativePosix(projectRoot, outPath);
+                    console.error(`Backup export: ${rel} (${rowCount} rows)`);
                 }
             }
         }
@@ -130,9 +156,11 @@ export async function crossBuImport(params) {
         await confirmClearBeforeImport({ deKeys, targets, acceptRiskFlag, isTTY, stdin, stdout });
     }
 
-    // Fetch rows once per DE from the source, then fan out to every target
+    // Load rows once per DE then fan out to every target
     for (const deKey of deKeys) {
-        const rows = await fetchAllRowObjects(srcSdk, deKey);
+        const rows = isFileBased
+            ? await readRowsFromFile(fileByDeKey.get(deKey), format)
+            : await fetchAllRowObjects(srcSdk, deKey);
 
         // Clear targets before import (rows already confirmed above)
         if (clearBeforeImport) {
@@ -147,19 +175,18 @@ export async function crossBuImport(params) {
             const { mid, authCred } = resolveCredentialAndMid(mcdevrc, mcdevAuth, credential, bu);
             const tgtSdk = new SDK(buildSdkAuthObject(authCred, mid), { requestAttempts: 3 });
 
-            // Write a timestamped "download" file in the target BU's data directory.
-            // This mirrors what mcdev retrieve / mcdata export produces, giving a
-            // traceable snapshot of exactly what was imported.
+            // Write a snapshot file in the target BU's data directory.
             const dir = dataDirectoryForBu(projectRoot, credential, bu);
             await fs.mkdir(dir, { recursive: true });
             const ts = filesystemSafeTimestamp();
-            const basename = buildExportBasename(deKey, ts, format);
-            const filePath = path.join(dir, basename);
-            await fs.writeFile(filePath, serializeRows(rows, format, false), 'utf8');
-            console.error(`Download stored: ${filePath}`);
+            const basename = buildExportBasename(deKey, ts, format, useGit);
+            const snapshotPath = path.join(dir, basename);
+            await fs.writeFile(snapshotPath, serializeRows(rows, format, false), 'utf8');
+            const snapRel = projectRelativePosix(projectRoot, snapshotPath);
+            console.error(`Download stored: ${snapRel} (${rows.length} rows)`);
 
-            await importRowsForDe(tgtSdk, { deKey, rows, api, mode });
-            console.error(`Imported -> ${credential}/${bu} DE ${deKey}`);
+            const imported = await importRowsForDe(tgtSdk, { deKey, rows, mode });
+            console.error(`Imported: ${credential}/${bu} DE ${deKey} (${imported} rows)`);
         }
     }
 }

package/lib/export-de.mjs

@@ -6,37 +6,17 @@ import { buildExportBasename, filesystemSafeTimestamp } from './filename.mjs';
 import { dataDirectoryForBu } from './paths.mjs';
 
 /**
- * @param {{ rest: { get: (path: string) => Promise<any> } }} sdk
+ * @param {{ rest: { getBulk: (path: string, pageSize?: number) => Promise<any> } }} sdk
  * @param {string} deKey
  * @returns {Promise<object[]>}
  */
 export async function fetchAllRowObjects(sdk, deKey) {
-    const pageSize = 2500;
-    let page = 1;
+    const basePath = rowsetGetPath(deKey);
+    const data = await sdk.rest.getBulk(basePath, 2500);
+    const items = data.items ?? [];
     const rows = [];
-    let hasMore = true;
-    while (hasMore) {
-        const qs = new URLSearchParams({
-            page: String(page),
-            pageSize: String(pageSize),
-        });
-        const urlPath = `${rowsetGetPath(deKey)}?${qs.toString()}`;
-        const data = await sdk.rest.get(urlPath);
-        const items = data.items ?? [];
-        for (const item of items) {
-            rows.push({ ...item.keys, ...item.values });
-        }
-        if (items.length === 0) {
-            hasMore = false;
-        } else if (data.hasMoreRows === false) {
-            hasMore = false;
-        } else if (data.hasMoreRows === true) {
-            hasMore = true;
-            page++;
-        } else {
-            hasMore = items.length === pageSize;
-            page++;
-        }
+    for (const item of items) {
+        rows.push({ ...item.keys, ...item.values });
     }
     return rows;
 }
@@ -62,7 +42,7 @@ export function serializeRows(rows, format, jsonPretty) {
 }
 
 /**
- * @param {{ rest: { get: (path: string) => Promise<any> } }} sdk
+ * @param {{ rest: { getBulk: (path: string, pageSize?: number) => Promise<any> } }} sdk
  * @param {object} params
  * @param {string} params.projectRoot
  * @param {string} params.credentialName
@@ -70,17 +50,18 @@ export function serializeRows(rows, format, jsonPretty) {
  * @param {string} params.deKey
  * @param {'csv'|'tsv'|'json'} params.format
  * @param {boolean} [params.jsonPretty]
- * @returns {Promise<string>} written file path
+ * @param {boolean} [params.useGit]
+ * @returns {Promise<{ path: string, rowCount: number }>}
  */
 export async function exportDataExtensionToFile(sdk, params) {
-    const { projectRoot, credentialName, buName, deKey, format, jsonPretty = false } = params;
+    const { projectRoot, credentialName, buName, deKey, format, jsonPretty = false, useGit = false } = params;
     const rows = await fetchAllRowObjects(sdk, deKey);
     const dir = dataDirectoryForBu(projectRoot, credentialName, buName);
     await fs.mkdir(dir, { recursive: true });
     const ts = filesystemSafeTimestamp();
-    const basename = buildExportBasename(deKey, ts, format);
+    const basename = buildExportBasename(deKey, ts, format, useGit);
     const outPath = path.join(dir, basename);
     const body = serializeRows(rows, format, jsonPretty);
     await fs.writeFile(outPath, body, 'utf8');
-    return outPath;
+    return { path: outPath, rowCount: rows.length };
 }

package/lib/file-resolve.mjs

@@ -1,9 +1,9 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { filterIllegalFilenames, MCDATA_SENTINEL } from './filename.mjs';
+import { parseExportBasename } from './filename.mjs';
 
 /**
- * Find export files under data dir matching encoded DE key prefix and extension.
+ * Find export files under data dir matching the DE customer key and extension.
  *
  * @param {string} dataDir
  * @param {string} customerKey
@@ -11,7 +11,6 @@ import { filterIllegalFilenames, MCDATA_SENTINEL } from './filename.mjs';
  * @returns {Promise<string[]>} full paths
  */
 export async function findImportCandidates(dataDir, customerKey, format) {
-    const prefix = filterIllegalFilenames(customerKey) + MCDATA_SENTINEL;
     let entries;
     try {
         entries = await fs.readdir(dataDir, { withFileTypes: true });
@@ -28,8 +27,13 @@ export async function findImportCandidates(dataDir, customerKey, format) {
         if (!name.endsWith(`.${ext}`)) {
             continue;
         }
-        if (name.startsWith(prefix)) {
-            matches.push(path.join(dataDir, name));
+        try {
+            const { customerKey: parsedKey } = parseExportBasename(name);
+            if (parsedKey === customerKey) {
+                matches.push(path.join(dataDir, name));
+            }
+        } catch {
+            continue;
         }
     }
     return matches;

package/lib/filename.mjs

@@ -4,6 +4,9 @@
  * @see https://github.com/Accenture/sfmc-devtools (lib/util/file.js)
  */
 
+/** Literal segment between encoded DE key and timestamp (or extension in --git mode). */
+export const MCDATA_SEGMENT = '.mcdata.';
+
 /**
  * @param {string} filename
  * @returns {string}
@@ -35,17 +38,19 @@ export function reverseFilterIllegalFilenames(filename) {
     return decodeURIComponent(filename).split('_STAR_').join('*');
 }
 
-/** Sentinel between encoded DE key and timestamp in export basenames; cannot appear in the key segment after encoding. */
-export const MCDATA_SENTINEL = '+MCDATA+';
-
 /**
  * @param {string} customerKey
- * @param {string} safeTs - filesystem-safe UTC timestamp
+ * @param {string} safeTs - filesystem-safe UTC timestamp (ignored when useGit is true)
  * @param {'csv'|'tsv'|'json'} ext
+ * @param {boolean} [useGit] - stable `key.mcdata.ext` without timestamp
  * @returns {string} basename without directory
  */
-export function buildExportBasename(customerKey, safeTs, ext) {
-    return `${filterIllegalFilenames(customerKey)}${MCDATA_SENTINEL}${safeTs}.${ext}`;
+export function buildExportBasename(customerKey, safeTs, ext, useGit = false) {
+    const enc = filterIllegalFilenames(customerKey);
+    if (useGit) {
+        return `${enc}.mcdata.${ext}`;
+    }
+    return `${enc}${MCDATA_SEGMENT}${safeTs}.${ext}`;
 }
 
 /**
@@ -57,24 +62,33 @@ export function filesystemSafeTimestamp(d = new Date()) {
 }
 
 /**
- * @param {string} basename - e.g. `encodedKey+MCDATA+2026-04-06T15-00-00.000Z.csv`
+ * @param {string} basename - e.g. `encodedKey.mcdata.2026-04-06T15-00-00.000Z.csv` or `encodedKey.mcdata.csv`
  * @returns {{ customerKey: string, timestampPart: string, ext: string }}
  */
 export function parseExportBasename(basename) {
     const lastDot = basename.lastIndexOf('.');
     const stem = lastDot === -1 ? basename : basename.slice(0, lastDot);
-    const ext = lastDot === -1 ? '' : basename.slice(lastDot + 1);
-    const idx = stem.indexOf(MCDATA_SENTINEL);
-    if (idx === -1) {
-        throw new Error(
-            `Filename must contain "${MCDATA_SENTINEL}" between encoded key and timestamp: ${basename}`
-        );
+    const ext = lastDot === -1 ? '' : basename.slice(lastDot + 1).toLowerCase();
+
+    const idx = stem.indexOf(MCDATA_SEGMENT);
+    if (idx !== -1) {
+        const encodedKey = stem.slice(0, idx);
+        const timestampPart = stem.slice(idx + MCDATA_SEGMENT.length);
+        return {
+            customerKey: reverseFilterIllegalFilenames(encodedKey),
+            timestampPart,
+            ext,
+        };
     }
-    const encodedKey = stem.slice(0, idx);
-    const timestampPart = stem.slice(idx + MCDATA_SENTINEL.length);
-    return {
-        customerKey: reverseFilterIllegalFilenames(encodedKey),
-        timestampPart,
-        ext: ext.toLowerCase(),
-    };
+
+    if (stem.endsWith('.mcdata')) {
+        const encodedKey = stem.slice(0, -'.mcdata'.length);
+        return {
+            customerKey: reverseFilterIllegalFilenames(encodedKey),
+            timestampPart: '',
+            ext,
+        };
+    }
+
+    throw new Error(`Filename must contain ".mcdata." or end with ".mcdata" before the extension: ${basename}`);
 }

package/lib/import-de.mjs

@@ -8,23 +8,23 @@ import { readRowsFromFile } from './read-rows.mjs';
  * @param {object} params
  * @param {string} params.deKey
  * @param {object[]} params.rows
- * @param {'async'|'sync'} params.api
- * @param {'upsert'|'insert'|'update'} params.mode
- * @returns {Promise<void>}
+ * @param {'upsert'|'insert'} params.mode
+ * @returns {Promise<number>} number of rows imported
  */
 export async function importRowsForDe(sdk, params) {
-    const { deKey, rows, api, mode } = params;
-    const route = resolveImportRoute(api, mode);
+    const { deKey, rows, mode } = params;
+    const route = resolveImportRoute(mode);
     const chunks = chunkItemsForPayload(rows);
     for (const chunk of chunks) {
-        const path = route.path(deKey);
+        const p = route.path(deKey);
         const body = { items: chunk };
         await withRetry429(() =>
             route.method === 'PUT'
-                ? sdk.rest.put(path, body)
-                : sdk.rest.post(path, body)
+                ? sdk.rest.put(p, body)
+                : sdk.rest.post(p, body)
         );
     }
+    return rows.length;
 }
 
 /**
@@ -33,16 +33,14 @@ export async function importRowsForDe(sdk, params) {
  * @param {string} params.filePath
  * @param {string} params.deKey - target DE customer key for API
  * @param {'csv'|'tsv'|'json'} params.format
- * @param {'async'|'sync'} params.api
- * @param {'upsert'|'insert'|'update'} params.mode
- * @returns {Promise<void>}
+ * @param {'upsert'|'insert'} params.mode
+ * @returns {Promise<number>} number of rows imported
  */
 export async function importFromFile(sdk, params) {
     const rows = await readRowsFromFile(params.filePath, params.format);
-    await importRowsForDe(sdk, {
+    return importRowsForDe(sdk, {
         deKey: params.deKey,
         rows,
-        api: params.api,
         mode: params.mode,
     });
 }

package/lib/import-routes.mjs

@@ -1,5 +1,5 @@
 /**
- * REST paths for Data Extension row writes (relative to REST base URL).
+ * REST paths for Data Extension row operations (relative to REST base URL).
  * Confirm against current Salesforce reference hubs when adjusting behavior.
  */
 
@@ -12,56 +12,24 @@ export function rowsetGetPath(deKey) {
 }
 
 /**
- * Async bulk upsert (default for `--api async`).
+ * Async bulk row writes: POST insert, PUT upsert (same URL).
  * @param {string} deKey
  * @returns {string}
  */
-export function asyncUpsertPath(deKey) {
+export function asyncDataExtensionRowsPath(deKey) {
     return `/data/v1/async/dataextensions/key:${encodeURIComponent(deKey)}/rows`;
 }
 
 /**
- * Synchronous upsert row set.
- * @param {string} deKey
- * @returns {string}
- */
-export function syncUpsertPath(deKey) {
-    return `/data/v1/customobjectdata/key/${encodeURIComponent(deKey)}/rows`;
-}
-
-/**
- * Synchronous insert row set (POST).
- * @param {string} deKey
- * @returns {string}
- */
-export function syncInsertPath(deKey) {
-    return `/data/v1/customobjectdata/key/${encodeURIComponent(deKey)}/rows`;
-}
-
-/**
- * @param {'async'|'sync'} api
- * @param {'upsert'|'insert'|'update'} mode
+ * @param {'upsert'|'insert'} mode
  * @returns {{ method: 'PUT'|'POST', path: (de: string) => string }}
  */
-export function resolveImportRoute(api, mode) {
-    if (api === 'async') {
-        if (mode !== 'upsert') {
-            throw new Error(
-                `Import mode "${mode}" is not supported with --api async (use --api sync or --mode upsert).`
-            );
-        }
-        return { method: 'PUT', path: asyncUpsertPath };
+export function resolveImportRoute(mode) {
+    if (mode === 'upsert') {
+        return { method: 'PUT', path: asyncDataExtensionRowsPath };
     }
-    if (api === 'sync') {
-        if (mode === 'upsert') {
-            return { method: 'PUT', path: syncUpsertPath };
-        }
-        if (mode === 'insert') {
-            return { method: 'POST', path: syncInsertPath };
-        }
-        if (mode === 'update') {
-            return { method: 'PUT', path: syncUpsertPath };
-        }
+    if (mode === 'insert') {
+        return { method: 'POST', path: asyncDataExtensionRowsPath };
     }
-    throw new Error(`Unsupported --api / --mode combination: ${api} + ${mode}`);
+    throw new Error(`Unsupported import mode "${mode}" (use upsert or insert).`);
 }

package/lib/index.mjs

@@ -1,7 +1,8 @@
 export { main } from './cli.mjs';
 export { filterIllegalFilenames, reverseFilterIllegalFilenames, parseExportBasename } from './filename.mjs';
 export { chunkItemsForPayload, DEFAULT_MAX_BODY_BYTES, MAX_OBJECTS_PER_BATCH } from './batch.mjs';
-export { resolveImportRoute, rowsetGetPath, asyncUpsertPath } from './import-routes.mjs';
+export { resolveImportRoute, rowsetGetPath, asyncDataExtensionRowsPath } from './import-routes.mjs';
 export { loadMcdevProject, parseCredBu, resolveCredentialAndMid, buildSdkAuthObject } from './config.mjs';
 export { multiBuExport } from './multi-bu-export.mjs';
 export { crossBuImport } from './cross-bu-import.mjs';
+export { projectRelativePosix } from './paths.mjs';

package/lib/multi-bu-export.mjs

@@ -1,6 +1,7 @@
 import SDK from 'sfmc-sdk';
 import { resolveCredentialAndMid, buildSdkAuthObject } from './config.mjs';
 import { exportDataExtensionToFile } from './export-de.mjs';
+import { projectRelativePosix } from './paths.mjs';
 
 /**
  * @typedef {{ credential: string, bu: string }} CredBuSource
@@ -19,24 +20,27 @@ import { exportDataExtensionToFile } from './export-de.mjs';
  * @param {string[]} params.deKeys
  * @param {'csv'|'tsv'|'json'} params.format
  * @param {boolean} [params.jsonPretty]
+ * @param {boolean} [params.useGit]
  * @returns {Promise<string[]>} Paths of all written files
  */
-export async function multiBuExport({ projectRoot, mcdevrc, mcdevAuth, sources, deKeys, format, jsonPretty = false }) {
+export async function multiBuExport({ projectRoot, mcdevrc, mcdevAuth, sources, deKeys, format, jsonPretty = false, useGit = false }) {
     /** @type {string[]} */
     const exported = [];
     for (const { credential, bu } of sources) {
         const { mid, authCred } = resolveCredentialAndMid(mcdevrc, mcdevAuth, credential, bu);
         const sdk = new SDK(buildSdkAuthObject(authCred, mid), { requestAttempts: 3 });
         for (const deKey of deKeys) {
-            const outPath = await exportDataExtensionToFile(sdk, {
+            const { path: outPath, rowCount } = await exportDataExtensionToFile(sdk, {
                 projectRoot,
                 credentialName: credential,
                 buName: bu,
                 deKey,
                 format,
                 jsonPretty,
+                useGit,
             });
-            console.error(`Exported: ${outPath}`);
+            const rel = projectRelativePosix(projectRoot, outPath);
+            console.error(`Exported: ${rel} (${rowCount} rows)`);
             exported.push(outPath);
         }
     }

package/lib/paths.mjs

@@ -9,3 +9,19 @@ import path from 'node:path';
 export function dataDirectoryForBu(projectRoot, credentialName, buName) {
     return path.join(projectRoot, 'data', credentialName, buName);
 }
+
+/**
+ * Path relative to mcdev project root for logs (POSIX-style, `./`-prefixed when needed).
+ *
+ * @param {string} projectRoot
+ * @param {string} absolutePath
+ * @returns {string}
+ */
+export function projectRelativePosix(projectRoot, absolutePath) {
+    const rel = path.relative(path.resolve(projectRoot), path.resolve(absolutePath));
+    const norm = rel.split(path.sep).join('/');
+    if (norm === '' || norm === '.') {
+        return './';
+    }
+    return norm.startsWith('.') ? norm : `./${norm}`;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "sfmc-dataloader",
-    "version": "1.1.0",
-    "description": "CLI (mcdata) to export and import Marketing Cloud Data Extension rows using mcdev project config and sfmc-sdk",
+    "version": "2.0.0",
+    "description": "SFMC Data Loader CLI (mcdata) to export and import Marketing Cloud Data Extension rows using mcdev project config and sfmc-sdk",
     "author": "Jörn Berkefeld <joern.berkefeld@gmail.com>",
     "license": "MIT",
     "repository": {