sfmc-dataloader 2.4.2 → 2.6.0

package/README.md

@@ -1,12 +1,57 @@
 # sfmc-dataloader
 
-Command-line tool **`mcdata`** to export and import **Salesforce Marketing Cloud Engagement** Data Extension rows using the same project files as [mcdev](https://github.com/Accenture/sfmc-devtools) (`.mcdevrc.json`, `.mcdev-auth.json`) and [sfmc-sdk](https://www.npmjs.com/package/sfmc-sdk) for REST/SOAP.
+Command-line tool **`mcdata`** to export and import **Salesforce Marketing Cloud Engagement** Data Extension rows using [sfmc-sdk](https://www.npmjs.com/package/sfmc-sdk) for REST/SOAP.
+
+Works **standalone** — no mcdev installation required — and also integrates with existing [mcdev](https://github.com/Accenture/sfmc-devtools) projects.
+
+## Config files
+
+| File pair | When to use |
+|---|---|
+| `.mcdevrc.json` + `.mcdev-auth.json` | Existing mcdev projects — **always wins** when both pairs present |
+| `.mcdatarc.json` + `.mcdata-auth.json` | Standalone setup; created by `mcdata init` |
+
+**Precedence:** When `.mcdevrc.json` and `.mcdev-auth.json` both exist they are loaded; any mcdata files are ignored (a warning is printed to stderr). Both file pairs share the same logical shape (`credentials.<name>.businessUnits`), so all commands work with either layout.
+
+## Standalone setup with `mcdata init`
+
+If you don't have an existing mcdev project, run:
+
+```bash
+mcdata init
+```
+
+The interactive wizard collects:
+
+1. Credential name (e.g. `MyOrg`)
+2. Installed-package **Client ID**
+3. Installed-package **Client Secret**
+4. **Auth URL** (e.g. `https://<tenantsubdomain>.auth.marketingcloudapis.com/`)
+5. **Enterprise MID** (parent account ID)
+
+It fetches your Business Unit list via the SOAP API, writes `.mcdatarc.json` and `.mcdata-auth.json`, and adds the auth file to `.gitignore`.
+
+### Non-interactive / CI mode
+
+Pass all five flags to skip prompts:
+
+```bash
+mcdata init \
+  --credential MyOrg \
+  --client-id  <id> \
+  --client-secret <secret> \
+  --auth-url  https://<tenantsubdomain>.auth.marketingcloudapis.com/ \
+  --enterprise-id <eid> \
+  --yes
+```
+
+Use `--yes` to overwrite existing `.mcdatarc.json` / `.mcdata-auth.json` without confirmation.
 
 ## Requirements
 
 - Node.js `^20.19.0 || ^22.13.0 || >=24` (aligned with `sfmc-sdk`)
-- A mcdev-style project with credentials on disk
-- Peer: `mcdev` `>=7` (declare alongside your project tooling)
+- An SFMC installed package with Data Extension access
+- **Optional:** `mcdev` `>=7` — listed in `optionalDependencies`; install globally if you also use mcdev for other metadata types
 
 ## Install
 
@@ -128,7 +173,15 @@ Interactive: type `YES` when prompted. In CI, add `--i-accept-clear-data-risk` a
 | `--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.
+Log lines include **row counts** and show file paths as **absolute paths in double-quotes** (e.g. `"C:\data\MyCred\DEV\Contact.mcdata.csv"`) so they are clickable in VS Code's integrated terminal.
+
+## Programmatic API (Node.js)
+
+Import from `sfmc-dataloader` for use in other tools (for example the **SFMC Data Loader** VS Code extension):
+
+| Export | Purpose |
+|--------|---------|
+| `fetchDeList(projectRoot, credential, bu)` | Returns all Data Extension **names** and **customer keys** for one BU via SOAP `retrieveBulk` (pagination handled by **sfmc-sdk**). Not a CLI command — intended for in-process callers that already have mcdev/mcdata config on disk. |
 
 ## License
 

package/bin/mcdata.mjs

@@ -4,6 +4,6 @@ import { main } from '../lib/cli.mjs';
 main(process.argv)
     .then((code) => process.exit(typeof code === 'number' ? code : 0))
     .catch((ex) => {
-        console.error(ex);
+        console.error(ex.message ?? String(ex));
         process.exit(1);
     });

package/lib/business-units.mjs

@@ -0,0 +1,93 @@
+import SDK from 'sfmc-sdk';
+import { buildSdkOptions } from './config.mjs';
+
+/**
+ * Normalize a Business Unit name to a safe identifier, mirroring mcdev's convention:
+ * strip non-word/non-space characters, replace spaces with underscores, collapse consecutive underscores.
+ *
+ * @param {string} name - Raw BU name from the API
+ * @returns {string}
+ */
+export function normalizeBuName(name) {
+    return name
+        .replaceAll(/[^\w\s]/gi, '')
+        .replaceAll(/ +/g, '_')
+        .replaceAll(/__+/g, '_');
+}
+
+/**
+ * @typedef {object} BusinessUnitsResult
+ * @property {number} eid - Enterprise MID (ID of the parent BU)
+ * @property {Record<string, number>} businessUnits - Normalized BU name → MID mapping; parent BU is stored under `_ParentBU_`
+ */
+
+/**
+ * Process a SOAP BusinessUnit retrieve result into the mcdata config shape.
+ * Exposed separately so it can be tested without a live SDK instance.
+ *
+ * @param {object[]} results - `buResult.Results` array from the SOAP API
+ * @param {number} enterpriseId - Fallback EID when no parent row is found
+ * @returns {BusinessUnitsResult}
+ */
+export function processBusinessUnitResults(results, enterpriseId) {
+    /** @type {Record<string, number>} */
+    const businessUnits = {};
+    let eid = enterpriseId;
+
+    for (const row of results) {
+        const id = Number.parseInt(row.ID, 10);
+        const parentId = Number.parseInt(row.ParentID, 10);
+
+        if (parentId === 0) {
+            businessUnits['_ParentBU_'] = id;
+            eid = id;
+        } else {
+            businessUnits[normalizeBuName(row.Name)] = id;
+        }
+    }
+
+    return { eid, businessUnits };
+}
+
+/**
+ * Fetch all Business Units for a Marketing Cloud instance via the SOAP API.
+ * Instantiates a temporary SDK client scoped to the enterprise account (`account_id: enterpriseId`)
+ * and calls `BusinessUnit` retrieve with `QueryAllAccounts: true`.
+ *
+ * @param {{ client_id: string, client_secret: string, auth_url: string }} authCred
+ * @param {number} enterpriseId - Enterprise MID (parent account ID)
+ * @returns {Promise.<BusinessUnitsResult>}
+ */
+export async function fetchBusinessUnits(authCred, enterpriseId) {
+    const sdk = new SDK(
+        {
+            client_id: authCred.client_id,
+            client_secret: authCred.client_secret,
+            auth_url: authCred.auth_url,
+            account_id: enterpriseId,
+        },
+        buildSdkOptions(),
+    );
+
+    let buResult;
+    try {
+        buResult = await sdk.soap.retrieve(
+            'BusinessUnit',
+            ['Name', 'ID', 'ParentName', 'ParentID', 'IsActive'],
+            { QueryAllAccounts: true },
+        );
+    } catch (ex) {
+        throw new Error(
+            `Could not retrieve Business Units - check client_id, client_secret, auth_url, and enterprise MID.`,
+            { cause: ex },
+        );
+    }
+
+    if (!buResult?.Results?.length) {
+        throw new Error(
+            'Credentials accepted but no Business Units returned. Verify this installed package has access to the parent BU.',
+        );
+    }
+
+    return processBusinessUnitResults(buResult.Results, enterpriseId);
+}

package/lib/cli.mjs

@@ -5,13 +5,13 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import SDK from 'sfmc-sdk';
 import {
-    loadMcdevProject,
+    loadProjectConfig,
     parseCredBu,
     resolveCredentialAndMid,
     buildSdkAuthObject,
     buildSdkOptions,
 } from './config.mjs';
-import { dataDirectoryForBu, projectRelativePosix } from './paths.mjs';
+import { dataDirectoryForBu } from './paths.mjs';
 import { exportDataExtensionToFile } from './export-de.mjs';
 import { findImportCandidates, pickLatestByMtime } from './file-resolve.mjs';
 import { parseExportBasename } from './filename.mjs';
@@ -23,6 +23,7 @@ import { getDeRowCount } from './row-count.mjs';
 import { multiBuExport } from './multi-bu-export.mjs';
 import { crossBuImport } from './cross-bu-import.mjs';
 import { initDebugLogger } from './debug-logger.mjs';
+import { runMcdataInit } from './init-project.mjs';
 
 /** @returns {string} semver from this package's package.json */
 function readCliPackageVersion() {
@@ -36,9 +37,10 @@ function readCliPackageVersion() {
 }
 
 function printHelp() {
-    console.log(`mcdata — SFMC Data Extension export/import (mcdev project)
+    console.log(`mcdata - SFMC Data Extension export/import
 
 Usage:
+  mcdata init [options]
   mcdata export <credential>/<bu> --de <key> [--de <key> ...] [options]
   mcdata export --from <cred>/<bu> [--from <cred>/<bu> ...] --de <key> [--de <key> ...] [options]
   mcdata import <credential>/<bu> (--de <key> ... | --file <path> ...) [options]
@@ -47,12 +49,20 @@ Usage:
 
 Options:
   --version               Print version and exit
-  -p, --project <dir>     mcdev project root (default: cwd)
+  -p, --project <dir>     Project root (default: cwd)
   --format <csv|tsv|json> Export file format (default: csv); ignored for imports
   --json-pretty           Pretty-print JSON on export
   --git                   Stable filenames: <key>.mcdata.<ext> (no timestamp)
   --debug                 Write API requests/responses to ./logs/data/*.log
 
+Init options:
+  --credential <name>     Credential name (e.g. MyOrg)
+  --client-id <id>        Installed package client ID
+  --client-secret <sec>   Installed package client secret
+  --auth-url <url>        Auth URL (e.g. https://<tenantsubdomain>.auth.marketingcloudapis.com/)
+  --enterprise-id <mid>   Enterprise MID (parent account ID)
+  -y, --yes               Overwrite existing .mcdatarc.json / .mcdata-auth.json without prompt
+
 Import options:
   --mode <upsert|insert>  Row write mode (default: upsert; async REST bulk API)
   --backup-before-import  Export target DE data as a timestamped backup before import (no prompt)
@@ -66,6 +76,10 @@ Multi-BU options:
   --to <cred>/<bu>        Import: target BU (repeatable for multiple targets)
                           Import (file mode): use with --file only (no --from needed)
 
+Config files:
+  .mcdevrc.json / .mcdev-auth.json       mcdev layout (wins when both pairs present)
+  .mcdatarc.json / .mcdata-auth.json     standalone mcdata layout (created by mcdata init)
+
 Notes:
   Exports are written under ./data/<credential>/<bu>/ using ".mcdata." in the filename.
   Import with --de resolves the latest matching file (csv/tsv/json) in that folder (by mtime).
@@ -108,6 +122,12 @@ export async function main(argv) {
                 debug: { type: 'boolean', default: false },
                 help: { type: 'boolean', short: 'h', default: false },
                 version: { type: 'boolean', default: false },
+                credential: { type: 'string' },
+                'client-id': { type: 'string' },
+                'client-secret': { type: 'string' },
+                'auth-url': { type: 'string' },
+                'enterprise-id': { type: 'string' },
+                yes: { type: 'boolean', short: 'y', default: false },
             },
         });
         values = parsed.values;
@@ -135,6 +155,21 @@ export async function main(argv) {
     const credBuRaw = positionals[1]; // May be undefined when --from/--to flags are used
 
     const projectRoot = path.resolve(values.project ?? process.cwd());
+
+    // ── init ─────────────────────────────────────────────────────────────────
+    if (sub === 'init') {
+        return runMcdataInit({
+            projectRoot,
+            isTTY: process.stdin.isTTY === true,
+            credential: values.credential,
+            clientId: values['client-id'],
+            clientSecret: values['client-secret'],
+            authUrl: values['auth-url'],
+            enterpriseId: values['enterprise-id'],
+            yes: values.yes,
+        });
+    }
+
     const fmt = values.format ?? 'csv';
     if (!['csv', 'tsv', 'json'].includes(fmt)) {
         console.error(`Invalid --format: ${fmt}`);
@@ -160,7 +195,7 @@ export async function main(argv) {
         ? initDebugLogger(projectRoot, readCliPackageVersion(), argv)
         : null;
     if (logger) {
-        console.error(`Debug log: ${projectRelativePosix(projectRoot, logger.logPath)}`);
+        console.error(`Debug log: "${path.resolve(logger.logPath)}"`);
     }
 
     // ── export ──────────────────────────────────────────────────────────────
@@ -199,7 +234,7 @@ export async function main(argv) {
                 console.error(ex.message);
                 return 1;
             }
-            const { mcdevrc, mcdevAuth } = loadMcdevProject(projectRoot);
+            const { mcdevrc, mcdevAuth } = loadProjectConfig(projectRoot);
             await multiBuExport({
                 projectRoot,
                 mcdevrc,
@@ -215,7 +250,7 @@ export async function main(argv) {
         }
 
         const { credential, bu } = parseCredBu(credBuRaw);
-        const { mcdevrc, mcdevAuth } = loadMcdevProject(projectRoot);
+        const { mcdevrc, mcdevAuth } = loadProjectConfig(projectRoot);
         const { mid, authCred } = resolveCredentialAndMid(mcdevrc, mcdevAuth, credential, bu);
         const sdk = new SDK(buildSdkAuthObject(authCred, mid), buildSdkOptions(logger));
         for (const deKey of des) {
@@ -228,8 +263,7 @@ export async function main(argv) {
                 jsonPretty: values['json-pretty'],
                 useGit,
             });
-            const rel = projectRelativePosix(projectRoot, out);
-            console.error(`Exported: ${rel} (${rowCount} rows)`);
+            console.error(`Exported: "${path.resolve(out)}" (${rowCount} rows)`);
         }
         return 0;
     }
@@ -267,7 +301,7 @@ export async function main(argv) {
                 console.error(ex.message);
                 return 1;
             }
-            const { mcdevrc, mcdevAuth } = loadMcdevProject(projectRoot);
+            const { mcdevrc, mcdevAuth } = loadProjectConfig(projectRoot);
             const crossBuHadError = await crossBuImport({
                 projectRoot,
                 mcdevrc,
@@ -332,7 +366,7 @@ export async function main(argv) {
                 console.error(ex.message);
                 return 1;
             }
-            const { mcdevrc, mcdevAuth } = loadMcdevProject(projectRoot);
+            const { mcdevrc, mcdevAuth } = loadProjectConfig(projectRoot);
             const crossBuApiHadError = await crossBuImport({
                 projectRoot,
                 mcdevrc,
@@ -372,7 +406,7 @@ export async function main(argv) {
         }
 
         const { credential, bu } = parseCredBu(credBuRaw);
-        const { mcdevrc, mcdevAuth } = loadMcdevProject(projectRoot);
+        const { mcdevrc, mcdevAuth } = loadProjectConfig(projectRoot);
         const { mid, authCred } = resolveCredentialAndMid(mcdevrc, mcdevAuth, credential, bu);
         const sdk = new SDK(buildSdkAuthObject(authCred, mid), buildSdkOptions(logger));
 
@@ -389,9 +423,7 @@ export async function main(argv) {
                         format: /** @type {'csv'|'tsv'|'json'} */ (fmt),
                         useGit: false,
                     });
-                    console.error(
-                        `Backup export: ${projectRelativePosix(projectRoot, outPath)} (${rowCount} rows)`,
-                    );
+                    console.error(`Backup export: "${path.resolve(outPath)}" (${rowCount} rows)`);
                 }
             }
             if (clear) {
@@ -406,7 +438,7 @@ export async function main(argv) {
                 const candidates = await findImportCandidates(dataDir, deKey);
                 if (candidates.length === 0) {
                     console.error(
-                        `No import file (csv/tsv/json) found for DE "${deKey}" under ${projectRelativePosix(projectRoot, dataDir)}`,
+                        `No import file (csv/tsv/json) found for DE "${deKey}" under "${path.resolve(dataDir)}"`,
                     );
                     return 1;
                 }
@@ -434,8 +466,7 @@ export async function main(argv) {
                     deKey,
                     mode: /** @type {'upsert'|'insert'} */ (mode),
                 });
-                const rel = projectRelativePosix(projectRoot, filePath);
-                console.error(`Imported: ${rel} (${n} rows) -> DE ${deKey}`);
+                console.error(`Imported: "${path.resolve(filePath)}" (${n} rows) -> DE ${deKey}`);
 
                 const importHadError = await pollAsyncImportCompletion(sdk, requestIds);
                 if (importHadError) {
@@ -476,9 +507,7 @@ export async function main(argv) {
                     format: /** @type {'csv'|'tsv'|'json'} */ (fmt),
                     useGit: false,
                 });
-                console.error(
-                    `Backup export: ${projectRelativePosix(projectRoot, outPath)} (${rowCount} rows)`,
-                );
+                console.error(`Backup export: "${path.resolve(outPath)}" (${rowCount} rows)`);
             }
         }
         if (clear) {
@@ -514,8 +543,7 @@ export async function main(argv) {
                 deKey: customerKey,
                 mode: /** @type {'upsert'|'insert'} */ (mode),
             });
-            const rel = projectRelativePosix(projectRoot, filePath);
-            console.error(`Imported: ${rel} (${n} rows)`);
+            console.error(`Imported: "${path.resolve(filePath)}" (${n} rows)`);
 
             const importHadError = await pollAsyncImportCompletion(sdk, requestIds);
             if (importHadError) {

package/lib/config.mjs

@@ -1,9 +1,18 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+export const FILE_MCDEV_RC = '.mcdevrc.json';
+export const FILE_MCDEV_AUTH = '.mcdev-auth.json';
+export const FILE_MCDATA_RC = '.mcdatarc.json';
+export const FILE_MCDATA_AUTH = '.mcdata-auth.json';
+
+export const WARN_MCDATA_SUPERSEDED =
+    'mcdata: Using .mcdevrc.json / .mcdev-auth.json; .mcdatarc.json / .mcdata-auth.json are ignored.';
+
 /**
  * @typedef {object} McdevrcCredentials
- * @property {Record<string, Record<string, number|string>>} businessUnits
+ * @property {number} [eid]
+ * @property {Record<string, number|string>} businessUnits
  */
 
 /**
@@ -16,24 +25,74 @@ import path from 'node:path';
  * @property {string} client_id
  * @property {string} client_secret
  * @property {string} auth_url
+ * @property {number} [account_id]
  */
 
 /**
+ * Loads project config from either mcdev or mcdata file pairs, applying mcdev-wins precedence.
+ * If both mcdev files exist they are used and mcdata files (if also present) are ignored with a warning.
+ * If only the mcdata pair exists it is used.
+ * Partial pairs (one file without the other) or no files at all throw descriptive errors.
+ *
  * @param {string} projectRoot
+ * @param {{ stderr?: (msg: string) => void }} [options]
  * @returns {{ mcdevrc: Mcdevrc, mcdevAuth: Record<string, AuthCredential> }}
  */
-export function loadMcdevProject(projectRoot) {
-    const rcPath = path.join(projectRoot, '.mcdevrc.json');
-    const authPath = path.join(projectRoot, '.mcdev-auth.json');
-    if (!fs.existsSync(rcPath)) {
-        throw new Error(`Missing ${rcPath}`);
+export function loadProjectConfig(projectRoot, options = {}) {
+    const err = options.stderr ?? ((msg) => console.error(msg));
+    const rcMcdev = path.join(projectRoot, FILE_MCDEV_RC);
+    const authMcdev = path.join(projectRoot, FILE_MCDEV_AUTH);
+    const rcMcdata = path.join(projectRoot, FILE_MCDATA_RC);
+    const authMcdata = path.join(projectRoot, FILE_MCDATA_AUTH);
+
+    const hasMcdevRc = fs.existsSync(rcMcdev);
+    const hasMcdevAuth = fs.existsSync(authMcdev);
+    const hasMcdataRc = fs.existsSync(rcMcdata);
+    const hasMcdataAuth = fs.existsSync(authMcdata);
+
+    const mcdevPairComplete = hasMcdevRc && hasMcdevAuth;
+    const mcdataPairComplete = hasMcdataRc && hasMcdataAuth;
+
+    if (mcdevPairComplete) {
+        if (hasMcdataRc || hasMcdataAuth) {
+            err(WARN_MCDATA_SUPERSEDED);
+        }
+        const mcdevrc = JSON.parse(fs.readFileSync(rcMcdev, 'utf8'));
+        const mcdevAuth = JSON.parse(fs.readFileSync(authMcdev, 'utf8'));
+        return { mcdevrc, mcdevAuth };
+    }
+
+    if (hasMcdevRc !== hasMcdevAuth) {
+        if (hasMcdevRc && !hasMcdevAuth) {
+            throw new Error(`Missing ${authMcdev} (pair with ${FILE_MCDEV_RC})`);
+        }
+        throw new Error(`Missing ${rcMcdev} (pair with ${FILE_MCDEV_AUTH})`);
+    }
+
+    if (mcdataPairComplete) {
+        const mcdevrc = JSON.parse(fs.readFileSync(rcMcdata, 'utf8'));
+        const mcdevAuth = JSON.parse(fs.readFileSync(authMcdata, 'utf8'));
+        return { mcdevrc, mcdevAuth };
     }
-    if (!fs.existsSync(authPath)) {
-        throw new Error(`Missing ${authPath}`);
+
+    if (hasMcdataRc !== hasMcdataAuth) {
+        if (hasMcdataRc && !hasMcdataAuth) {
+            throw new Error(`Missing ${authMcdata} (pair with ${FILE_MCDATA_RC})`);
+        }
+        throw new Error(`Missing ${rcMcdata} (pair with ${FILE_MCDATA_AUTH})`);
     }
-    const mcdevrc = JSON.parse(fs.readFileSync(rcPath, 'utf8'));
-    const mcdevAuth = JSON.parse(fs.readFileSync(authPath, 'utf8'));
-    return { mcdevrc, mcdevAuth };
+
+    throw new Error(
+        `No project config found in ${projectRoot}. Add ${FILE_MCDEV_RC} + ${FILE_MCDEV_AUTH} (mcdev), or ${FILE_MCDATA_RC} + ${FILE_MCDATA_AUTH} from \`mcdata init\`. Install mcdev globally (\`npm i -g mcdev\`) if you want a full mcdev project.`,
+    );
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {{ mcdevrc: Mcdevrc, mcdevAuth: Record<string, AuthCredential> }}
+ */
+export function loadMcdevProject(projectRoot) {
+    return loadProjectConfig(projectRoot);
 }
 
 /**
@@ -61,7 +120,7 @@ export function parseCredBu(credBu) {
 export function resolveCredentialAndMid(mcdevrc, mcdevAuth, credentialName, buName) {
     const credBlock = mcdevrc.credentials?.[credentialName];
     if (!credBlock) {
-        throw new Error(`Unknown credential "${credentialName}" in .mcdevrc.json`);
+        throw new Error(`Unknown credential "${credentialName}" in project credentials config`);
     }
     const midRaw = credBlock.businessUnits?.[buName];
     if (midRaw === undefined || midRaw === null) {
@@ -74,7 +133,7 @@ export function resolveCredentialAndMid(mcdevrc, mcdevAuth, credentialName, buNa
     const authCred = mcdevAuth[credentialName];
     if (!authCred?.client_id || !authCred?.client_secret || !authCred?.auth_url) {
         throw new Error(
-            `Missing auth fields for credential "${credentialName}" in .mcdev-auth.json`,
+            `Missing auth fields for credential "${credentialName}" in auth config file`,
         );
     }
     return { mid, authCred };

package/lib/cross-bu-import.mjs

@@ -16,7 +16,7 @@ import { pollAsyncImportCompletion } from './async-status.mjs';
 import { readRowsFromFile } from './read-rows.mjs';
 import { clearDataExtensionRows } from './clear-de.mjs';
 import { confirmClearBeforeImport } from './confirm-clear.mjs';
-import { dataDirectoryForBu, projectRelativePosix } from './paths.mjs';
+import { dataDirectoryForBu } from './paths.mjs';
 import { buildExportBasename, filesystemSafeTimestamp, parseExportBasename } from './filename.mjs';
 import { getDeRowCount } from './row-count.mjs';
 
@@ -164,8 +164,7 @@ export async function crossBuImport(params) {
                     format,
                     useGit: false,
                 });
-                const rel = projectRelativePosix(projectRoot, outPath);
-                console.error(`Backup export: ${rel} (${rowCount} rows)`);
+                console.error(`Backup export: "${path.resolve(outPath)}" (${rowCount} rows)`);
             }
         }
     }
@@ -243,8 +242,7 @@ export async function crossBuImport(params) {
                 serializeRows(rows, format, false, snapshotColumns),
                 'utf8',
             );
-            const snapRel = projectRelativePosix(projectRoot, snapshotPath);
-            console.error(`Download stored: ${snapRel} (${rows.length} rows)`);
+            console.error(`Download stored: "${path.resolve(snapshotPath)}" (${rows.length} rows)`);
 
             const { count: imported, requestIds } = await importRowsForDe(tgtSdk, {
                 deKey,

package/lib/de-list.mjs

@@ -0,0 +1,59 @@
+import SDK from 'sfmc-sdk';
+import {
+    loadProjectConfig,
+    resolveCredentialAndMid,
+    buildSdkAuthObject,
+    buildSdkOptions,
+} from './config.mjs';
+
+/**
+ * Maps a SOAP retrieveBulk result for DataExtension into sorted `{ name, key }` rows.
+ * Exported for unit tests; not part of the stable public API contract beyond testing.
+ *
+ * @param {object|null|undefined} bulkResult - `sdk.soap.retrieveBulk` response
+ * @returns {{ name: string, key: string }[]}
+ */
+export function normalizeDeListFromBulkResult(bulkResult) {
+    const rows = bulkResult?.Results;
+    if (!Array.isArray(rows) || rows.length === 0) {
+        return [];
+    }
+
+    const items = rows
+        .map((row) => ({
+            name: String(row.Name ?? ''),
+            key: String(row.CustomerKey ?? ''),
+        }))
+        .filter((item) => item.key.length > 0);
+
+    items.sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }));
+    return items;
+}
+
+/**
+ * Retrieves all Data Extension `Name` and `CustomerKey` values for a credential/BU via SOAP
+ * (`retrieveBulk` handles pagination). For programmatic use (e.g. VS Code extension cache), not the CLI.
+ *
+ * @param {string} projectRoot - Absolute path to project root (mcdev or mcdata config pair)
+ * @param {string} credential - Credential name from config
+ * @param {string} bu - Business unit key from config
+ * @returns {Promise.<{ name: string, key: string }[]>}
+ */
+export async function fetchDeList(projectRoot, credential, bu) {
+    const { mcdevrc, mcdevAuth } = loadProjectConfig(projectRoot);
+    const { mid, authCred } = resolveCredentialAndMid(mcdevrc, mcdevAuth, credential, bu);
+    const sdk = new SDK(buildSdkAuthObject(authCred, mid), buildSdkOptions());
+
+    let bulkResult;
+    try {
+        bulkResult = await sdk.soap.retrieveBulk('DataExtension', ['Name', 'CustomerKey'], {});
+    } catch (ex) {
+        const message = ex instanceof Error ? ex.message : String(ex);
+        throw new Error(
+            `Could not retrieve Data Extensions — check credentials and BU. Original error: ${message}`,
+            { cause: ex },
+        );
+    }
+
+    return normalizeDeListFromBulkResult(bulkResult);
+}

