sounding 0.0.3 → 0.1.0

package/lib/create-auth-helpers.js

@@ -1,15 +1,54 @@
 const { resolveAuthConfig } = require('./resolve-auth-config')
-
+const { createSoundingError } = require('./create-error')
+
+/** @typedef {import('./types').SoundingActor} SoundingActor */
+/** @typedef {import('./types').SoundingAuthHelpers} SoundingAuthHelpers */
+/** @typedef {import('./types').SoundingBrowserLoginResult} SoundingBrowserLoginResult */
+/** @typedef {import('./types').SoundingMagicLink} SoundingMagicLink */
+/** @typedef {import('./types').SoundingMailbox} SoundingMailbox */
+/** @typedef {import('./types').SoundingPage} SoundingPage */
+/** @typedef {import('./types').SoundingPasswordRequestResult} SoundingPasswordRequestResult */
+/** @typedef {import('./types').SoundingRequestMagicLinkResult} SoundingRequestMagicLinkResult */
+/** @typedef {import('./types').SoundingRequestOptions} SoundingRequestOptions */
+/** @typedef {import('./types').SoundingRequestClient} SoundingRequestClient */
+/** @typedef {import('./types').SoundingSailsApp} SoundingSailsApp */
+/** @typedef {import('./types').SoundingWorldEngine} SoundingWorldEngine */
+
+/**
+ * @param {any} value
+ * @returns {string}
+ */
 function normalizeEmail(value) {
   return String(value || '')
     .trim()
     .toLowerCase()
 }
 
+/**
+ * @param {any} value
+ * @returns {value is string}
+ */
 function looksLikeEmail(value) {
   return typeof value === 'string' && value.includes('@')
 }
 
