@mindful-web/marko-newsletters-email-x 1.0.0

package/.eslintignore

@@ -0,0 +1 @@
+*.marko.js

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Parameter1 LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/components/data.marko

@@ -0,0 +1,30 @@
+import { warn } from "@mindful-web/utils";
+import { getAsObject, getAsArray } from "@mindful-web/object-path";
+import fetchData from "../utils/fetch-data";
+
+$ const { onError } = input;
+$ const adUnit = getAsObject(input, "adUnit");
+$ const params = getAsObject(input, "params");
+$ const decodedParams = getAsArray(input, "decodedParams");
+
+$ const { uri, id } = adUnit;
+$ const {
+  email,
+  date,
+  send,
+  includeAdvertiser,
+} = params;
+
+$ const promise = fetchData({
+  serveUri: uri,
+  adUnitId: id,
+  date,
+  email,
+  send,
+  includeAdvertiser,
+  decodedParams,
+});
+
+<marko-web-resolve|{ resolved }| promise=promise>
+  <${input.renderBody} response=resolved ad-unit=adUnit />
+</marko-web-resolve>

package/components/data.marko.js

@@ -0,0 +1,75 @@
+// Compiled using marko@4.20.2 - DO NOT EDIT
+"use strict";
+
+var marko_template = module.exports = require("marko/dist/html").t(__filename),
+    marko_componentType = "/@mindful-web/marko-newsletters-email-x$1.0.0/components/data.marko",
+    marko_component = require("./data.marko"),
+    marko_renderer = require("marko/dist/runtime/components/renderer"),
+    module_utils_module = require("@mindful-web/utils"),
+    utils_module = module_utils_module.default || module_utils_module,
+    warn = module_utils_module.warn,
+    module_objectPath_module = require("@mindful-web/object-path"),
+    objectPath_module = module_objectPath_module.default || module_objectPath_module,
+    getAsObject = module_objectPath_module.getAsObject,
+    getAsArray = module_objectPath_module.getAsArray,
+    module_fetchData = require("../utils/fetch-data"),
+    fetchData = module_fetchData.default || module_fetchData,
+    marko_dynamicTag = require("marko/dist/runtime/helpers/dynamic-tag"),
+    marko_web_resolve_template = require("@mindful-web/marko-core/components/resolve.marko"),
+    marko_loadTag = require("marko/dist/runtime/helpers/load-tag"),
+    marko_web_resolve_tag = marko_loadTag(marko_web_resolve_template);
+
+function render(input, out, __component, component, state) {
+  var data = input;
+
+  const { onError } = input;
+
+  const adUnit = getAsObject(input, "adUnit");
+
+  const params = getAsObject(input, "params");
+
+  const decodedParams = getAsArray(input, "decodedParams");
+
+  const { uri, id } = adUnit;
+
+  const {
+  email,
+  date,
+  send,
+  includeAdvertiser,
+} = params;
+
+  const promise = fetchData({
+  serveUri: uri,
+  adUnitId: id,
+  date,
+  email,
+  send,
+  includeAdvertiser,
+  decodedParams,
+});
+
+  marko_web_resolve_tag({
+      promise: promise,
+      renderBody: function(out, { resolved }) {
+        marko_dynamicTag(out, input.renderBody, function() {
+          return {
+              response: resolved,
+              "ad-unit": adUnit
+            };
+        }, null, null, null, __component, "1");
+      }
+    }, out, __component, "0");
+}
+
+marko_template._ = marko_renderer(render, {
+    e_: marko_componentType
+  }, marko_component);
+
+marko_template.meta = {
+    id: "/@mindful-web/marko-newsletters-email-x$1.0.0/components/data.marko",
+    component: "./data.marko",
+    tags: [
+      "@mindful-web/marko-core/components/resolve.marko"
+    ]
+  };

package/components/display.marko

