campaign-cli 0.7.2

package/src/CampaignAuth.js

@@ -0,0 +1,131 @@
+import CampaignError from "./CampaignError.js";
+
+/**
+ * Campaign CLI class for managing ACC (Campaign Classic) instances.
+ * Provides authentication, instance management, and connection capabilities.
+ *
+ * @class CampaignAuth
+ * @classdesc Main class for interacting with ACC instances
+ */
+class CampaignAuth {
+  /**
+   * Configuration key for storing instances
+   * @type {string}
+   * @private
+   */
+  INSTANCES_KEY = "instances";
+
+  /**
+   * Creates a new CampaignAuth instance.
+   *
+   * @param {Object} sdk - ACC JS SDK instance
+   * @param {Object} config - Configstore instance for persistent storage
+   * @throws {CampaignError} Throws if SDK or config parameters are missing
+   *
+   * @example
+   * const auth = new CampaignAuth(sdk, config);
+   */
+  constructor(sdk, config) {
+    if (!sdk || !config) {
+      throw new CampaignError(
+        "SDK and Configstore instances are required to initialize CampaignAuth.",
+      );
+    }
+    this.sdk = sdk;
+    this.config = config;
+    this.instances = config.get(this.INSTANCES_KEY) || {};
+    this.instanceIds = Object.keys(this.instances);
+  }
+
+  async ip(){
+    console.log(`Fetching IP address...`);
+    const ip = await this.sdk.ip();
+    console.log(ip);
+  }
+
+  /**
+   * Initializes a new ACC instance with the provided credentials.
+   *
+   * @param {Object} options - Initialization options
+   * @param {string} options.alias - Local alias for this instance (e.g., 'prod', 'staging')
+   * @param {string} options.host - URL of ACC root (e.g., 'http://localhost:8080')
+   * @param {string} options.user - Operator username
+   * @param {string} options.password - Operator password
+   * @returns {Promise<void>} Resolves when instance is initialized and logged in
+   * @throws {CampaignError} Throws if instance with alias already exists
+   *
+   * @example
+   * await auth.init({
+   *   alias: 'prod',
+   *   host: 'http://localhost:8080',
+   *   user: 'admin',
+   *   password: 'password'
+   * });
+   */
+  async init(options) {
+    if (this.instanceIds.includes(options.alias)) {
+      throw new CampaignError(
+        `Instance with alias ${options.alias} already exists. Please choose a different alias.`,
+      );
+    }
+    const { alias, host, user, password } = options;
+    this.config.set(`${this.INSTANCES_KEY}.${alias}`, { host, user, password });
+    console.log(`✅ Instance ${alias} added successfully.`);
+    return this.login(options);
+  }
+
+  /**
+   * Logs in to an existing ACC instance.
+   *
+   * @param {Object} options - Login options
+   * @param {string} options.alias - Alias of the instance to log in to
+   * @returns {Promise<Object>} Resolves with the authenticated client
+   * @throws {CampaignError} Throws if instance doesn't exist or login fails
+   *
+   * @example
+   * const client = await auth.login({ alias: 'prod' });
+   */
+  async login(options) {
+    const { host, user, password } =
+      this.config.get(`instances.${options.alias}`) || {};
+    if (!host || !user || !password) {
+      throw new CampaignError(
+        `Authentication with alias "${options.alias}" doesn't exist. Use "acc auth list" to see all configured instances.`,
+      );
+    }
+    console.log(`↔️ Connecting ${user}@${host}...`);
+    const connectionParameters =
+      this.sdk.ConnectionParameters.ofUserAndPassword(host, user, password);
+    const client = await this.sdk.init(connectionParameters);
+    await client.logon();
+    const serverInfo = client.getSessionInfo().serverInfo;
+    if (!serverInfo) {
+      throw new CampaignError(`Unable to get server info.`);
+    }
+    console.log(
+      `✅ Logged in to ${serverInfo.instanceName} (${serverInfo.releaseName} build ${serverInfo.buildNumber}) successfully.`,
+    );
+    return client;
+  }
+
+  /**
+   * Lists all configured ACC instances.
+   *
+   * @returns {void} Outputs list of instances to console
+   *
+   * @example
+   * auth.list(); // Lists all configured instances
+   */
+  list() {
+    console.log(`📚 Reading ${this.instanceIds.length} instance(s)`);
+    if(this.instanceIds.length === 0) {
+      console.log(`  No instances configured yet. Use "campaign auth init" to add an instance.`);
+      return;
+    }
+    for (const [key, value] of Object.entries(this.instances)) {
+      console.log(`  - "${key}": ${value.user}@${value.host}`);
+    }
+  }
+}
+
+export default CampaignAuth;

