@mindful-web/marko-web-postup 1.61.3

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/api-client.js

@@ -0,0 +1,152 @@
+const debug = require('debug')('postup:api');
+const fetch = require('node-fetch');
+
+class PostUpApiClient {
+  /**
+   * @param {string} credentials
+   */
+  constructor(credentials) {
+    if (!credentials) throw new Error('Unable to use the PostUp API without credentials.');
+    this.headers = {
+      'content-type': 'application/json',
+      authorization: `Basic ${credentials}`,
+    };
+  }
+
+  /**
+   * @param {string} endpoint
+   * @param {object} opts fetch options
+   * @returns {Promise<object>}
+   */
+  async request(endpoint, opts = {}) {
+    const method = opts.method || 'post';
+    const { headers } = this;
+    const url = `https://api.postup.com/api/${endpoint}`;
+    const r = await fetch(url, { method, headers, ...opts || {} });
+    const response = await r.json();
+    const dbg = {
+      req: { url, ...{ method, headers, ...opts || {} } },
+      res: { headers: r.headers.raw(), body: response },
+    };
+    if (!r.ok) {
+      debug(`${method.toUpperCase()} ${url} ${r.status} ERR`, dbg);
+      if (response.message) throw new Error(response.message);
+      throw new Error(`API request was unsuccessful: ${r.status} ${r.statusText}`);
+    }
+    debug(`${method.toUpperCase()} ${url} ${r.status} OK`, dbg);
+    return response;
+  }
+
+  /**
+   * Creates a recipient and sets idx external id
+   * @see https://apidocs.postup.com/docs/subscription-management
+   *
+   * @param {string} email
+   * @param {string} externalId
+   * @param {?string} [ip]
+   * @returns {Promise}
+   */
+  async createRecipient(email, externalId, ip) {
+    return this.request('recipient', {
+      body: JSON.stringify({
+        address: email,
+        externalId,
+        channel: 'E',
+        sourceDescription: 'IdentityX',
+        signupIP: ip,
+      }),
+    });
+  }
+
+  /**
+   * Retrieves subscription info for the supplied recipient
+   * @see https://apidocs.postup.com/docs/return-a-single-recipients-list-subscription
+   *
+   * @param {string} recipientId
+   * @returns {Promise<ListSubscription[]>}
+   */
+  async listSubscriptionsForRecipient(recipientId) {
+    const params = new URLSearchParams({ recipid: recipientId });
+    return this.request(`listsubscription?${params}`, { method: 'get' });
+  }
+
+  /**
+   * Retrieves a recipient by email address
+   * @see https://apidocs.postup.com/docs/retrieve-recipient-data
+   *
+   * @param {string} email
+   * @returns {Promise<Recipient>}
+   */
+  async returnRecipientDataByEmailAddress(email) {
+    const params = new URLSearchParams({ address: email });
+    return this.request(`recipient?${params}`, { method: 'get' });
+  }
+
+  /**
+   * Updates recipient data (fields, demographics, etc)
+   * @see https://apidocs.postup.com/docs/update-existing-recipient-data
+   *
+   * @param {string} recipientId
+   * @param {string} email
+   * @param {string[]} demographics
+   * @returns {Promise}
+   */
+  updateRecipient(recipientId, email, demographics) {
+    return this.request(`recipient/${recipientId}`, {
+      method: 'put',
+      body: JSON.stringify({
+        address: email,
+        demographics,
+      }),
+    });
+  }
+
+  /**
+   * Updates recipient externalId
+   * @see https://apidocs.postup.com/docs/update-existing-recipient-data
+   *
+   * @param {string} recipientId The PostUp recipient id
+   * @param {string} externalId The IdentityX user id
+   * @returns {Promise}
+   */
+  updateRecipientExternalId(recipientId, externalId) {
+    return this.request(`recipient/${recipientId}`, {
+      method: 'put',
+      body: JSON.stringify({ externalId }),
+    });
+  }
+
+  /**
+   * Updates a list subscription for a recipient
+   * @see https://apidocs.postup.com/docs/subscribe-recipient-to-a-list
+   * @see https://apidocs.postup.com/docs/unsubscribe-recipient-from-a-list
+   *
+   * @param {string} recipientId
+   * @param {string} listId
+   * @param {boolean} value
+   * @returns {Promise}
+   */
+  async updateSubscription(recipientId, listId, value) {
+    return this.request('listsubscription', {
+      body: JSON.stringify({
+        listId,
+        recipientId,
+        status: value ? 'NORMAL' : 'UNSUB',
+      }),
+    });
+  }
+}
+
+module.exports = PostUpApiClient;
+
+/**
+ * @typedef ListSubscription
+ * @prop {Number} recipientId
+ * @prop {Number} listId
+ * @prop {ListSubscriptionStatus} status
+ * @prop {ListSubscriptionStatus} listStatus
+ * @prop {ListSubscriptionStatus} globalStatus
+ * @prop {Boolean} confirmed
+ *
+ * @typedef {("NORMAL"|"UNSUB")} ListSubscriptionStatus
+ */