@@ -0,0 +1,38 @@
+import { warn } from "@mindful-web/utils";
+import { getAsObject, getAsArray } from "@mindful-web/object-path";
+import moment from "moment";
+import buildUrl from "../utils/build-url";
+import buildQuery from "../utils/build-query";
+
+$ const adUnit = getAsObject(input, "adUnit");
+$ const params = getAsObject(input, "params");
+$ const decodedParams = getAsArray(input, "decodedParams");
+
+$ const { uri, id, width, height, name, alias } = adUnit;
+$ const { email, date, send } = params;
+
+$ const momentDate = moment(date);
+$ if (!momentDate.isValid()) warn("The EmailX date parameter is invalid.");
+
+$ const canDisplay = Boolean(uri && id && email && momentDate.isValid());
+
+$ const query = buildQuery({ momentDate, email, send });
+$ const href = buildUrl({ action: "click", uri, id, query, decodedParams });
+$ const src = buildUrl({ action: "image", uri, id, query, decodedParams });
+$ const imageAttrs = {
+  ...getAsObject(input.image, "attrs"),
+  width,
+  height,
+};
+$ const classNames = [`email-x-${alias}-${name}`, input.class];
+
+<if(canDisplay)>
+  <div ...input.attrs class=classNames>
+    <marko-core-img ...input.image src=src attrs=imageAttrs>
+      <@link target="_blank" ...input.link href=href />
+    </marko-core-img>
+  </div>
+</if>
+<else>
+  $ warn("Unable to render EmailX ad unit: a required input property is missing.");
+</else>

package/components/display.marko.js

@@ -0,0 +1,92 @@
+// Compiled using marko@4.20.2 - DO NOT EDIT
+"use strict";
+
+var marko_template = module.exports = require("marko/dist/html").t(__filename),
+    marko_componentType = "/@mindful-web/marko-newsletters-email-x$1.0.0/components/display.marko",
+    marko_renderer = require("marko/dist/runtime/components/renderer"),
+    module_utils_module = require("@mindful-web/utils"),
+    utils_module = module_utils_module.default || module_utils_module,
+    warn = module_utils_module.warn,
+    module_objectPath_module = require("@mindful-web/object-path"),
+    objectPath_module = module_objectPath_module.default || module_objectPath_module,
+    getAsObject = module_objectPath_module.getAsObject,
+    getAsArray = module_objectPath_module.getAsArray,
+    module_moment = require("moment"),
+    moment = module_moment.default || module_moment,
+    module_buildUrl = require("../utils/build-url"),
+    buildUrl = module_buildUrl.default || module_buildUrl,
+    module_buildQuery = require("../utils/build-query"),
+    buildQuery = module_buildQuery.default || module_buildQuery,
+    marko_assign = require("marko/dist/runtime/helpers/assign"),
+    marko_core_img_template = require("@mindful-web/marko-core/components/elements/img.marko"),
+    marko_loadTag = require("marko/dist/runtime/helpers/load-tag"),
+    marko_core_img_tag = marko_loadTag(marko_core_img_template),
+    marko_mergeAttrs = require("marko/dist/runtime/html/helpers/merge-attrs");
+
+function render(input, out, __component, component, state) {
+  var data = input;
+
+  const adUnit = getAsObject(input, "adUnit");
+
+  const params = getAsObject(input, "params");
+
+  const decodedParams = getAsArray(input, "decodedParams");
+
+  const { uri, id, width, height, name, alias } = adUnit;
+
+  const { email, date, send } = params;
+
+  const momentDate = moment(date);
+
+  if (!momentDate.isValid()) warn("The EmailX date parameter is invalid.");
+
+  const canDisplay = Boolean(uri && id && email && momentDate.isValid());
+
+  const query = buildQuery({ momentDate, email, send });
+
+  const href = buildUrl({ action: "click", uri, id, query, decodedParams });
+
+  const src = buildUrl({ action: "image", uri, id, query, decodedParams });
+
+  const imageAttrs = {
+  ...getAsObject(input.image, "attrs"),
+  width,
+  height,
+};
+
+  const classNames = [`email-x-${alias}-${name}`, input.class];
+
+  if (canDisplay) {
+    out.w("<div" +
+      marko_mergeAttrs(input.attrs, {
+        class: classNames
+      }) +
+      ">");
+
+    marko_core_img_tag(marko_assign({}, input.image, {
+        src: src,
+        attrs: imageAttrs,
+        link: marko_assign({
+            target: "_blank"
+          }, input.link, {
+            href: href
+          })
+      }), out, __component, "1");
+
+    out.w("</div>");
+  } else {
+    warn("Unable to render EmailX ad unit: a required input property is missing.");
+  }
+}
+
+marko_template._ = marko_renderer(render, {
+    d_: true,
+    e_: marko_componentType
+  });
+
+marko_template.meta = {
+    id: "/@mindful-web/marko-newsletters-email-x$1.0.0/components/display.marko",
+    tags: [
+      "@mindful-web/marko-core/components/elements/img.marko"
+    ]
+  };

package/components/marko.json

