sounding 0.0.3 → 0.1.0

package/lib/create-helper-runner.js

@@ -1,15 +1,41 @@
+const { createSoundingError } = require('./create-error')
+
+/** @typedef {import('./types').AnyRecord} AnyRecord */
+/** @typedef {import('./types').SoundingHelperRunner} SoundingHelperRunner */
+/** @typedef {import('./types').SoundingSailsApp} SoundingSailsApp */
+
+/**
+ * @param {SoundingSailsApp} sails
+ * @param {string} identity
+ * @returns {any}
+ */
 function resolveHelper(sails, identity) {
   return identity
     .split('.')
     .reduce((current, segment) => current?.[segment], sails.helpers)
 }
 
+/**
+ * @param {{ sails: SoundingSailsApp }} input
+ * @returns {SoundingHelperRunner}
+ */
 function createHelperRunner({ sails }) {
+  /**
+   * @param {string} identity
+   * @param {AnyRecord} [inputs]
+   * @returns {Promise<any>}
+   */
   async function invoke(identity, inputs = {}) {
     const helper = resolveHelper(sails, identity)
 
     if (!helper) {
-      throw new Error(`Unknown Sounding helper: ${identity}`)
+      throw createSoundingError({
+        code: 'E_SOUNDING_HELPER_UNKNOWN',
+        message: `Unknown Sounding helper: ${identity}`,
+        details: {
+          identity,
+        },
+      })
     }
 
     if (typeof helper.with === 'function') {
@@ -20,9 +46,19 @@ function createHelperRunner({ sails }) {
       return helper(inputs)
     }
 
-    throw new Error(`Sounding helper \`${identity}\` is not callable.`)
+    throw createSoundingError({
+      code: 'E_SOUNDING_HELPER_NOT_CALLABLE',
+      message: `Sounding helper \`${identity}\` is not callable.`,
+      details: {
+        identity,
+      },
+    })
   }
 
+  /**
+   * @param {string[]} [path]
+   * @returns {SoundingHelperRunner}
+   */
   function buildProxy(path = []) {
     const callable = async (...args) => {
       if (path.length === 0) {

package/lib/create-mail-capture.js

@@ -1,6 +1,21 @@
 const path = require('node:path')
 const url = require('node:url')
-
+const { createSoundingError } = require('./create-error')
+const { getTrialContext } = require('./trial-context')
+
+const DEFAULT_MAIL_LAYOUT = 'mail'
+const mailCaptureRegistry = new WeakMap()
+
+/** @typedef {import('./types').AnyRecord} AnyRecord */
+/** @typedef {import('./types').SoundingMailCapture} SoundingMailCapture */
+/** @typedef {import('./types').SoundingMailbox} SoundingMailbox */
+/** @typedef {import('./types').SoundingMailMessage} SoundingMailMessage */
+/** @typedef {import('./types').SoundingSailsApp} SoundingSailsApp */
+
+/**
+ * @param {any} value
+ * @returns {any[]}
+ */
 function normalizeList(value) {
   if (value === undefined || value === null || value === '') {
     return []
@@ -20,6 +35,10 @@ function normalizeList(value) {
   return [value]
 }
 
+/**
+ * @param {string | undefined} html
+ * @returns {string[]}
+ */
 function extractLinks(html) {
   if (!html) {
     return []
@@ -29,6 +48,11 @@ function extractLinks(html) {
   return [...matches].map((match) => match[1])
 }
 
+/**
+ * @param {AnyRecord} [inputs]
+ * @param {string[]} [links]
+ * @returns {string | undefined}
+ */
 function resolvePrimaryLink(inputs = {}, links = []) {
   const templateData = inputs.templateData || {}
   const preferredKeys = [
@@ -50,6 +74,10 @@ function resolvePrimaryLink(inputs = {}, links = []) {
   return links.find((link) => !/\/unsubscribe\b/i.test(link)) || links[0]
 }
 
+/**
+ * @param {any} view
+ * @returns {Promise<string | undefined>}
+ */
 function createRenderViewPromise(view) {
   if (!view) {
     return Promise.resolve(undefined)
@@ -62,22 +90,28 @@ function createRenderViewPromise(view) {
   return Promise.resolve(view)
 }
 
-async function renderTemplatePreview(sails, {
-  template,
-  templateData = {},
-  layout = 'layout-email',
-}) {
+/**
+ * @param {SoundingSailsApp} sails
+ * @param {AnyRecord} [inputs]
+ * @param {AnyRecord} [options]
+ * @returns {Promise<string | undefined>}
+ */
+async function renderTemplatePreview(sails, inputs = {}, options = {}) {
+  const { template, templateData = {} } = inputs
+
   if (!template || typeof sails?.renderView !== 'function') {
     return undefined
   }
 
+  const resolvedLayout = resolvePreviewLayout(sails, inputs, options)
   const emailTemplatePath = path.join('emails/', template)
+  /** @type {string | false} */
   let emailTemplateLayout = false
 
-  if (layout) {
+  if (resolvedLayout) {
     emailTemplateLayout = path.relative(
       path.dirname(emailTemplatePath),
-      path.resolve('layouts/', layout)
+      path.resolve('layouts/', resolvedLayout)
     )
   }
 
@@ -90,10 +124,50 @@ async function renderTemplatePreview(sails, {
   )
 }
 
+/**
+ * @param {SoundingSailsApp} sails
+ * @returns {AnyRecord}
+ */
 function resolveMailConfig(sails) {
   return sails?.config?.mail || {}
 }
 
+/**
+ * @param {SoundingSailsApp} sails
+ * @param {AnyRecord} [options]
+ * @returns {AnyRecord}
+ */
+function resolveSoundingMailConfig(sails, options = {}) {
+  if (options.mailSettings) {
+    return options.mailSettings
+  }
+
+  const soundingConfig =
+    options.soundingConfig || options.config || sails?.config?.sounding || {}
+
+  return soundingConfig.mail || {}
+}
+
+/**
+ * @param {SoundingSailsApp} sails
+ * @param {AnyRecord} [inputs]
+ * @param {AnyRecord} [options]
+ * @returns {string | false | undefined}
+ */
+function resolvePreviewLayout(sails, inputs = {}, options = {}) {
+  if (Object.prototype.hasOwnProperty.call(inputs, 'layout')) {
+    return inputs.layout
+  }
+
+  const mailSettings = resolveSoundingMailConfig(sails, options)
+
+  if (Object.prototype.hasOwnProperty.call(mailSettings, 'layout')) {
+    return mailSettings.layout
+  }
+
+  return DEFAULT_MAIL_LAYOUT
+}
+
 function resolveMailerName(sails, inputs = {}) {
   return inputs.mailer || process.env.MAIL_MAILER || resolveMailConfig(sails).default
 }
@@ -125,10 +199,17 @@ function toErrorShape(error) {
   }
 }
 
-async function buildCapturedMail(sails, inputs = {}) {
+/**
+ * @param {SoundingSailsApp} sails
+ * @param {AnyRecord} [inputs]
+ * @param {AnyRecord} [options]
+ * @returns {Promise<SoundingMailMessage>}
+ */
+async function buildCapturedMail(sails, inputs = {}, options = {}) {
   const mailer = resolveMailerName(sails, inputs)
   const transport = resolveTransportName(sails, mailer)
-  const html = await renderTemplatePreview(sails, inputs)
+  const layout = resolvePreviewLayout(sails, inputs, options)
+  const html = await renderTemplatePreview(sails, inputs, options)
   const links = extractLinks(html)
 
   return {
@@ -150,10 +231,14 @@ async function buildCapturedMail(sails, inputs = {}) {
     ctaUrl: resolvePrimaryLink(inputs, links),
     attachments: inputs.attachments || [],
     headers: inputs.headers || {},
-    layout: inputs.layout === undefined ? 'layout-email' : inputs.layout,
+    layout,
   }
 }
 
+/**
+ * @param {{ sails?: SoundingSailsApp, mailbox: SoundingMailbox, getConfig?: () => AnyRecord }} input
+ * @returns {SoundingMailCapture}
+ */
 function createMailCapture({ sails, mailbox, getConfig }) {
   let originalSend = null
 
@@ -164,15 +249,30 @@ function createMailCapture({ sails, mailbox, getConfig }) {
     return soundingConfig.mail || {}
   }
 
+  function resolveCaptureTarget() {
+    const context = getTrialContext()
+
+    return {
+      mailbox: context?.mailbox || mailbox,
+      mailSettings: context?.getConfig?.().mail || resolveMailSettings(),
+    }
+  }
+
   function isEnabled() {
     return resolveMailSettings().capture !== false
   }
 
   function shouldPassthrough() {
-    const settings = resolveMailSettings()
+    const settings = resolveCaptureTarget().mailSettings
     return settings.deliver === true || settings.mode === 'passthrough'
   }
 
+  function resolveMessageLayout(inputs = {}) {
+    return resolvePreviewLayout(sails, inputs, {
+      mailSettings: resolveCaptureTarget().mailSettings,
+    })
+  }
+
   function wrapDeferred(executor, onRejected) {
     let promise = Promise.resolve().then(executor)
 
@@ -250,7 +350,10 @@ function createMailCapture({ sails, mailbox, getConfig }) {
       return sendHelper.with.bind(sendHelper)
     }
 
-    throw new Error('Sounding could not invoke `sails.helpers.mail.send`.')
+    throw createSoundingError({
+      code: 'E_SOUNDING_MAIL_SEND_UNAVAILABLE',
+      message: 'Sounding could not invoke `sails.helpers.mail.send`.',
+    })
   }
 
   function resolveWithInvoker(sendHelper) {
@@ -262,23 +365,31 @@ function createMailCapture({ sails, mailbox, getConfig }) {
       return sendHelper.bind(sendHelper)
     }
 
-    throw new Error('Sounding could not invoke `sails.helpers.mail.send.with()`.')
+    throw createSoundingError({
+      code: 'E_SOUNDING_MAIL_SEND_WITH_UNAVAILABLE',
+      message: 'Sounding could not invoke `sails.helpers.mail.send.with()`.',
+    })
   }
 
   async function captureSuccessfulSend(inputs = {}) {
+    const target = resolveCaptureTarget()
+
     try {
-      const message = await buildCapturedMail(sails, inputs)
-      mailbox.capture({
+      const message = await buildCapturedMail(sails, inputs, {
+        mailSettings: target.mailSettings,
+      })
+      target.mailbox.capture({
         ...message,
         status: 'sent',
       })
     } catch (error) {
-      mailbox.capture({
+      target.mailbox.capture({
         mailer: resolveMailerName(sails, inputs),
         transport: resolveTransportName(sails, resolveMailerName(sails, inputs)),
         to: normalizeList(inputs.to),
         subject: inputs.subject || '',
         template: inputs.template,
+        layout: resolveMessageLayout(inputs),
         status: 'sent',
         captureError: toErrorShape(error),
       })
@@ -286,10 +397,13 @@ function createMailCapture({ sails, mailbox, getConfig }) {
   }
 
   async function captureFailedSend(inputs = {}, error) {
+    const target = resolveCaptureTarget()
     let message
 
     try {
-      message = await buildCapturedMail(sails, inputs)
+      message = await buildCapturedMail(sails, inputs, {
+        mailSettings: target.mailSettings,
+      })
     } catch (captureError) {
       message = {
         mailer: resolveMailerName(sails, inputs),
@@ -297,11 +411,12 @@ function createMailCapture({ sails, mailbox, getConfig }) {
         to: normalizeList(inputs.to),
         subject: inputs.subject || '',
         template: inputs.template,
+        layout: resolveMessageLayout(inputs),
         captureError: toErrorShape(captureError),
       }
     }
 
-    mailbox.capture({
+    target.mailbox.capture({
       ...message,
       status: 'failed',
       error: toErrorShape(error),
@@ -347,27 +462,60 @@ function createMailCapture({ sails, mailbox, getConfig }) {
       return false
     }
 
-    const sendHelper = sails?.helpers?.mail?.send
+    const mailHelpers = sails?.helpers?.mail
+    const sendHelper = mailHelpers?.send
     if (!sendHelper) {
       return false
     }
 
-    if (sendHelper.__soundingWrapped) {
-      originalSend = sendHelper.__soundingOriginal || originalSend
+    const registered = mailCaptureRegistry.get(mailHelpers) || sendHelper.__soundingRegistry
+    if (registered && sendHelper === registered.wrappedSend) {
+      registered.installs += 1
+      originalSend = registered.originalSend
+      mailCaptureRegistry.set(mailHelpers, registered)
       return true
     }
 
     originalSend = sendHelper
-    sails.helpers.mail.send = wrapSendHelper(sendHelper)
+    const wrappedSend = wrapSendHelper(sendHelper)
+    const registry = {
+      originalSend,
+      wrappedSend,
+      installs: 1,
+    }
+
+    Object.defineProperty(wrappedSend, '__soundingRegistry', {
+      value: registry,
+      configurable: true,
+    })
+
+    mailCaptureRegistry.set(mailHelpers, registry)
+    mailHelpers.send = wrappedSend
     return true
   }
 
   function uninstall() {
-    if (!originalSend || !sails?.helpers?.mail) {
+    const mailHelpers = sails?.helpers?.mail
+
+    if (!originalSend || !mailHelpers) {
       return false
     }
 
-    sails.helpers.mail.send = originalSend
+    const registered = mailCaptureRegistry.get(mailHelpers)
+
+    if (registered && registered.originalSend === originalSend) {
+      registered.installs -= 1
+
+      if (registered.installs <= 0) {
+        mailHelpers.send = originalSend
+        mailCaptureRegistry.delete(mailHelpers)
+      }
+
+      originalSend = null
+      return true
+    }
+
+    mailHelpers.send = originalSend
     originalSend = null
     return true
   }
@@ -388,4 +536,5 @@ module.exports = {
   normalizeList,
   resolvePrimaryLink,
   renderTemplatePreview,
+  resolvePreviewLayout,
 }

package/lib/create-mailbox.js

@@ -1,7 +1,18 @@
+/** @typedef {import('./types').SoundingMailbox} SoundingMailbox */
+/** @typedef {import('./types').SoundingMailMessage} SoundingMailMessage */
+
+/**
+ * @returns {SoundingMailbox}
+ */
 function createMailbox() {
+  /** @type {SoundingMailMessage[]} */
   const messages = []
 
   return {
+    /**
+     * @param {SoundingMailMessage} message
+     * @returns {SoundingMailMessage}
+     */
     capture(message) {
       const normalized = {
         capturedAt: new Date().toISOString(),
@@ -11,14 +22,23 @@ function createMailbox() {
       return normalized
     },
 
+    /**
+     * @returns {SoundingMailMessage[]}
+     */
     all() {
       return [...messages]
     },
 
+    /**
+     * @returns {SoundingMailMessage | undefined}
+     */
     latest() {
       return messages.at(-1)
     },
 
+    /**
+     * @returns {void}
+     */
     clear() {
       messages.length = 0
     },