package/env.js

@@ -0,0 +1,7 @@
+const { cleanEnv, validators } = require('@mindful-web/env');
+
+const { nonemptystr } = validators;
+
+module.exports = cleanEnv(process.env, {
+  POSTUP_API_CREDENTIALS: nonemptystr({ desc: 'The PostUp API credentials.' }),
+});

package/hooks/index.js

@@ -0,0 +1,51 @@
+const onAuthenticationSuccess = require('./on-authentication-success');
+const onLoginLinkSent = require('./on-login-link-sent');
+const onUserProfileUpdate = require('./on-user-profile-update');
+
+/**
+ *
+ * @param {import('../index').IdentityXConfiguration} idxConfig
+ * @param {PostUpService} postUp
+ */
+module.exports = (idxConfig, postUp) => {
+  if (idxConfig.postupInstalled) return;
+  idxConfig.addHook({
+    name: 'onUserProfileUpdate',
+    shouldAwait: false,
+    fn: (args) => onUserProfileUpdate({ postUp, ...args }),
+  });
+
+  idxConfig.addHook({
+    name: 'onLoginLinkSent',
+    shouldAwait: false,
+    fn: (args) => onLoginLinkSent({ postUp, ...args }),
+  });
+
+  idxConfig.addHook({
+    name: 'onAuthenticationSuccess',
+    shouldAwait: true,
+    fn: (args) => onAuthenticationSuccess({ postUp, ...args }),
+  });
+  // eslint-disable-next-line no-param-reassign
+  idxConfig.postupInstalled = true;
+};
+
+/**
+ * @typedef {import('@mindful-web/marko-web-identity-x/service')} IdentityXService
+ * @typedef {import('../service')} PostUpService
+ * @typedef {import('../index').PostUpConfig} PostUpConfig
+ * @typedef {import('../index').PostUpRequest} PostUpRequest
+ *
+ * @typedef IdentityXUser
+ * @prop {String} id
+ * @prop {String} email
+ * @prop {import('@mindful-web/marko-web-identity-x/service').ExternalId[]} externalIds
+ *
+ * @typedef IdentityXHookArgs
+ * @prop {Object} additionalEventData
+ * @prop {Object} authToken
+ * @prop {PostUpService} postUp
+ * @prop {IdentityXService} service
+ * @prop {IdentityXUser} user
+ * @prop {String} loginSource
+ * */

package/hooks/on-authentication-success.js

@@ -0,0 +1,16 @@
+/**
+ * @param {import("./index").IdentityXHookArgs} args
+ */
+module.exports = async ({
+  // loginSource,
+  postUp,
+  service,
+  user,
+}) => {
+  await postUp.ensureUser(user, service);
+
+  // Auto-subscribe the user if this is the first successful authentication
+  // if (loginSource === 'newsletterSignup' && user.verifiedCount === 1) {
+  //   await postUp.defaultListOptIns(service, user);
+  // }
+};