@@ -0,0 +1,58 @@
+{
+  "<marko-newsletters-email-x-display>": {
+    "template": "./display.marko",
+    "<ad-unit>": {
+      "@uri": "string",
+      "@id": "string",
+      "@width": "number",
+      "@height": "number",
+      "@name": "string",
+      "@alias": "string"
+    },
+    "<params>": {
+      "@email": "string",
+      "@date": "date",
+      "@send": "string"
+    },
+    "<link>": {},
+    "<image>": {},
+    "@decoded-params":  "array",
+    "@class": "string",
+    "@attrs": "object"
+  },
+  "<marko-newsletters-email-x-data>": {
+    "template": "./data.marko",
+    "<ad-unit>": {
+      "@uri": "string",
+      "@id": "string"
+    },
+    "<params>": {
+      "@email": "string",
+      "@date": "date",
+      "@send": "string",
+      "@include-advertiser": "boolean"
+    },
+    "@decoded-params":  "array"
+  },
+  "<marko-newsletters-email-x-render>": {
+    "template": "./render.marko",
+    "<response>": {
+      "<data>": {
+        "<ad>": {
+          "@height": "number",
+          "@mindfulCreativeId": "string",
+          "@width": "number"
+        }
+      },
+      "@imageSrc": "string"
+    },
+    "<link>": {
+      "@href": "string",
+      "@attrs": "object"
+    },
+    "<image>": {
+      "@attrs": "object",
+      "@class": "string"
+    }
+  }
+}

package/components/render.marko

