sounding 0.0.4 → 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,8 +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 []
@@ -22,6 +35,10 @@ function normalizeList(value) {
   return [value]
 }
 
+/**
+ * @param {string | undefined} html
+ * @returns {string[]}
+ */
 function extractLinks(html) {
   if (!html) {
     return []
@@ -31,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 = [
@@ -52,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)
@@ -64,6 +90,12 @@ function createRenderViewPromise(view) {
   return Promise.resolve(view)
 }
 
+/**
+ * @param {SoundingSailsApp} sails
+ * @param {AnyRecord} [inputs]
+ * @param {AnyRecord} [options]
+ * @returns {Promise<string | undefined>}
+ */
 async function renderTemplatePreview(sails, inputs = {}, options = {}) {
   const { template, templateData = {} } = inputs
 
@@ -73,6 +105,7 @@ async function renderTemplatePreview(sails, inputs = {}, options = {}) {
 
   const resolvedLayout = resolvePreviewLayout(sails, inputs, options)
   const emailTemplatePath = path.join('emails/', template)
+  /** @type {string | false} */
   let emailTemplateLayout = false
 
   if (resolvedLayout) {
@@ -91,10 +124,19 @@ async function renderTemplatePreview(sails, inputs = {}, options = {}) {
   )
 }
 
+/**
+ * @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
@@ -106,6 +148,12 @@ function resolveSoundingMailConfig(sails, options = {}) {
   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
@@ -151,6 +199,12 @@ function toErrorShape(error) {
   }
 }
 
+/**
+ * @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)
@@ -181,6 +235,10 @@ async function buildCapturedMail(sails, inputs = {}, options = {}) {
   }
 }
 
+/**
+ * @param {{ sails?: SoundingSailsApp, mailbox: SoundingMailbox, getConfig?: () => AnyRecord }} input
+ * @returns {SoundingMailCapture}
+ */
 function createMailCapture({ sails, mailbox, getConfig }) {
   let originalSend = null
 
@@ -191,18 +249,27 @@ 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: resolveMailSettings(),
+      mailSettings: resolveCaptureTarget().mailSettings,
     })
   }
 
@@ -283,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) {
@@ -295,20 +365,25 @@ 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, {
-        mailSettings: resolveMailSettings(),
+        mailSettings: target.mailSettings,
       })
-      mailbox.capture({
+      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),
@@ -322,11 +397,12 @@ function createMailCapture({ sails, mailbox, getConfig }) {
   }
 
   async function captureFailedSend(inputs = {}, error) {
+    const target = resolveCaptureTarget()
     let message
 
     try {
       message = await buildCapturedMail(sails, inputs, {
-        mailSettings: resolveMailSettings(),
+        mailSettings: target.mailSettings,
       })
     } catch (captureError) {
       message = {
@@ -340,7 +416,7 @@ function createMailCapture({ sails, mailbox, getConfig }) {
       }
     }
 
-    mailbox.capture({
+    target.mailbox.capture({
       ...message,
       status: 'failed',
       error: toErrorShape(error),
@@ -386,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
   }

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
     },