package/hooks/on-login-link-sent.js

@@ -0,0 +1,22 @@
+/**
+ * @param {import("./index").IdentityXHookArgs} args
+ */
+module.exports = async ({
+  // additionalEventData,
+  postUp,
+  service,
+  user,
+}) => {
+  // Attempt to import user data to IdentityX
+  if (user && !user.verified) {
+    await postUp.updateIdentityXData(user, service);
+    await postUp.defaultListOptIns(service, user);
+  }
+
+  // If the user has already verified and is coming from nl signup, sign them up to the default list
+  // if (user && user.verified && additionalEventData.actionSource === 'newsletterSignup') {
+  //   await postUp.defaultListOptIns(service, user);
+  // }
+
+  return user;
+};

package/hooks/on-user-profile-update.js

@@ -0,0 +1,15 @@
+/**
+ * @param {import("./index").IdentityXHookArgs} args
+ */
+module.exports = async ({
+  // additionalEventData,
+  postUp,
+  user,
+  service,
+}) => {
+  await postUp.ensureUser(user, service);
+
+  await postUp.updatePostUpData(user, service);
+
+  return user;
+};

package/index.js

@@ -0,0 +1,72 @@
+const { get } = require('@mindful-web/object-path');
+
+/* eslint-disable max-len */
+const Joi = require('@parameter1/joi');
+const { validate } = require('@parameter1/joi/utils');
+const PostUp = require('./service');
+const hooks = require('./hooks');
+
+/**
+ * @param {import("express").Application} app
+ * @param {IdentityXConfiguration} idxConfig
+ * @param {PostUpConfig} params
+ *
+ * @returns {PostUpConfig}
+ */
+
+module.exports = (app, idxConfig, params = {}) => {
+  const args = validate(Joi.object({
+    defaultListQuestionIds: Joi.array().items(Joi.string().pattern(/[a-f0-9]{24}/i)).required(),
+    fieldMap: Joi.object().default({
+      // PostUp standard fields
+      FirstName: 'givenName',
+      LastName: 'familyName',
+      _Address1: 'street',
+      _Address2: 'addressExtra',
+      _City: 'city',
+      _Country: 'countryCode',
+      _CountryCode: 'countryCode',
+      _HomePhone: 'phoneNumber',
+      _PostalCode: 'postalCode',
+      _State: 'regionCode',
+      // PostUp custom fields
+      companyname: 'organization',
+      title: 'organizationTitle',
+    }).description('The PostUp fields that should be mapped to IdentityX fields.'),
+  }), params);
+
+  app.use((req, res, next) => {
+    // Install service
+    const service = new PostUp({ ...args, cookies: req.cookies || {} });
+    req.PostUp = service;
+    res.locals.PostUp = service;
+
+    // Install custom handler for content metering
+    // eslint-disable-next-line no-param-reassign
+    app.locals.contentBypassGatingHandler = ({ content }) => {
+      // Skip metering if we already have an IdX identity
+      const idt = req.identityX.getIdentity(res);
+      if (idt) return true;
+
+      // Skip metering if we have a constant contact email param
+      if (req.query.pu_ext_id) return true;
+
+      // Fall back to default behavior
+      return get(content, 'userRegistration.bypassGating', false);
+    };
+
+    // Install hooks
+    hooks(idxConfig, service);
+    next();
+  });
+};
+
+/**
+ * @typedef {import('@mindful-web/marko-web-identity-x/config')} IdentityXConfiguration
+ * @typedef PostUpConfig
+ * @prop {Array} defaultListQuestionIds Array of object ids representing the default subscription questions
+ * @prop {Object} fieldMap An object representing how fields should map from PostUp to IdentityX.
+ *
+ * @typedef PostUpRequest
+ * @prop {PostUp} postUp
+ */