+/**
+ * @param {string[]} values
+ * @returns {string}
+ */
+function formatAvailable(values) {
+  return values.length ? values.join(', ') : 'none'
+}
+
+/**
+ * @param {{
+ *   sails?: SoundingSailsApp,
+ *   world: SoundingWorldEngine,
+ *   mailbox: SoundingMailbox,
+ *   request: SoundingRequestClient,
+ * }} input
+ * @returns {SoundingAuthHelpers}
+ */
 function createAuthHelpers({ sails, world, mailbox, request }) {
   function getAuthConfig() {
     return resolveAuthConfig({ sails })
@@ -19,6 +58,10 @@ function createAuthHelpers({ sails, world, mailbox, request }) {
     return getAuthConfig().model
   }
 
+  /**
+   * @param {string} alias
+   * @returns {SoundingActor | null}
+   */
   function resolveWorldActor(alias) {
     if (!alias || typeof alias !== 'string') {
       return null
@@ -34,20 +77,50 @@ function createAuthHelpers({ sails, world, mailbox, request }) {
     )
   }
 
+  /**
+   * @returns {string[]}
+   */
+  function availableWorldActors() {
+    const auth = getAuthConfig()
+    const aliases = new Set()
+
+    for (const collection of [auth.worldCollection, 'users', 'creators']) {
+      const entries = world.current?.[collection]
+
+      if (entries && typeof entries === 'object' && !Array.isArray(entries)) {
+        for (const alias of Object.keys(entries)) {
+          aliases.add(alias)
+        }
+      }
+    }
+
+    return Array.from(aliases).sort()
+  }
+
+  /**
+   * @param {string} email
+   * @param {string} [fullName]
+   * @returns {Promise<Record<string, any>>}
+   */
   async function createUserFromEmail(email, fullName) {
     const auth = getAuthConfig()
     const User = getAuthModel()
 
     if (auth.modelIdentity !== 'user') {
-      throw new Error(
-        `Sounding auth helpers could not auto-create a missing ${auth.modelIdentity} record.`
-      )
+      throw createSoundingError({
+        code: 'E_SOUNDING_AUTH_CREATE_UNSUPPORTED',
+        message: `Sounding auth helpers could not auto-create a missing ${auth.modelIdentity} record.`,
+        details: {
+          modelIdentity: auth.modelIdentity,
+        },
+      })
     }
 
     if (!sails?.helpers?.user?.signupWithTeam) {
-      throw new Error(
-        'Sounding auth helpers could not find `sails.helpers.user.signupWithTeam`.'
-      )
+      throw createSoundingError({
+        code: 'E_SOUNDING_AUTH_SIGNUP_HELPER_MISSING',
+        message: 'Sounding auth helpers could not find `sails.helpers.user.signupWithTeam`.',
+      })
     }
 
     const signupResult = await sails.helpers.user.signupWithTeam.with({
@@ -70,53 +143,101 @@ function createAuthHelpers({ sails, world, mailbox, request }) {
     return signupResult.user
   }
 
+  /**
+   * @param {SoundingActor | string} actorOrEmail
+   * @param {{ createIfMissing?: boolean, fullName?: string, [key: string]: any }} [options]
+   * @returns {Promise<Record<string, any>>}
+   */
   async function resolveActor(actorOrEmail, options = {}) {
     const auth = getAuthConfig()
     const User = getAuthModel()
 
     if (!actorOrEmail) {
-      throw new Error('Sounding auth helpers require an actor or email address.')
+      throw createSoundingError({
+        code: 'E_SOUNDING_AUTH_ACTOR_REQUIRED',
+        message: 'Sounding auth helpers require an actor or email address.',
+      })
     }
 
     let candidate = actorOrEmail
+    let unresolvedAlias = null
 
     if (typeof candidate === 'string' && !looksLikeEmail(candidate)) {
+      unresolvedAlias = candidate
       candidate = resolveWorldActor(candidate) || candidate
     }
 
-    if (candidate?.id && User?.findOne) {
+    if (typeof candidate !== 'string' && candidate?.id && User?.findOne) {
       return User.findOne({ id: candidate.id }) || candidate
     }
 
-    const email = candidate?.email || (looksLikeEmail(candidate) ? candidate : null)
+    const email =
+      typeof candidate === 'string'
+        ? looksLikeEmail(candidate)
+          ? candidate
+          : null
+        : candidate?.email || null
 
     if (!email) {
-      throw new Error(
-        `Sounding auth helpers could not resolve an email address for actor \`${candidate}\`.`
-      )
+      const details = {
+        actor: candidate,
+      }
+
+      if (unresolvedAlias && candidate === unresolvedAlias) {
+        const availableActors = availableWorldActors()
+        details.availableActors = availableActors
+
+        throw createSoundingError({
+          code: 'E_SOUNDING_AUTH_EMAIL_UNRESOLVED',
+          message: `Sounding auth helpers could not resolve an email address for actor \`${candidate}\`. Available actors: ${formatAvailable(availableActors)}.`,
+          details,
+        })
+      }
+
+      throw createSoundingError({
+        code: 'E_SOUNDING_AUTH_EMAIL_UNRESOLVED',
+        message: `Sounding auth helpers could not resolve an email address for actor \`${candidate}\`.`,
+        details,
+      })
     }
 
     const normalizedEmail = normalizeEmail(email)
     let user = User?.findOne ? await User.findOne({ email: normalizedEmail }) : null
 
     if (!user && options.createIfMissing !== false) {
-      user = await createUserFromEmail(normalizedEmail, candidate?.fullName || options.fullName)
+      user = await createUserFromEmail(
+        normalizedEmail,
+        (typeof candidate !== 'string' && candidate?.fullName) || options.fullName
+      )
     }
 
     if (!user) {
-      throw new Error(
-        `Sounding auth helpers could not find a ${auth.modelIdentity} for ${normalizedEmail}.`
-      )
+      throw createSoundingError({
+        code: 'E_SOUNDING_AUTH_MODEL_UNAVAILABLE',
+        message: `Sounding auth helpers could not find a ${auth.modelIdentity} for ${normalizedEmail}.`,
+        details: {
+          modelIdentity: auth.modelIdentity,
+          email: normalizedEmail,
+        },
+      })
     }
 
     return user
   }
 
+  /**
+   * @param {SoundingActor | string} actorOrEmail
+   * @param {{ createIfMissing?: boolean, fullName?: string, [key: string]: any }} [options]
+   * @returns {Promise<SoundingMagicLink>}
+   */
   async function issueMagicLink(actorOrEmail, options = {}) {
     const User = getAuthModel()
 
     if (!User?.updateOne) {
-      throw new Error('Sounding auth helpers require an auth model with updateOne().')
+      throw createSoundingError({
+        code: 'E_SOUNDING_AUTH_MODEL_UNAVAILABLE',
+        message: 'Sounding auth helpers require an auth model with updateOne().',
+      })
     }
 
     const user = await resolveActor(actorOrEmail, {
@@ -143,6 +264,11 @@ function createAuthHelpers({ sails, world, mailbox, request }) {
     }
   }
 
+  /**
+   * @param {SoundingActor | string} actorOrEmail
+   * @param {{ fullName?: string, redirectUrl?: string, requestOptions?: SoundingRequestOptions, [key: string]: any }} [options]
+   * @returns {Promise<SoundingRequestMagicLinkResult>}
+   */
   async function requestMagicLink(actorOrEmail, options = {}) {
     const user = await resolveActor(actorOrEmail, {
       createIfMissing: true,
@@ -167,9 +293,18 @@ function createAuthHelpers({ sails, world, mailbox, request }) {
     }
   }
 
+  /**
+   * @param {SoundingActor | string} actorOrEmail
+   * @param {SoundingPage} page
+   * @param {{ password?: string, rememberMe?: boolean, returnUrl?: string, [key: string]: any }} [options]
+   * @returns {Promise<SoundingBrowserLoginResult>}
+   */
   async function loginWithPassword(actorOrEmail, page, options = {}) {
     if (!page || typeof page.goto !== 'function') {
-      throw new Error('Sounding password browser login requires a Playwright page.')
+      throw createSoundingError({
+        code: 'E_SOUNDING_AUTH_BROWSER_PAGE_REQUIRED',
+        message: 'Sounding password browser login requires a Playwright page.',
+      })
     }
 
     const auth = getAuthConfig()
@@ -180,7 +315,10 @@ function createAuthHelpers({ sails, world, mailbox, request }) {
     const email = normalizeEmail(actor?.email || actorOrEmail)
 
     if (!options.password) {
-      throw new Error('Sounding password login requires a `password` option.')
+      throw createSoundingError({
+        code: 'E_SOUNDING_AUTH_PASSWORD_REQUIRED',
+        message: 'Sounding password login requires a `password` option.',
+      })
     }
 
     const loginUrl = new URL(auth.password.pagePath, 'http://sounding.local')
@@ -212,6 +350,11 @@ function createAuthHelpers({ sails, world, mailbox, request }) {
     }
   }
 
+  /**
+   * @param {SoundingActor | string} actorOrEmail
+   * @param {{ password?: string, rememberMe?: boolean, returnUrl?: string, request?: SoundingRequestClient, requestOptions?: SoundingRequestOptions, [key: string]: any }} [options]
+   * @returns {Promise<SoundingPasswordRequestResult>}
+   */
   async function requestWithPassword(actorOrEmail, options = {}) {
     const auth = getAuthConfig()
     const actor = await resolveActor(actorOrEmail, {
@@ -221,9 +364,13 @@ function createAuthHelpers({ sails, world, mailbox, request }) {
     const email = normalizeEmail(actor?.email || actorOrEmail)
 
     if (!options.password) {
-      throw new Error('Sounding password request auth requires a `password` option.')
+      throw createSoundingError({
+        code: 'E_SOUNDING_AUTH_PASSWORD_REQUIRED',
+        message: 'Sounding password request auth requires a `password` option.',
+      })
     }
 
+    /** @type {Record<string, any>} */
     const payload = {
       [auth.password.form.email]: email,
       [auth.password.form.password]: options.password,