package/lib/import-de.mjs

@@ -1,3 +1,4 @@
+import { RestError } from 'sfmc-sdk/util';
 import { chunkItemsForPayload } from './batch.mjs';
 import { formatFromExtension } from './file-resolve.mjs';
 import { resolveImportRoute } from './import-routes.mjs';
@@ -20,9 +21,27 @@ export async function importRowsForDe(sdk, params) {
     for (const chunk of chunks) {
         const p = route.path(deKey);
         const body = { items: chunk };
-        const resp = await withRetry429(() =>
-            route.method === 'PUT' ? sdk.rest.put(p, body) : sdk.rest.post(p, body),
-        );
+        let resp;
+        try {
+            resp = await withRetry429(() =>
+                route.method === 'PUT' ? sdk.rest.put(p, body) : sdk.rest.post(p, body),
+            );
+        } catch (ex) {
+            const msgs =
+                ex instanceof RestError &&
+                ex.response?.status === 400 &&
+                Array.isArray(ex.response?.data?.resultMessages) &&
+                ex.response.data.resultMessages.length > 0
+                    ? ex.response.data.resultMessages
+                    : null;
+            if (msgs) {
+                const summary = msgs.map((m) => m.message ?? String(m)).join('; ');
+                throw new Error(`Import failed for DE "${deKey}" (HTTP 400): ${summary}`, {
+                    cause: ex,
+                });
+            }
+            throw ex;
+        }
         requestIds.push(resp?.requestId ?? null);
     }
     return { count: rows.length, requestIds };

package/lib/index.mjs

@@ -15,6 +15,12 @@ export {
 export { pollAsyncImportCompletion } from './async-status.mjs';
 export {
     loadMcdevProject,
+    loadProjectConfig,
+    WARN_MCDATA_SUPERSEDED,
+    FILE_MCDEV_RC,
+    FILE_MCDEV_AUTH,
+    FILE_MCDATA_RC,
+    FILE_MCDATA_AUTH,
     parseCredBu,
     resolveCredentialAndMid,
     buildSdkAuthObject,
@@ -23,3 +29,4 @@ export { multiBuExport } from './multi-bu-export.mjs';
 export { crossBuImport } from './cross-bu-import.mjs';
 export { getDeRowCount } from './row-count.mjs';
 export { projectRelativePosix } from './paths.mjs';
+export { fetchDeList } from './de-list.mjs';

package/lib/init-project.mjs

@@ -0,0 +1,214 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { FILE_MCDEV_RC, FILE_MCDEV_AUTH, FILE_MCDATA_RC, FILE_MCDATA_AUTH } from './config.mjs';
+import { fetchBusinessUnits } from './business-units.mjs';
+
+/**
+ * @typedef {object} InitOptions
+ * @property {string} projectRoot - Absolute path to the project folder
+ * @property {boolean} isTTY - Whether stdin is a TTY (interactive)
+ * @property {string} [credential] - Non-interactive: credential name
+ * @property {string} [clientId] - Non-interactive: client_id
+ * @property {string} [clientSecret] - Non-interactive: client_secret
+ * @property {string} [authUrl] - Non-interactive: auth_url
+ * @property {string} [enterpriseId] - Non-interactive: enterprise MID (string, will be parsed to int)
+ * @property {boolean} [yes] - Skip overwrite confirmation
+ * @property {Function} [_buFetcher] - Dependency injection for testing (replaces fetchBusinessUnits)
+ * @property {(question: string) => Promise.<boolean>} [_confirm] - Dependency injection for testing (replaces defaultConfirm)
+ * @property {(msg: string) => void} [stdout] - Override stdout (for testing)
+ * @property {(msg: string) => void} [stderr] - Override stderr (for testing)
+ */
+
+/**
+ * Ask a yes/no question on the terminal and return true only if the user types "y" or "yes".
+ *
+ * @param {string} question
+ * @returns {Promise.<boolean>}
+ */
+async function defaultConfirm(question) {
+    const rl = readline.createInterface({ input, output });
+    try {
+        const answer = (await rl.question(question)).trim().toLowerCase();
+        return answer === 'y' || answer === 'yes';
+    } finally {
+        rl.close();
+    }
+}
+
+/**
+ * Ensure .mcdata-auth.json is listed in the project's .gitignore (creates the file if absent).
+ *
+ * @param {string} projectRoot
+ */
+function ensureGitignore(projectRoot) {
+    const gitignorePath = path.join(projectRoot, '.gitignore');
+    const entry = '.mcdata-auth.json';
+    if (!fs.existsSync(gitignorePath)) {
+        fs.writeFileSync(gitignorePath, `${entry}\n`, 'utf8');
+        return;
+    }
+    const current = fs.readFileSync(gitignorePath, 'utf8');
+    const lines = current.split('\n');
+    if (!lines.some((line) => line.trim() === entry)) {
+        const appended = current.endsWith('\n')
+            ? current + entry + '\n'
+            : current + '\n' + entry + '\n';
+        fs.writeFileSync(gitignorePath, appended, 'utf8');
+    }
+}
+
+/**
+ * Run the `mcdata init` flow — interactive or non-interactive.
+ *
+ * @param {InitOptions} opts
+ * @returns {Promise.<number>} exit code (0 = success, 1 = failure)
+ */
+export async function runMcdataInit(opts) {
+    const { projectRoot, isTTY, yes = false, _buFetcher } = opts;
+    const out = opts.stdout ?? ((msg) => console.log(msg));
+    const err = opts.stderr ?? ((msg) => console.error(msg));
+
+    // Guard: do not init over an existing mcdev project (both files must be present)
+    if (
+        fs.existsSync(path.join(projectRoot, FILE_MCDEV_RC)) &&
+        fs.existsSync(path.join(projectRoot, FILE_MCDEV_AUTH))
+    ) {
+        err(
+            `This project is managed by mcdev (${FILE_MCDEV_RC} and ${FILE_MCDEV_AUTH} found).\n` +
+                `Manage your credentials by editing ${FILE_MCDEV_AUTH} directly, or run 'mcdev init' to re-initialise.`,
+        );
+        return 1;
+    }
+
+    // Guard: confirm overwrite when mcdata files already present
+    const mcdataRcPath = path.join(projectRoot, FILE_MCDATA_RC);
+    const mcdataAuthPath = path.join(projectRoot, FILE_MCDATA_AUTH);
+    if (!yes && (fs.existsSync(mcdataRcPath) || fs.existsSync(mcdataAuthPath))) {
+        if (isTTY) {
+            const confirmFn = opts._confirm ?? defaultConfirm;
+            const confirmed = await confirmFn(
+                `${FILE_MCDATA_RC} or ${FILE_MCDATA_AUTH} already exists. Override existing configuration? [y/N] `,
+            );
+            if (!confirmed) {
+                out('Aborted.');
+                return 1;
+            }
+        } else {
+            err(
+                `${FILE_MCDATA_RC} or ${FILE_MCDATA_AUTH} already exists in ${projectRoot}.\n` +
+                    `Pass --yes to overwrite.`,
+            );
+            return 1;
+        }
+    }
+
+    // Collect credentials
+    let credentialName = opts.credential;
+    let clientId = opts.clientId;
+    let clientSecret = opts.clientSecret;
+    let authUrl = opts.authUrl;
+    let enterpriseIdStr = opts.enterpriseId;
+
+    if (isTTY && (!credentialName || !clientId || !clientSecret || !authUrl || !enterpriseIdStr)) {
+        const rl = readline.createInterface({ input, output });
+        try {
+            if (!credentialName) {
+                credentialName = (await rl.question('Credential name (e.g. MyOrg): ')).trim();
+            }
+            if (!clientId) {
+                clientId = (await rl.question('Client ID: ')).trim();
+            }
+            if (!clientSecret) {
+                clientSecret = (await rl.question('Client Secret: ')).trim();
+            }
+            if (!authUrl) {
+                authUrl = (
+                    await rl.question(
+                        'Auth URL (e.g. https://<tenantsubdomain>.auth.marketingcloudapis.com/): ',
+                    )
+                ).trim();
+            }
+            if (!enterpriseIdStr) {
+                enterpriseIdStr = (await rl.question('Enterprise MID: ')).trim();
+            }
+        } finally {
+            rl.close();
+        }
+    } else if (!isTTY) {
+        // Non-interactive: all flags must be provided
+        const missing = [];
+        if (!credentialName) {
+            missing.push('--credential');
+        }
+        if (!clientId) {
+            missing.push('--client-id');
+        }
+        if (!clientSecret) {
+            missing.push('--client-secret');
+        }
+        if (!authUrl) {
+            missing.push('--auth-url');
+        }
+        if (!enterpriseIdStr) {
+            missing.push('--enterprise-id');
+        }
+        if (missing.length > 0) {
+            err(
+                `mcdata init: missing required flags in non-interactive mode: ${missing.join(', ')}`,
+            );
+            return 1;
+        }
+    }
+
+    const enterpriseId = Number.parseInt(String(enterpriseIdStr), 10);
+    if (!Number.isInteger(enterpriseId) || enterpriseId <= 0) {
+        err(`Invalid enterprise MID: ${enterpriseIdStr}`);
+        return 1;
+    }
+
+    // Fetch Business Units
+    out('Fetching Business Units from Marketing Cloud...');
+    let buResult;
+    try {
+        const buFetcher = _buFetcher ?? fetchBusinessUnits;
+        buResult = await buFetcher(
+            { client_id: clientId, client_secret: clientSecret, auth_url: authUrl },
+            enterpriseId,
+        );
+    } catch (ex) {
+        err(`Failed to fetch Business Units: ${ex.message}`);
+        return 1;
+    }
+    out(`Found ${Object.keys(buResult.businessUnits).length} Business Unit(s).`);
+
+    // Build config objects
+    const mcdataRc = {
+        credentials: {
+            [credentialName]: {
+                eid: buResult.eid,
+                businessUnits: buResult.businessUnits,
+            },
+        },
+    };
+
+    const mcdataAuth = {
+        [credentialName]: {
+            client_id: clientId,
+            client_secret: clientSecret,
+            auth_url: authUrl,
+            account_id: buResult.eid,
+        },
+    };
+
+    // Write files
+    fs.writeFileSync(mcdataRcPath, JSON.stringify(mcdataRc, null, 4) + '\n', 'utf8');
+    fs.writeFileSync(mcdataAuthPath, JSON.stringify(mcdataAuth, null, 4) + '\n', 'utf8');
+    ensureGitignore(projectRoot);
+
+    out(`Created ${FILE_MCDATA_RC} and ${FILE_MCDATA_AUTH} in ${projectRoot}`);
+    out('Make sure to add .mcdata-auth.json to your .gitignore (done automatically).');
+    out("Tip: To use mcdev instead, install it globally and run 'mcdev init'.");
+    return 0;
+}

package/lib/multi-bu-export.mjs

@@ -1,7 +1,7 @@
+import path from 'node:path';
 import SDK from 'sfmc-sdk';
 import { resolveCredentialAndMid, buildSdkAuthObject, buildSdkOptions } from './config.mjs';
 import { exportDataExtensionToFile } from './export-de.mjs';
-import { projectRelativePosix } from './paths.mjs';
 
 /**
  * @typedef {{ credential: string, bu: string }} CredBuSource
@@ -50,8 +50,7 @@ export async function multiBuExport({
                 jsonPretty,
                 useGit,
             });
-            const rel = projectRelativePosix(projectRoot, outPath);
-            console.error(`Exported: ${rel} (${rowCount} rows)`);
+            console.error(`Exported: "${path.resolve(outPath)}" (${rowCount} rows)`);
             exported.push(outPath);
         }
     }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "sfmc-dataloader",
-    "version": "2.4.2",
-    "description": "SFMC Data Loader CLI (mcdata) to export and import Marketing Cloud Data Extension rows using mcdev project config and sfmc-sdk",
+    "version": "2.6.0",
+    "description": "SFMC Data Loader CLI (mcdata) — standalone export/import of Marketing Cloud Data Extension rows; optional mcdev integration",
     "author": "Jörn Berkefeld <joern.berkefeld@gmail.com>",
     "license": "MIT",
     "repository": {
@@ -35,9 +35,6 @@
     "engines": {
         "node": "^20.19.0 || ^22.13.0 || >=24"
     },
-    "peerDependencies": {
-        "mcdev": ">=7"
-    },
     "dependencies": {
         "csv-parser": "3.2.0",
         "csv-stringify": "6.7.0",
@@ -61,5 +58,8 @@
         "globals": "^17.4.0",
         "husky": "^9.1.7",
         "prettier": "^3.8.1"
+    },
+    "optionalDependencies": {
+        "mcdev": ">=7"
     }
 }