sfmc-dataloader 2.4.0 → 2.4.2

package/lib/cross-bu-import.mjs

@@ -4,7 +4,12 @@ import readline from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import SDK from 'sfmc-sdk';
 import { resolveCredentialAndMid, buildSdkAuthObject, buildSdkOptions } from './config.mjs';
-import { fetchAllRowObjects, serializeRows, exportDataExtensionToFile } from './export-de.mjs';
+import {
+    fetchAllRowObjects,
+    fetchDataExtensionFieldNames,
+    serializeRows,
+    exportDataExtensionToFile,
+} from './export-de.mjs';
 import { formatFromExtension } from './file-resolve.mjs';
 import { importRowsForDe } from './import-de.mjs';
 import { pollAsyncImportCompletion } from './async-status.mjs';
@@ -184,10 +189,28 @@ export async function crossBuImport(params) {
                 );
             }
             rows = await readRowsFromFile(filePath, detectedFormat);
+            if (rows.length === 0) {
+                throw new Error(
+                    `Import file contains no data rows: "${filePath}". ` +
+                        `The file may be empty, contain only a BOM, or contain only a header row. ` +
+                        `Export the DE first to obtain a template with column names, then add rows.`,
+                );
+            }
         } else {
             rows = await fetchAllRowObjects(srcSdk, deKey);
         }
 
+        let snapshotColumns = [];
+        if (rows.length === 0 && format !== 'json') {
+            try {
+                snapshotColumns = await fetchDataExtensionFieldNames(srcSdk.soap, deKey);
+            } catch (ex) {
+                console.error(
+                    `Warning: could not retrieve field names for empty DE "${deKey}" (snapshot): ${ex.message}`,
+                );
+            }
+        }
+
         for (const { credential, bu } of targets) {
             const { mid, authCred } = resolveCredentialAndMid(mcdevrc, mcdevAuth, credential, bu);
             const tgtSdk = new SDK(buildSdkAuthObject(authCred, mid), buildSdkOptions(logger));
@@ -215,7 +238,11 @@ export async function crossBuImport(params) {
             const ts = filesystemSafeTimestamp();
             const basename = buildExportBasename(deKey, ts, format, false);
             const snapshotPath = path.join(dir, basename);
-            await fs.writeFile(snapshotPath, serializeRows(rows, format, false), 'utf8');
+            await fs.writeFile(
+                snapshotPath,
+                serializeRows(rows, format, false, snapshotColumns),
+                'utf8',
+            );
             const snapRel = projectRelativePosix(projectRoot, snapshotPath);
             console.error(`Download stored: ${snapRel} (${rows.length} rows)`);
 

package/lib/export-de.mjs

@@ -30,28 +30,57 @@ export async function fetchAllRowObjects(sdk, deKey) {
     return rows;
 }
 
+/**
+ * Field names for a Data Extension, in ordinal order (SOAP).
+ *
+ * @param {{ retrieve: (type: string, props: string[], opts: object) => Promise.<any> }} soap
+ * @param {string} deKey - DE customer key
+ * @returns {Promise.<string[]>}
+ */
+export async function fetchDataExtensionFieldNames(soap, deKey) {
+    const result = await soap.retrieve('DataExtensionField', ['Name', 'Ordinal'], {
+        filter: {
+            leftOperand: 'DataExtension.CustomerKey',
+            operator: 'equals',
+            rightOperand: deKey,
+        },
+    });
+    const fields = result?.Results;
+    if (!Array.isArray(fields) || fields.length === 0) {
+        return [];
+    }
+    return fields
+        .toSorted((a, b) => Number(a.Ordinal ?? 0) - Number(b.Ordinal ?? 0))
+        .map((f) => f.Name);
+}
+
 /**
  * @param {object[]} rows
  * @param {'csv'|'tsv'|'json'} format
  * @param {boolean} jsonPretty
+ * @param {string[]} [columns] - when `rows` is empty and format is csv/tsv, emit this header row
  * @returns {string}
  */
-export function serializeRows(rows, format, jsonPretty) {
+export function serializeRows(rows, format, jsonPretty, columns = []) {
     if (format === 'json') {
         const space = jsonPretty ? 2 : undefined;
         return JSON.stringify(rows, null, space) + '\n';
     }
     const delimiter = format === 'tsv' ? '\t' : ',';
-    return stringify(rows, {
+    const options = {
         header: true,
         quoted: format === 'csv',
         bom: true,
         delimiter,
-    });
+    };
+    if (rows.length === 0 && columns.length > 0) {
+        options.columns = columns;
+    }
+    return stringify(rows, options);
 }
 
 /**
- * @param {{rest: {getBulk: (path: string, pageSize?: number) => Promise.<any>}}} sdk
+ * @param {{ rest: { getBulk: (path: string, pageSize?: number) => Promise.<any> }, soap: { retrieve: Function } }} sdk
  * @param {object} params
  * @param {string} params.projectRoot
  * @param {string} params.credentialName
@@ -73,12 +102,22 @@ export async function exportDataExtensionToFile(sdk, params) {
         useGit = false,
     } = params;
     const rows = await fetchAllRowObjects(sdk, deKey);
+    let columns = [];
+    if (rows.length === 0 && format !== 'json') {
+        try {
+            columns = await fetchDataExtensionFieldNames(sdk.soap, deKey);
+        } catch (ex) {
+            console.error(
+                `Warning: could not retrieve field names for empty DE "${deKey}": ${ex.message}`,
+            );
+        }
+    }
     const dir = dataDirectoryForBu(projectRoot, credentialName, buName);
     await fs.mkdir(dir, { recursive: true });
     const ts = filesystemSafeTimestamp();
     const basename = buildExportBasename(deKey, ts, format, useGit);
     const outPath = path.join(dir, basename);
-    const body = serializeRows(rows, format, jsonPretty);
+    const body = serializeRows(rows, format, jsonPretty, columns);
     await fs.writeFile(outPath, body, 'utf8');
     return { path: outPath, rowCount: rows.length };
 }

package/lib/import-de.mjs

@@ -45,6 +45,13 @@ export async function importFromFile(sdk, params) {
         );
     }
     const rows = await readRowsFromFile(params.filePath, format);
+    if (rows.length === 0) {
+        throw new Error(
+            `Import file contains no data rows: "${params.filePath}". ` +
+                `The file may be empty, contain only a BOM, or contain only a header row. ` +
+                `Export the DE first to obtain a template with column names, then add rows.`,
+        );
+    }
     return importRowsForDe(sdk, {
         deKey: params.deKey,
         rows,

package/lib/read-rows.mjs

@@ -29,7 +29,7 @@ export async function readRowsFromFile(filePath, format) {
                     mapHeaders: ({ header }) => {
                         let h = header;
                         // Strip BOM if present (backup in case bom:true misses it)
-                        if (h.codePointAt(0) === 0xFEFF) {
+                        if (h.startsWith('\uFEFF')) {
                             h = h.slice(1);
                         }
                         // Strip surrounding quotes if present (non-standard quoted TSV)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "sfmc-dataloader",
-    "version": "2.4.0",
+    "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",
     "author": "Jörn Berkefeld <joern.berkefeld@gmail.com>",
     "license": "MIT",