package/src/CampaignError.js

@@ -0,0 +1,43 @@
+/**
+ * Custom error class for Campaign CLI operations.
+ * Extends the standard JavaScript Error class.
+ *
+ * @class CampaignError
+ * @extends Error
+ * @classdesc Custom error class for handling ACC-related errors
+ *
+ * @example
+ * throw new CampaignError("Instance already exists");
+ *
+ * @example
+ * try {
+ *   await auth.login({ alias: "nonexistent" });
+ * } catch (err) {
+ *   if (err instanceof CampaignError) {
+ *     console.error("Campaign error:", err.message);
+ *   }
+ * }
+ */
+class CampaignError extends Error {
+  /**
+   * Creates a new CampaignError instance.
+   *
+   * @param {string} [message] - Error message
+   * @param {Object} [options] - Error options
+   * @param {string} [options.cause] - Underlying cause of the error
+   *
+   * @example
+   * // Simple error
+   * throw new CampaignError("Instance not found");
+   *
+   * @example
+   * // Error with cause
+   * throw new CampaignError("Login failed", { cause: originalError });
+   */
+  constructor(message, options) {
+    super(message, options);
+    this.name = "CampaignError";
+  }
+}
+
+export default CampaignError;

package/src/CampaignInstance.js

@@ -0,0 +1,386 @@
+// npm
+import fs from "fs-extra";
+import path from "node:path";
+import chalk from "chalk";
+// sdk
+import sdk from "@adobe/acc-js-sdk";
+const { DomUtil } = sdk;
+
+/**
+ * Campaign Instance class for interacting with ACC instances.
+ * Handles data checking, pulling, and downloading from ACC schemas.
+ * - pull():
+ *   - paginates by batch of 10 (startLine, lineCount)
+ *   - download()
+ *     - sdk.xml.xtkQueryDef.create(schema)
+ *     - sdk.xml.xtkQueryDef.selectAll()
+ *     - sdk.xml.xtkQueryDef.executeQuery()
+ *     - for each XML record:
+ *       - parse()
+ *
+ * @class CampaignInstance
+ * @classdesc Class for managing data operations with ACC instances
+ */
+class CampaignInstance {
+  REGEX_CONFIG_ATTRIBUTE = /{(.+?)}/g;
+  CONFIG_XPATH_SEP = "/";
+  CONFIG_XPATH_ATTR = "@";
+
+  /**
+   * Creates a new CampaignInstance.
+   *
+   * @param {Object} client - Authenticated ACC client
+   * @param {Object} accConfig - Configuration object defining schemas and download options
+   * @param {Object} [accConfig.*] - Schema-specific configurations
+   *
+   * @example
+   * const instance = new CampaignInstance(client, { schemas: [
+   *   { schemaId: "nms:recipient", filename: "recipient_%name%.xml" }
+   * ]});
+   */
+  constructor(client, accConfig, options = { verbose: false }) {
+    this.client = client;
+    this.accConfig = accConfig;
+    this.verbose = options.verbose;
+    this.downloadPath = options.path;
+    /**
+     * Array of schema names to process (excluding default config)
+     * @type {string[]}
+     */
+    this.schemas = Object.keys(this.accConfig);
+
+    this.client.registerObserver({
+      onSOAPCall: (soapCall, safeRequestData) => {
+        // this.saveArchiveRequest(soapCall.request.data);
+      },
+      onSOAPCallSuccess: (soapCall, safeResponseData) => {
+        // this.saveArchiveResponse(soapCall.response);
+      },
+      onSOAPCallFailure: (soapCall, error) => {
+        // this.saveArchiveResponse(soapCall.response);
+      },
+    });
+  }
+
+  /**
+   * Gets query definition for a specific schema, merging with default config.
+   *
+   * @param {string} schema - Schema name (e.g., 'nms:recipient')
+   * @param {Object} baseQueryDef - Base query definition
+   * @returns {Object} Merged query definition
+   *
+   * @example
+   * const queryDef = instance._getQueryDefForSchema('nms:recipient', {
+   *   schema: 'nms:recipient',
+   *   operation: 'count'
+   * });
+   */
+  _getQueryDefForSchema(schemaConfig, baseQueryDef) {
+    const configQueryDef = schemaConfig.queryDef ? schemaConfig.queryDef : {};
+
+    return {
+      ...baseQueryDef,
+      ...configQueryDef,
+    };
+  }
+
+  /**
+   * Pulls data from all schemas in the ACC instance.
+   * Implements pagination to handle large datasets.
+   *
+   * @returns {Promise<void>} Resolves when pull operation is complete
+   *
+   * @example
+   * await instance.pull('/path/to/download');
+   */
+  async pull(isPreview) {
+    this.log(
+      `✨ ${isPreview ? "Previewing" : "Pulling"} data to ${this.downloadPath}`,
+    );
+
+    for (const schemaConfig of this.accConfig.schemas) {
+      const lineCount = schemaConfig.queryDef?.lineCount || 10;
+      let startLine = 1;
+      let recordsLengthTotal = 0;
+      let recordsLengthCurrent = 0;
+      do {
+        if (this.verbose) {
+          this.log(
+            `  Querying instance for records from ${startLine} to ${startLine + lineCount - 1}...`,
+          );
+        }
+        recordsLengthCurrent = await this.downloadAndParse(
+          schemaConfig,
+          startLine,
+          lineCount,
+          isPreview,
+        );
+        startLine += lineCount;
+        recordsLengthTotal += recordsLengthCurrent;
+      } while (recordsLengthCurrent >= lineCount);
+      this.log(
+        `✅ ${schemaConfig.filename}: ${chalk.bgCyan(schemaConfig.schemaId)} ${recordsLengthTotal} records`,
+      );
+      // new line when verbose
+      if (this.verbose) {
+        this.log("");
+      }
+    }
+  }
+
+  /**
+   * Downloads records from a specific schema and saves them as XML files.
+   *
+   * @param {Object} schemaConfig - Schema download config
+   * @param {number} startLine - Starting line number for pagination
+   * @param {number} lineCount - Size of pagination
+   * @returns {Promise<number>} Number of records downloaded
+   *
+   * @example
+   * const count = await instance.download('nms:recipient', '/path/to/save', 1);
+   */
+  async downloadAndParse(schemaConfig, startLine, lineCount, isPreview) {
+    const { schemaId } = schemaConfig;
+    const baseQueryDef = {
+      schema: schemaId,
+      operation: "select",
+      select: {
+        node: [{ expr: "data" }],
+      },
+      startLine: startLine,
+      lineCount: lineCount,
+    };
+    const queryDef = this._getQueryDefForSchema(schemaConfig, baseQueryDef);
+    // console.log("queryDef", JSON.stringify(queryDef));
+    const queryDefXml = DomUtil.fromJSON("queryDef", queryDef, "SimpleJson");
+    // console.log("queryDefXml", DomUtil.toXMLString(queryDefXml));
+
+    const query = this.client.NLWS.xml.xtkQueryDef.create(queryDefXml);
+
+    let message = "";
+    var recordsLength = 0;
+    try {
+      await query.selectAll(false); // @see https://opensource.adobe.com/acc-js-sdk/xtkQueryDef.html
+      const records = await query.executeQuery(); // DOMElement <srcSchema-collection><srcSchema></srcSchema>...
+      // console.log("records", DomUtil.toXMLString(records));
+      if (this.verbose) {
+        this.log(
+          `Parsing XML Response with ${records.childElementCount} children`,
+        );
+      }
+      var child = DomUtil.getFirstChildElement(records); // @see https://opensource.adobe.com/acc-js-sdk/domHelper.html
+      while (child) {
+        recordsLength++;
+
+        this.parse(child, schemaConfig, isPreview);
+
+        child = DomUtil.getNextSiblingElement(child);
+      }
+
+      message = `${recordsLength} saved.`;
+    } catch (err) {
+      message = `⚠️ Error executing query: ${err.message}.`;
+    } finally {
+      if (this.verbose) {
+        this.log(` => ${message}`);
+      }
+    }
+    return recordsLength;
+  }
+
+  /**
+   * manual xpath to return the last Element
+   * - abc/def => def
+   * - abc/def/@ghi => def
+   *
+   * @param {Element} element
+   * @param {string} xpath
+   * @return Element
+   */
+  _getLastElement(element, xpath) {
+    let childTraverse = element;
+    xpath.split(this.CONFIG_XPATH_SEP).forEach((xp) => {
+      if (xp.startsWith(this.CONFIG_XPATH_ATTR)) {
+        return;
+      }
+      childTraverse = DomUtil.getFirstChildElement(childTraverse, xp);
+    });
+    return childTraverse;
+  }
+
+  parse(childElement, schemaConfig, isPreview) {
+    // console.log(`>>> parse with isPreview:${isPreview}`);
+    const { filename, decompose, excludeXPaths } = schemaConfig;
+    const configAttributes = this._getAttributesFromSchemaConfig(schemaConfig); // [ '@name', '@namespace' ]
+
+    const computedFilename = this._computeFilename(
+      filename,
+      configAttributes,
+      childElement,
+    );
+    const filenameOnly = path.basename(computedFilename);
+    const datapath = path.join(this.downloadPath, computedFilename);
+
+    // prepare XML by removing excluded attributes
+    if (excludeXPaths) {
+      for (let xpath of excludeXPaths) {
+        const chunks = xpath.split(this.CONFIG_XPATH_SEP);
+        const childTraverse = this._getLastElement(childElement, xpath);
+
+        // remove attribute
+        if (xpath.includes(this.CONFIG_XPATH_ATTR)) {
+          const attribute = chunks[chunks.length - 1];
+          const attributeName = attribute.replace(this.CONFIG_XPATH_ATTR, "");
+          if (!childTraverse.hasAttribute(attributeName)) {
+            continue;
+          }
+          childTraverse.setAttribute(attributeName, "");
+        }
+        // remove element
+        else {
+        }
+      }
+    }
+
+    // no decomposition: save raw XML
+    if (!decompose) {
+      const raw = DomUtil.toXMLString(childElement);
+      if (!isPreview) {
+        fs.outputFileSync(datapath, raw);
+      }
+    }
+    // with decomposition: save each xpath, then save the clean meta
+    else {
+      // 1. save each xpath + removeElement
+      for (const [xpath, filenameTemplate] of Object.entries(decompose)) {
+        try {
+          // compute filename
+          const decomposedFilename = this._computeFilename(
+            filenameTemplate,
+            configAttributes,
+            childElement,
+          );
+          // then traverse xpath
+          let childTraverse = this._getLastElement(childElement, xpath);
+          const elementValue = DomUtil.elementValue(childTraverse);
+          // save to file
+          const datapath = path.join(this.downloadPath, decomposedFilename);
+          if (!isPreview) {
+            fs.outputFileSync(datapath, elementValue);
+          }
+          const decomposedFilenameOnly = path.basename(decomposedFilename);
+          if (this.verbose) {
+            this.log(`${chalk.underline(decomposedFilenameOnly)} `, false);
+          }
+          // removeElement
+          if (childTraverse) {
+            childTraverse.textContent = ""; // @since 0.5.1, instead of removeChild that removed attributes
+          }
+        } catch (err) {
+          this.log(`(⚠️ warning:parse ${err.message})`);
+        }
+      }
+      // 2. save meta
+      const metaContent = DomUtil.toXMLString(childElement);
+      if (!isPreview) {
+        fs.outputFileSync(datapath, metaContent);
+      }
+    }
+
+    if (this.verbose) {
+      this.log(`${chalk.underline(filenameOnly)} `, false);
+    }
+  }
+
+  _getAttributesFromSchemaConfig(schemaConfig) {
+    const configAttributesRe = schemaConfig.filename.matchAll(
+      this.REGEX_CONFIG_ATTRIBUTE,
+    ); // [object RegExp String Iterator]
+    const configAttributesArr = Array.from(configAttributesRe); // [ [ '@name', '@name' ], ... ]
+    return configAttributesArr.map((attr) => attr[1]); // [ '@name', '@namespace' ]
+  }
+
+  _computeFilename(configFilename, configAttributes, record) {
+    var filename = configFilename;
+    for (let configAttribute of configAttributes) {
+      const value = DomUtil.getAttributeAsString(
+        record,
+        configAttribute.replace(this.CONFIG_XPATH_ATTR, ""),
+      );
+      filename = filename.replace(`{${configAttribute}}`, value);
+    }
+    return filename;
+  }
+
+  /**
+   * Saves SOAP request to archive file with timestamp.
+   *
+   * @param {string} rawRequest - Raw SOAP request XML
+   * @returns {void}
+   *
+   * @example
+   * instance.saveArchiveRequest('<soap:Envelope>...</soap:Envelope>');
+   */
+  saveArchiveRequest(rawRequest) {
+    const archiveRequest =
+      "archives/" + this.getArchiveDate() + "-CampaignInstance-request.xml";
+    fs.outputFileSync(archiveRequest, rawRequest, function (errFs) {
+      throw errFs;
+    });
+  }
+
+  /**
+   * Saves SOAP response to archive file with timestamp.
+   *
+   * @param {string} rawResponse - Raw SOAP response XML
+   * @returns {void}
+   *
+   * @example
+   * instance.saveArchiveResponse('<soap:Envelope>...</soap:Envelope>');
+   */
+  saveArchiveResponse(rawResponse) {
+    const archiveResponse =
+      "archives/" + this.getArchiveDate() + "-CampaignInstance-response.xml";
+    fs.outputFileSync(archiveResponse, rawResponse, function (errFs) {
+      throw errFs;
+    });
+  }
+
+  /**
+   * Generates timestamp string for archive files in format: YYYY/MM/DD/HH-mm-ss_ms
+   *
+   * @returns {string} Formatted timestamp string
+   *
+   * @example
+   * const timestamp = instance.getArchiveDate(); // "2023/01/15/14-30-45_123"
+   */
+  getArchiveDate() {
+    var ts_hms = new Date();
+
+    return (
+      ts_hms.getFullYear() +
+      "/" +
+      ("0" + (ts_hms.getMonth() + 1)).slice(-2) +
+      "/" +
+      ("0" + ts_hms.getDate()).slice(-2) +
+      "/" +
+      ("0" + ts_hms.getHours()).slice(-2) +
+      "-" +
+      ("0" + ts_hms.getMinutes()).slice(-2) +
+      "-" +
+      ("0" + ts_hms.getSeconds()).slice(-2) +
+      "_" +
+      ts_hms.getMilliseconds()
+    );
+  }
+
+  log(text, newLine = true) {
+    if (newLine) {
+      console.log(text);
+    } else {
+      process.stdout.write(text);
+    }
+  }
+}
+
+export default CampaignInstance;