@@ -0,0 +1,37 @@
+import { getAsObject, get } from "@mindful-web/object-path";
+
+$ const response = getAsObject(input, "response");
+$ const { ad, elements } = response.data;
+$ const imageSrc = get(input, "response.imageSrc");
+$ const adImageSrc = get(ad, "image.src") || imageSrc;
+
+$ const imageAttrs = {
+  ...getAsObject(input, "image.attrs"),
+  width: ad.width,
+  height: ad.height,
+};
+
+$ const mindfulCreativeId = get(response, "data.ad.mindfulCreativeId");
+$ let mindfulTenant;
+$ try {
+  [, mindfulTenant] = imageSrc.match(/^https:\/\/delivery\.mindfulcms\.com\/(\w+\/\w+)\//);
+} catch (e) {
+  // Explicitly throw, native email-x delivery is no longer supported.
+  throw new Error(`Unable to parse mindful tenant from image url ${imageSrc}`);
+}
+$ if (!mindfulCreativeId) throw new Error('Unable to parse mindful creative id from response.');
+
+$ const linkAttrs = {
+  href: ad.url,
+  ...(getAsObject(input, "link")),
+  attrs: {
+    ...(getAsObject(input, "link.attrs")),
+    "data-mindful-tenant": mindfulTenant,
+    "data-mindful-creative-id": mindfulCreativeId,
+    ...elements.a,
+  },
+};
+
+<marko-core-img ...input.image src=adImageSrc attrs=imageAttrs>
+  <@link target="_blank" ...linkAttrs />
+</marko-core-img>

package/components/render.marko.js

@@ -0,0 +1,76 @@
+// Compiled using marko@4.20.2 - DO NOT EDIT
+"use strict";
+
+var marko_template = module.exports = require("marko/dist/html").t(__filename),
+    marko_componentType = "/@mindful-web/marko-newsletters-email-x$1.0.0/components/render.marko",
+    marko_renderer = require("marko/dist/runtime/components/renderer"),
+    module_objectPath_module = require("@mindful-web/object-path"),
+    objectPath_module = module_objectPath_module.default || module_objectPath_module,
+    getAsObject = module_objectPath_module.getAsObject,
+    get = module_objectPath_module.get,
+    marko_assign = require("marko/dist/runtime/helpers/assign"),
+    marko_core_img_template = require("@mindful-web/marko-core/components/elements/img.marko"),
+    marko_loadTag = require("marko/dist/runtime/helpers/load-tag"),
+    marko_core_img_tag = marko_loadTag(marko_core_img_template);
+
+function render(input, out, __component, component, state) {
+  var data = input;
+
+  const response = getAsObject(input, "response");
+
+  const { ad, elements } = response.data;
+
+  const imageSrc = get(input, "response.imageSrc");
+
+  const adImageSrc = get(ad, "image.src") || imageSrc;
+
+  const imageAttrs = {
+  ...getAsObject(input, "image.attrs"),
+  width: ad.width,
+  height: ad.height,
+};
+
+  const mindfulCreativeId = get(response, "data.ad.mindfulCreativeId");
+
+  let mindfulTenant;
+
+  try {
+  [, mindfulTenant] = imageSrc.match(/^https:\/\/delivery\.mindfulcms\.com\/(\w+\/\w+)\//);
+} catch (e) {
+  // Explicitly throw, native email-x delivery is no longer supported.
+  throw new Error(`Unable to parse mindful tenant from image url ${imageSrc}`);
+}
+
+  if (!mindfulCreativeId) throw new Error('Unable to parse mindful creative id from response.');
+
+  const linkAttrs = {
+  href: ad.url,
+  ...(getAsObject(input, "link")),
+  attrs: {
+    ...(getAsObject(input, "link.attrs")),
+    "data-mindful-tenant": mindfulTenant,
+    "data-mindful-creative-id": mindfulCreativeId,
+    ...elements.a,
+  },
+};
+
+  marko_core_img_tag(marko_assign({}, input.image, {
+      src: adImageSrc,
+      attrs: imageAttrs,
+      link: marko_assign({
+          target: "_blank"
+        }, linkAttrs)
+    }), out, __component, "0");
+}
+
+marko_template._ = marko_renderer(render, {
+    d_: true,
+    e_: marko_componentType
+  });
+
+marko_template.meta = {
+    id: "/@mindful-web/marko-newsletters-email-x$1.0.0/components/render.marko",
+    tags: [
+      "@mindful-web/marko-core/components/elements/img.marko"
+    ]
+  };

package/config.js

@@ -0,0 +1,80 @@
+const { asArray } = require('@mindful-web/utils');
+const { set, getAsObject } = require('@mindful-web/object-path');
+
+class EmailXConfiguration {
+  /**
+   *
+   * @param {string} uri
+   * @param {object} params
+   */
+  constructor(uri) {
+    if (!uri) throw new Error('Unable to configure EmailX: no URI was provided.');
+    this.uri = uri;
+    this.adUnits = {};
+  }
+
+  /**
+   *
+   * @param {object} params
+   * @param {string} params.name  The ad unit name, e.g. `primary` or `header`, etc.
+   * @param {string} params.alias The ad unit deployment alias, e.g. `some-deployment-alias`.
+   */
+  getAdUnit({ name, alias } = {}) {
+    const foundAdUnit = getAsObject(this.adUnits, `${alias}.${name}`);
+    // Ensure ad unit is duplicated so property re-assignment doesn't "stick."
+    return {
+      uri: this.uri,
+      ...foundAdUnit,
+    };
+  }
+
+  /**
+   *
+   * @param {object} params
+   * @param {string} params.alias The ad unit deployment alias, e.g. `some-deployment-alias`.
+   * @param {string} params.name The ad unit name, e.g. `primary` or `header`, etc.
+   * @param {string} params.id The ad unit id, e.g. `5d4b04769f69b200013ab109`.
+   * @param {number} params.width The ad unit width.
+   * @param {number} params.height The ad unit height.
+   * @param {string} [params.uri] A custom delivery URI for this adunit
+   */
+  setAdUnit({
+    alias,
+    name,
+    id,
+    width,
+    height,
+    uri,
+  } = {}) {
+    if (!name || !alias || !id) throw new Error('Unable to create EmailX ad unit: the name, alias, and ID are required');
+    if (!width || !height) throw new Error('Unable to create EmailX ad unit: the height and width are required');
+    const adUnit = {
+      id,
+      width,
+      height,
+      name,
+      alias,
+    };
+    if (uri) adUnit.uri = uri;
+    set(this.adUnits, `${alias}.${name}`, adUnit);
+    return this;
+  }
+
+  /**
+   *
+   * @param {string} alias
+   * @param {object[]} definitions
+   */
+  setAdUnits(alias, definitions) {
+    asArray(definitions).forEach((definition) => {
+      this.setAdUnit({ ...definition, alias });
+    });
+    return this;
+  }
+
+  getUri() {
+    return this.uri;
+  }
+}
+
+module.exports = EmailXConfiguration;

package/marko.json

@@ -0,0 +1,6 @@
+{
+  "taglib-id": "@mindful-web/marko-newsletters-email-x",
+  "taglib-imports": [
+    "./components/marko.json"
+  ]
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@mindful-web/marko-newsletters-email-x",
+  "version": "1.0.0",
+  "description": "EmailX Marko components for Mindful Web newsletters.",
+  "author": "Jacob Bare <jacob@parameter1.com>",
+  "license": "MIT",
+  "repository": "https://github.com/parameter1/mindful-web/tree/main/packages/marko-newsletters-email-x",
+  "scripts": {
+    "lint:fix": "yarn lint --fix",
+    "lint": "eslint --ext .js --max-warnings 5 ./",
+    "compile": "mindful-web-marko-compile compile",
+    "prepublish": "yarn compile --silent",
+    "test": "yarn compile --no-clean && yarn lint"
+  },
+  "dependencies": {
+    "@mindful-web/object-path": "^1.0.0",
+    "@mindful-web/utils": "^1.0.0",
+    "moment": "^2.29.1",
+    "node-fetch": "^2.6.9"
+  },
+  "peerDependencies": {
+    "@mindful-web/marko-core": "^0.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "0b77cab713eb5841202bb86c7119949866bc68b5"
+}

package/utils/build-query.js

@@ -0,0 +1,25 @@
+/**
+ * Builds the EmailX ad unit query string.
+ *
+ * @param {object} params
+ * @param {moment} params.momentDate The moment date of the deployment
+ * @param {string} params.email The email address query var
+ * @param {string} [param.send] The send corrlator var
+ * @param {bool}   [param.includeAdvertiser] Flag indicating if the advertiser data should be
+ *                 returned in the response. Defaults to false.
+ */
+module.exports = ({
+  momentDate,
+  email,
+  send,
+  includeAdvertiser = false,
+} = {}) => {
+  const rand = Math.floor(Math.random() * 100000000);
+  return {
+    date: momentDate.format('YYYY-MM-DDTHH:mm:ssZ'),
+    rand,
+    email,
+    send,
+    ...(includeAdvertiser && { incAdv: true }),
+  };
+};

package/utils/build-url.js

@@ -0,0 +1,20 @@
+const { asArray, asObject } = require('@mindful-web/utils');
+
+module.exports = ({
+  uri,
+  action,
+  id,
+  query,
+  decodedParams,
+} = {}) => {
+  const q = asObject(query);
+  const noEncode = asArray(decodedParams);
+  const search = Object.keys(q).reduce((pairs, key) => {
+    const v = q[key];
+    if (!v) return pairs;
+    const value = noEncode.includes(key) ? v : encodeURIComponent(v);
+    pairs.push(`${encodeURIComponent(key)}=${value}`);
+    return pairs;
+  }, []).join('&');
+  return `${uri}/${action}/${id}?${search}`;
+};

package/utils/fetch-data.js

@@ -0,0 +1,68 @@
+const fetch = require('node-fetch');
+const moment = require('moment');
+const { asArray } = require('@mindful-web/utils');
+const buildQuery = require('./build-query');
+const buildUrl = require('./build-url');
+
+/**
+ * Retrieves ad unit data from the EmailX delivery service
+ *
+ * @param {object} params
+ * @param {string} params.serveUri The EmailX base URI, e.g. https://ebm.serve.email-x.io
+ * @param {string} params.adUnitId The ad unit to request data for
+ * @param {Date} params.date The newsletter deployment date
+ * @param {string} params.email The email address for delivery correlation
+ * @param {string} [params.send] The send param for delivery correlation
+ * @param {string[]} [params.decodedParams] Params to leave unencoded when build the query string
+ * @param {object} [params.fetchOptions] Optional params to send to fetch
+ */
+module.exports = async ({
+  serveUri,
+  adUnitId,
+  date,
+  email,
+  send,
+  includeAdvertiser = false,
+  decodedParams,
+  fetchOptions,
+} = {}) => {
+  if (!serveUri) throw new Error('The EmailX serveUri param is required.');
+  if (!email) throw new Error('The EmailX email param is required.');
+  if (!adUnitId || !/^[a-f0-9]{24}$/i.test(adUnitId)) throw new Error(`The provided EmailX adUnitId '${adUnitId}' is invalid.`);
+  const momentDate = moment(date);
+  if (!momentDate.isValid()) throw new Error(`The provided EmailX date '${date}' is invalid.`);
+
+  const query = buildQuery({
+    momentDate,
+    email,
+    send,
+    includeAdvertiser,
+  });
+
+  const buildParams = {
+    uri: serveUri,
+    id: adUnitId,
+    query,
+    decodedParams: asArray(decodedParams),
+  };
+
+  const url = buildUrl({ action: 'data', ...buildParams });
+  const clickHref = buildUrl({ action: 'click', ...buildParams });
+  const imageSrc = buildUrl({ action: 'image', ...buildParams });
+
+  const res = await fetch(url, fetchOptions);
+  const { status } = res;
+  if (status === 204) return null;
+  if (!res.ok) {
+    const error = new Error(`Unable to load ad unit data: ${res.statusText} (${status})`);
+    error.res = res;
+    throw error;
+  }
+  const data = await res.json();
+  return {
+    fetchUrl: url,
+    clickHref,
+    imageSrc,
+    data,
+  };
+};