package/middleware/set-identity-cookie.js

@@ -0,0 +1,27 @@
+const { asyncRoute } = require('@mindful-web/utils');
+
+/**
+ * @typedef OIDXRequest
+ * @prop {import('@mindful-web/marko-web-identity-x/service')} identityX
+ *
+ * @typedef MiddlewareConstructor
+ */
+module.exports = asyncRoute(async (req, res, next) => {
+  /** @type {OIDXRequest} */
+  const { identityX: idx } = req;
+  const cookie = idx.getIdentity(res);
+
+  // Don't overwrite an existing cookie
+  if (cookie) return next();
+
+  // get oly enc id. if we don't have one, bail
+  const postUpId = req.query.pu_ext_id;
+  if (!postUpId) return next();
+
+  // Look up idx user by pu_ext_id or our idx mongoID
+  const identity = await idx.findUserById(postUpId);
+  if (identity) {
+    idx.setIdentityCookie(identity.id);
+  }
+  return next();
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@mindful-web/marko-web-postup",
+  "version": "1.61.3",
+  "author": "Josh Worden <josh@parameter1.com>",
+  "repository": "https://github.com/parameter1/mindful-web/tree/main/packages/marko-web-postup",
+  "license": "MIT",
+  "scripts": {
+    "lint": "eslint --ext .js --ext .vue --max-warnings 5 --config ../../.eslintrc.js --ignore-path ../../.eslintignore ./",
+    "lint:fix": "yarn lint --fix",
+    "test": "yarn lint"
+  },
+  "dependencies": {
+    "@mindful-web/env": "^1.0.0",
+    "@mindful-web/marko-web-identity-x": "^1.60.0",
+    "@mindful-web/object-path": "^1.57.0",
+    "@mindful-web/utils": "^1.57.0",
+    "@parameter1/joi": "^1.2.10",
+    "debug": "^4.1.1",
+    "express": "^4.17.1",
+    "graphql-tag": "^2.12.6",
+    "newrelic": "^9.10.2",
+    "node-fetch": "^2.6.1"
+  },
+  "engines": {
+    "node": ">=14.15"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "713b78883a51d0bcce2e82d84cf361353fa4823a"
+}

package/service.js

@@ -0,0 +1,339 @@
+const debug = require('debug')('postup:service');
+const gql = require('graphql-tag');
+const { get, getAsArray } = require('@mindful-web/object-path');
+const { POSTUP_API_CREDENTIALS } = require('./env');
+const { filterByExternalId, filterFieldsByExternalId } = require('./utils');
+const PostUpApiClient = require('./api-client');
+
+const SET_DATA = gql`
+mutation SetPostUpData($input: SetAppUserUnverifiedDataMutationInput!) {
+  setAppUserUnverifiedData(input: $input) { id }
+}
+`;
+
+const SET_SELECT_FIELD_ANSWERS = gql`
+  mutation SetPostUpSelectFieldAnswers($input: UpdateAppUserCustomSelectAnswersMutationInput!) {
+    updateAppUserCustomSelectAnswers(input: $input) { id }
+  }
+`;
+
+const SET_BOOLEAN_FIELD_ANSWERS = gql`
+  mutation SetPostUpBooleanFieldAnswers($input: UpdateAppUserCustomBooleanAnswersMutationInput!) {
+    updateAppUserCustomBooleanAnswers(input: $input) { id }
+  }
+`;
+
+class PostUp {
+  /**
+   * @param {string} defaultListQuestionIds The array of default lists for auto-signups
+   * @param {object} fieldMap A mapping of postup>identityx field keys
+   */
+  constructor({
+    defaultListQuestionIds,
+    fieldMap = {},
+    tenant = 'transpire',
+  } = {}) {
+    this.defaultListQuestionIds = defaultListQuestionIds;
+    this.fieldMap = Object.entries(fieldMap).reduce((map, [key, value]) => {
+      map.set(key, value);
+      return map;
+    }, new Map());
+    this.tenant = tenant;
+    this.client = new PostUpApiClient(POSTUP_API_CREDENTIALS);
+  }
+
+  /**
+   * Writes PostUp-supplied user data to IdentityX
+   *
+   * @param {import('./hooks').IdentityXUser} user
+   * @param {IdentityXService} idx The IdentityX user service
+   * @returns {Promise<any>}
+   */
+  async updateIdentityXData(user, idx) {
+    // Don't overwrite verified user data
+    if (user.verified) return;
+
+    const [userData = {}] = await this.getUserByEmail(user.email);
+    if (!userData || !userData.recipientId) {
+      await this.ensureUser(user, idx);
+      return;
+    }
+
+    const { demographics = [], recipientId } = userData;
+
+    debug('updateIdentityXData.externalId', recipientId);
+    await this.setExternalIds(idx, user.id, recipientId);
+
+    const demoData = demographics.reduce((o, kv) => {
+      const [k, v] = kv.split('=');
+      return { ...o, [k]: v };
+    }, {});
+
+    // Update root fields
+    const payload = Object.entries(demoData).reduce((o, [k, v]) => ({
+      ...o,
+      ...(this.fieldMap.has(k) && v && {
+        [this.fieldMap.get(k)]: v,
+      }),
+    }), { email: user.email });
+
+    debug('updateIdentityXData.data', payload);
+    await idx.client.mutate({
+      context: { apiToken: idx.getOrgUserApiToken() },
+      mutation: SET_DATA,
+      variables: { input: payload },
+    });
+
+    // Update custom selects
+    const questions = filterFieldsByExternalId(getAsArray(user, 'customSelectFieldAnswers'), 'demographic');
+    const customSelectFieldAnswers = questions.reduce((arr, ans) => {
+      // Don't overwrite previously set answers
+      if (!ans.hasAnswered) {
+        const key = `${get(ans, 'field.externalId.identifier.value')}`.toLocaleLowerCase();
+        const { id: fieldId } = ans.field;
+        if (demoData[key]) {
+          // find the answer, set the value
+          const found = ans.field.options.find((opt) => opt.externalIdentifier === demoData[key]);
+          if (found) arr.push({ fieldId, optionIds: [found.id] });
+        }
+      }
+      return arr;
+    }, []);
+
+    debug('updateIdentityXData.selects', customSelectFieldAnswers);
+    if (customSelectFieldAnswers.length) {
+      await idx.client.mutate({
+        context: { apiToken: idx.getOrgUserApiToken() },
+        mutation: SET_SELECT_FIELD_ANSWERS,
+        variables: {
+          input: {
+            id: user.id,
+            answers: customSelectFieldAnswers,
+          },
+        },
+      });
+    }
+
+    const subs = await this.client.listSubscriptionsForRecipient(recipientId);
+
+    const subscriptions = filterFieldsByExternalId(getAsArray(user, 'customBooleanFieldAnswers'), 'list');
+    const customBooleanFieldAnswers = subscriptions.reduce((arr, ans) => {
+      const listId = get(ans, 'field.externalId.identifier.value');
+      const match = subs.find((sub) => sub.listId === parseInt(listId, 10));
+      if (match) arr.push({ fieldId: ans.field.id, value: match.status === 'NORMAL' });
+      return arr;
+    }, []);
+
+    debug('updateIdentityXData.bools', customBooleanFieldAnswers);
+    if (customBooleanFieldAnswers.length) {
+      await idx.client.mutate({
+        context: { apiToken: idx.getOrgUserApiToken() },
+        mutation: SET_BOOLEAN_FIELD_ANSWERS,
+        variables: {
+          input: {
+            id: user.id,
+            answers: customBooleanFieldAnswers,
+          },
+        },
+      });
+    }
+  }
+
+  /**
+   * Writes user-supplied IdentityX data to PostUp
+   *
+   * @param {import('./hooks').IdentityXUser} user
+   * @returns {Promise<any>}
+   */
+  async updatePostUpData(user) {
+    const demographics = [...this.fieldMap.entries()].reduce((o, [p, i]) => ({
+      ...o,
+      [p]: get(user, i),
+    }), {});
+
+    // External ID tagged questions
+    const questions = filterFieldsByExternalId(getAsArray(user, 'customSelectFieldAnswers'), 'demographic');
+    questions.forEach((ans) => {
+      if (ans.hasAnswered) {
+        const key = get(ans, 'field.externalId.identifier.value');
+        const answers = getAsArray(ans, 'answers').map((a) => a.writeInValue || a.externalIdentifier);
+        demographics[key] = ans.field.multiple ? answers.join(',') : answers.pop();
+      }
+    });
+
+    // Update Postup with the user data and demographics
+    await this.updateRecipient(user, demographics);
+
+    const answers = filterFieldsByExternalId(getAsArray(user, 'customBooleanFieldAnswers'), 'list');
+    const subscriptions = answers.reduce((map, answer) => {
+      const id = get(answer, 'field.externalId.identifier.value');
+      map.set(`${id}`, answer.value);
+      return map;
+    }, new Map());
+
+    // Update Postup with user subscriptions
+    await this.updateSubscriptions(user, subscriptions);
+  }
+
+  /**
+   * Ensure the user has been sent to postup.
+   *
+   * @param {import('./hooks').IdentityXUser} user
+   * @param {IdentityXService} idx The IdentityX user service
+   * @returns {Promise<any>}
+   */
+  async ensureUser(user, idx) {
+    // 1. Check IdentityX user externalIds for postup recipient id, bail if found
+    const found = filterByExternalId(user.externalIds, 'recipient');
+    if (found && found.length) return user;
+
+    // 2. Attempt to look up by email address. If found, push externalId to IdX/PostUp users
+    const data = await this.getUserByEmail(user.email);
+    const recipientId = get(data, '0.recipientId');
+    if (recipientId) return this.setExternalIds(idx, user.id, recipientId);
+
+    // 3. Create user. Push externalId to IdX user
+    return this.createRecipient(user.email, user.id, idx);
+  }
+
+  /**
+   * Sets the IdentityX externalId
+   *
+   * @param {IdentityXService} idx The IdentityX user service
+   * @param {string} userId The IdentityX user id
+   * @param {string} externalId The PostUp recipient id
+   * @return {Promise}
+   */
+  async setExternalIds(idx, userId, externalId) {
+    return Promise.all([
+      idx.addExternalUserId({
+        userId,
+        identifier: { value: `${externalId}` },
+        namespace: { provider: 'postup', tenant: this.tenant, type: 'recipient' },
+      }),
+      this.client.updateRecipientExternalId(externalId, userId),
+    ]);
+  }
+
+  /**
+   * Subscribes a user to the default list.
+   *
+   * @param {IdentityXService} idx The IdentityX user service
+   * @param {import('./hooks').IdentityXUser} user The IdentityX user object
+   */
+  async defaultListOptIns(idx, user) {
+    const subscriptions = filterFieldsByExternalId(getAsArray(user, 'customBooleanFieldAnswers'), 'list');
+
+    const recipientId = await this.getRecipientId(user);
+
+    const answers = new Map();
+    const postUpSupscritions = subscriptions.reduce((map, a) => {
+      const id = get(a, 'field.id');
+      const externalId = get(a, 'field.externalId.identifier.value');
+      if (this.defaultListQuestionIds.includes(id)) {
+        map.set(`${externalId}`, true);
+        answers.set(`${id}`, { fieldId: id, value: true });
+      }
+      return map;
+    }, new Map());
+
+    debug('defaultListOptIn', {
+      user: user.id,
+      recipientId,
+      postUpSupscritions,
+      answers: [...answers.values()],
+    });
+    await Promise.all([
+      // Update Postup with user subscriptions by default
+      await this.updateSubscriptions(user, postUpSupscritions),
+      // Set question value in IdentityX
+      idx.client.mutate({
+        context: { apiToken: idx.getOrgUserApiToken() },
+        mutation: SET_BOOLEAN_FIELD_ANSWERS,
+        variables: {
+          input: {
+            id: user.id,
+            answers: [...answers.values()],
+          },
+        },
+      }),
+    ]);
+  }
+
+  /**
+   * Returns the PostUp id for the supplied user
+   *
+   * @param {import('./hooks').IdentityXUser} user
+   * @returns {Promise<string>}
+   */
+  async getRecipientId(user) {
+    const { email } = user;
+    const extIds = filterByExternalId(user.externalIds, 'recipient');
+    const extId = get(extIds, '0.identifier.value');
+    if (extId) return extId;
+
+    const data = await this.getUserByEmail(email);
+    const found = get(data, '0.recipientId');
+    if (found) return found;
+
+    throw new Error(`Unable to find a recipient id for IdentityX user "${user.id}".`);
+  }
+
+  /**
+   * Updates recipient data (fields, demographics, etc)
+   *
+   * @param {import('./hooks').IdentityXUser} user
+   * @param {object} demographics
+   * @returns {Promise<any>}
+   */
+  async updateRecipient(user, demographics) {
+    const { email } = user;
+    const formatted = Object.keys(demographics).reduce((arr, k) => {
+      arr.push(`${k}=${demographics[k]}`);
+      return arr;
+    }, []);
+    const recipientId = await this.getRecipientId(user);
+    return this.client.updateRecipient(recipientId, email, formatted);
+  }
+
+  /**
+   * @param {import('./hooks').IdentityXUser} user
+   * @param {Map<string, boolean>} subscriptions
+   */
+  async updateSubscriptions(user, subscriptions) {
+    const recipientId = await this.getRecipientId(user);
+    return Promise.all(
+      [...subscriptions].map(async ([id, v]) => this.client.updateSubscription(recipientId, id, v)),
+    );
+  }
+
+  /**
+   * Retrieves a recipient by email address
+   *
+   * @param {string} email
+   * @returns {Promise<Recipient>}
+   */
+  async getUserByEmail(email) {
+    return this.client.returnRecipientDataByEmailAddress(email);
+  }
+
+  /**
+   * Creates a recipient and sets idx external id
+   *
+   * @param {string} email
+   * @param {string} externalId
+   * @param {IdentityXService} idx
+   * @returns {Promise}
+   */
+  async createRecipient(email, externalId, idx) {
+    const ip = idx.req.header('cf-connecting-ip') || idx.req.ip;
+    const created = await this.client.createRecipient(email, externalId, ip);
+    return this.setExternalIds(idx, externalId, `${created.recipientId}`);
+  }
+}
+
+module.exports = PostUp;
+
+/**
+ * @typedef {import("@mindful-web/marko-web-identity-x/service")} IdentityXService
+ */

package/utils.js

@@ -0,0 +1,12 @@
+const { getAsObject } = require('@mindful-web/object-path');
+
+module.exports = {
+  filterByExternalId: (arr, type) => arr.filter((v) => {
+    const ns = getAsObject(v, 'namespace');
+    return ns.provider === 'postup' && ns.type === type && ns.tenant === 'transpire';
+  }),
+  filterFieldsByExternalId: (arr, type) => arr.filter((v) => {
+    const ns = getAsObject(v, 'field.externalId.namespace');
+    return ns.provider === 'postup' && ns.type === type && ns.tenant === 'transpire';
+  }),
+};