@foxtware/mineral 0.1.36 → 0.1.37

package/.creds.yml.sample

@@ -140,6 +140,15 @@ salesforce:
   CLIENT_SECRET: _________________________
   LOGIN_URL: https://login.salesforce.com  # or My Domain / test.salesforce.com
 
+marketingcloud:
+  # Salesforce Marketing Cloud > Setup > Installed Packages > API Integration (server-to-server)
+  CLIENT_ID: _____________________________
+  CLIENT_SECRET: _________________________
+  AUTH_URL: https://________.auth.marketingcloudapis.com/
+  REST_URL: https://________.rest.marketingcloudapis.com/
+  SOAP_URL: https://________.soap.marketingcloudapis.com/  # optional
+  ACCOUNT_ID: ____________________________  # optional business unit MID
+
 fastsimon:
   store:                                   # instance name of your choice
     UUID: ________________________________ # Dashboard → Settings

package/api/marketingcloud/docs.md

@@ -0,0 +1,6 @@
+# Marketing Cloud Engagement
+
+- [Developer documentation](https://developer.salesforce.com/docs/marketing/marketing-cloud/overview)
+- [REST API](https://developer.salesforce.com/docs/marketing/marketing-cloud/references)
+
+Tenant-specific auth and REST base URLs from Installed Packages → API Integration (server-to-server). OAuth 2.0 client credentials against `{subdomain}.auth.marketingcloudapis.com`, then REST calls to `{subdomain}.rest.marketingcloudapis.com`.

package/api/marketingcloud/marketingcloud.constants.js

@@ -0,0 +1,5 @@
+const TOKEN_PATH = '/v2/token';
+
+module.exports = {
+  TOKEN_PATH,
+};

package/api/marketingcloud/marketingcloud.utils.js

@@ -0,0 +1,67 @@
+const { marketingcloudAuthGet } = require('../marketingcloud/marketingcloudAuthGet');
+const { resolveCreds } = require('../pipelineSteps');
+const {
+  FetchClient,
+  appendUrlToBase,
+  fetchClientCommonSteps,
+} = require('../utils');
+
+const useRestUrlAndAuthHeaders = async (state) => {
+  const { requestPayload, context } = state;
+  const { creds } = context;
+
+  const authResponse = await marketingcloudAuthGet({
+    credsObject: creds,
+  });
+
+  if (!authResponse?.ok) {
+    return {
+      breakChain: true,
+      response: authResponse,
+    };
+  }
+
+  const {
+    access_token,
+    rest_instance_url,
+  } = authResponse.data;
+
+  const restBase = rest_instance_url || creds.REST_URL?.replace(/\/$/, '');
+
+  if (!restBase) {
+    return {
+      breakChain: true,
+      response: {
+        ok: false,
+        error: {
+          code: 'INVALID_CREDS',
+          message: 'Provide REST_URL in creds or ensure auth returns rest_instance_url.',
+        },
+      },
+    };
+  }
+
+  return {
+    requestPayload: {
+      ...requestPayload,
+      url: appendUrlToBase(restBase, requestPayload.url),
+      headers: {
+        Authorization: `Bearer ${ access_token }`,
+        ...requestPayload.headers,
+      },
+    },
+  };
+};
+
+const marketingcloudClient = new FetchClient({
+  pipeline: [
+    resolveCreds,
+    useRestUrlAndAuthHeaders,
+    'fetch',
+    fetchClientCommonSteps.exitEarlyOnNotOk,
+  ],
+});
+
+module.exports = {
+  marketingcloudClient,
+};

package/api/marketingcloud/marketingcloudAttributesSearch.js

@@ -0,0 +1,87 @@
+// https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_contacts/searchContactAttributes.html
+
+const { ArgsWarden, valueProvided } = require('../utils');
+const { credsValidator } = require('../validators');
+const { marketingcloudClient } = require('../marketingcloud/marketingcloud.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['conditionSet', valueProvided],
+]);
+
+const marketingcloudAttributesSearch = async (
+  credsPayload,
+  conditionSet,
+  {
+    requestAttributes,
+    inspect = false,
+    fetchClient = marketingcloudClient,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    conditionSet,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const body = {
+    conditionSet,
+  };
+
+  if (requestAttributes) {
+    const attributes = Array.isArray(requestAttributes)
+      ? requestAttributes.map((item) => (
+        typeof item === 'string' ? { key: item } : item
+      ))
+      : requestAttributes;
+
+    body.request = { attributes };
+  }
+
+  return fetchClient.fetch({
+    requestPayload: {
+      method: 'post',
+      url: '/contacts/v1/attributes/search',
+      body,
+    },
+    context: {
+      credsPayload,
+    },
+    inspect,
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  marketingcloudAttributesSearch,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/marketingcloudAttributesSearch" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "marketingcloud" },
+    "conditionSet": {
+      "operator": "And",
+      "conditionSets": [],
+      "conditions": [{
+        "attribute": { "key": "MobileConnect Demographics.Mobile Number" },
+        "operator": "Equals",
+        "value": { "items": ["61412345678"] }
+      }]
+    },
+    "options": {
+      "requestAttributes": [
+        "Contact.Contact Key",
+        "MobileConnect Demographics.Mobile Number"
+      ]
+    }
+  }'
+*/

package/api/marketingcloud/marketingcloudAuthGet.js

@@ -0,0 +1,111 @@
+// https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/access-token-s2s.html
+
+const {
+  ArgsWarden,
+  appendUrlToBase,
+  credsFromPayload,
+  customFetch,
+} = require('../utils');
+const { credsValidator } = require('../validators');
+const { TOKEN_PATH } = require('../marketingcloud/marketingcloud.constants');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+]);
+
+const marketingcloudAuthGet = async (
+  credsPayload,
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const creds = await credsFromPayload(credsPayload);
+  const {
+    CLIENT_ID,
+    CLIENT_SECRET,
+    AUTH_URL,
+    ACCOUNT_ID,
+  } = creds ?? {};
+
+  if (!CLIENT_ID || !CLIENT_SECRET || !AUTH_URL) {
+    return {
+      ok: false,
+      error: {
+        code: 'INVALID_CREDS',
+        message: 'Provide CLIENT_ID, CLIENT_SECRET, and AUTH_URL for Marketing Cloud.',
+      },
+    };
+  }
+
+  const authBase = AUTH_URL.replace(/\/$/, '');
+  const tokenUrl = appendUrlToBase(authBase, TOKEN_PATH);
+
+  const body = {
+    grant_type: 'client_credentials',
+    client_id: CLIENT_ID,
+    client_secret: CLIENT_SECRET,
+  };
+
+  if (ACCOUNT_ID) {
+    body.account_id = ACCOUNT_ID;
+  }
+
+  const tokenResponse = await customFetch(tokenUrl, {
+    method: 'post',
+    body,
+  });
+
+  if (!tokenResponse.ok) {
+    return tokenResponse;
+  }
+
+  const {
+    access_token,
+    rest_instance_url,
+    soap_instance_url,
+    expires_in,
+  } = tokenResponse.data ?? {};
+
+  if (!access_token) {
+    return {
+      ok: false,
+      error: {
+        code: 'AUTH_FAILED',
+        message: 'Marketing Cloud did not return access_token.',
+        details: tokenResponse.data,
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    data: {
+      access_token,
+      rest_instance_url: rest_instance_url || creds.REST_URL?.replace(/\/$/, ''),
+      soap_instance_url: soap_instance_url || creds.SOAP_URL?.replace(/\/$/, ''),
+      expires_in,
+    },
+  };
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  marketingcloudAuthGet,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/marketingcloudAuthGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "marketingcloud" }
+  }'
+*/

package/api/marketingcloud/marketingcloudContactGet.js

@@ -0,0 +1,79 @@
+// https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_contacts/getContact.html
+
+const { ArgsWarden, actionSingleOrMultiple } = require('../utils');
+const { credsValidator } = require('../validators');
+const { marketingcloudClient } = require('../marketingcloud/marketingcloud.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['contactKey'],
+]);
+
+const marketingcloudContactGetSingle = async (
+  credsPayload,
+  contactKey,
+  {
+    inspect = false,
+    fetchClient = marketingcloudClient,
+  } = {},
+) => {
+
+  return fetchClient.fetch({
+    requestPayload: {
+      method: 'get',
+      url: `/contacts/v1/contacts/${ encodeURIComponent(contactKey) }`,
+    },
+    context: {
+      credsPayload,
+    },
+    inspect,
+  });
+};
+
+const marketingcloudContactGet = async (
+  credsPayload,
+  contactKey,
+  {
+    queueRunOptions,
+    ...options
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    contactKey,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  return actionSingleOrMultiple(
+    contactKey,
+    marketingcloudContactGetSingle,
+    (contactKeyItem) => ({
+      args: [credsPayload, contactKeyItem, options],
+    }),
+    {
+      ...(queueRunOptions ? { queueRunOptions } : {}),
+    },
+  );
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  marketingcloudContactGet,
+  marketingcloudContactGetSingle,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/marketingcloudContactGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "marketingcloud" },
+    "contactKey": "1234567890"
+  }'
+*/

package/api/marketingcloud/marketingcloudContactSearch.js

@@ -0,0 +1,87 @@
+// https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_contacts/searchContacts.html
+
+const { ArgsWarden, valueProvided } = require('../utils');
+const { credsValidator } = require('../validators');
+const { marketingcloudClient } = require('../marketingcloud/marketingcloud.utils');
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['conditionSet', valueProvided],
+]);
+
+const marketingcloudContactSearch = async (
+  credsPayload,
+  conditionSet,
+  {
+    requestAttributes,
+    inspect = false,
+    fetchClient = marketingcloudClient,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    conditionSet,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const body = {
+    conditionSet,
+  };
+
+  if (requestAttributes) {
+    const attributes = Array.isArray(requestAttributes)
+      ? requestAttributes.map((item) => (
+        typeof item === 'string' ? { key: item } : item
+      ))
+      : requestAttributes;
+
+    body.request = { attributes };
+  }
+
+  return fetchClient.fetch({
+    requestPayload: {
+      method: 'post',
+      url: '/contacts/v1/contacts/search',
+      body,
+    },
+    context: {
+      credsPayload,
+    },
+    inspect,
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  marketingcloudContactSearch,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/marketingcloudContactSearch" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "marketingcloud" },
+    "conditionSet": {
+      "operator": "And",
+      "conditionSets": [],
+      "conditions": [{
+        "attribute": { "key": "Email Addresses.Email Address" },
+        "operator": "Equals",
+        "value": { "items": ["user@example.com"] }
+      }]
+    },
+    "options": {
+      "requestAttributes": [
+        "Contact.Contact Key",
+        "Email Addresses.Email Address"
+      ]
+    }
+  }'
+*/

package/api/marketingcloud/marketingcloudSmsSubscriptionsGet.js

@@ -0,0 +1,79 @@
+// https://developer.salesforce.com/docs/marketing/marketing-cloud/references/mc_rest_sms/contactsSubscriptions.html
+
+const { ArgsWarden, ensureArray, objHasAny } = require('../utils');
+const { credsValidator } = require('../validators');
+const { marketingcloudClient } = require('../marketingcloud/marketingcloud.utils');
+
+const subscriptionsValidator = (subscriptions) => {
+  return objHasAny(subscriptions, ['mobileNumber', 'subscriberKey']);
+};
+
+const argsWarden = new ArgsWarden([
+  ['credsPayload', credsValidator],
+  ['subscriptions', subscriptionsValidator],
+]);
+
+const marketingcloudSmsSubscriptionsGet = async (
+  credsPayload,
+  subscriptions,
+  {
+    inspect = false,
+    fetchClient = marketingcloudClient,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    subscriptions,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const {
+    mobileNumber,
+    subscriberKey,
+  } = subscriptions;
+
+  const body = {};
+
+  if (mobileNumber) {
+    body.mobileNumber = ensureArray(mobileNumber);
+  }
+
+  if (subscriberKey) {
+    body.subscriberKey = ensureArray(subscriberKey);
+  }
+
+  return fetchClient.fetch({
+    requestPayload: {
+      method: 'post',
+      url: '/sms/v1/contacts/subscriptions',
+      body,
+    },
+    context: {
+      credsPayload,
+    },
+    inspect,
+  });
+};
+
+const funcApiConfig = {
+  argsWarden,
+};
+
+module.exports = {
+  marketingcloudSmsSubscriptionsGet,
+  funcApiConfig,
+};
+
+/*
+curl -X POST "http://localhost:8000/marketingcloudSmsSubscriptionsGet" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "marketingcloud" },
+    "subscriptions": {
+      "mobileNumber": ["61412345678", "61498765432"]
+    }
+  }'
+*/

package/api/peoplevox/peoplevoxItemEdit.js

@@ -1,6 +1,13 @@
 const { json2csv } = require('json-2-csv');
 const { credsValidator } = require('../validators');
-const { ensureArray, everyIfArray, ArgsWarden } = require('../utils');
+const {
+  ensureArray,
+  everyIfArray,
+  ArgsWarden,
+  arrayToChunks,
+  groupObjectsByFields,
+  actionSingleOrMultiple,
+} = require('../utils');
 const { peoplevoxClient } = require('../peoplevox/peoplevox.utils');
 const { MAX_REQUEST_ITEMS } = require('../peoplevox/peoplevox.constants');
 
@@ -11,33 +18,15 @@ const argsWarden = new ArgsWarden([
   ['itemPayload', (item) => everyIfArray(itemPayloadValidator, item)],
 ]);
 
-const peoplevoxItemEdit = async (
+const peoplevoxItemEditChunk = async (
   credsPayload,
-  itemPayload,
+  itemPayloads,
   {
     fetchClient = peoplevoxClient,
   } = {},
 ) => {
 
-  const rejectResponse = await argsWarden.responseIfRejectingArgs({
-    credsPayload,
-    itemPayload,
-  });
-  if (rejectResponse) {
-    return rejectResponse;
-  }
-
-  const csvData = await json2csv(ensureArray(itemPayload));
-
-  if (csvData.length > MAX_REQUEST_ITEMS) {
-    return {
-      ok: false,
-      error: {
-        code: 'MAX_REQUEST_ITEMS_EXCEEDED',
-        message: `Max request items exceeded. Max is ${ MAX_REQUEST_ITEMS }.`,
-      },
-    };
-  }
+  const csvData = await json2csv(itemPayloads);
 
   return fetchClient.fetch({
     requestPayload: {
@@ -56,6 +45,43 @@ const peoplevoxItemEdit = async (
   });
 };
 
+const peoplevoxItemEdit = async (
+  credsPayload,
+  itemPayload,
+  {
+    fetchClient = peoplevoxClient,
+    queueRunOptions,
+  } = {},
+) => {
+
+  const rejectResponse = await argsWarden.responseIfRejectingArgs({
+    credsPayload,
+    itemPayload,
+  });
+  if (rejectResponse) {
+    return rejectResponse;
+  }
+
+  const itemPayloads = ensureArray(itemPayload);
+
+  // Sort into buckets of matching field sets so json2csv does not pad missing keys,
+  // then chunk each bucket by max size
+  const buckets = groupObjectsByFields(itemPayloads);
+  const chunksByBucket = buckets.map((bucket) => arrayToChunks(bucket, MAX_REQUEST_ITEMS));
+  const chunks = chunksByBucket.flat();
+
+  return actionSingleOrMultiple(
+    chunks,
+    peoplevoxItemEditChunk,
+    (chunk) => ({
+      args: [credsPayload, chunk, { fetchClient }],
+    }),
+    {
+      ...(queueRunOptions ? { queueRunOptions } : {}),
+    },
+  );
+};
+
 const funcApiConfig = {
   argsWarden,
 };
@@ -75,4 +101,15 @@ curl -X POST "http://localhost:8000/peoplevoxItemEdit" \
       "Attribute7": "ATTR7"
     }
   }'
+
+Mixed field sets (grouped into separate SaveData calls):
+curl -X POST "http://localhost:8000/peoplevoxItemEdit" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "credsPayload": { "credsPath": "peoplevox" },
+    "itemPayload": [
+      { "ItemCode": "100335-CHC-L", "Attribute9": "Whatever" },
+      { "ItemCode": "100335-CHC-M", "Attribute9": "Watermelon", "Attribute10": "Werewolf" }
+    ]
+  }'
 */