sounding 0.0.4 → 0.1.0

package/lib/create-request-client.js

@@ -1,31 +1,116 @@
 const { Transform } = require('node:stream')
 const QS = require('node:querystring')
 const { resolveAuthConfig } = require('./resolve-auth-config')
-
+const { createSoundingError } = require('./create-error')
+
+/** @typedef {import('./types').AnyRecord} AnyRecord */
+/** @typedef {import('./types').SoundingActor} SoundingActor */
+/** @typedef {import('./types').SoundingRequestClient} SoundingRequestClient */
+/** @typedef {import('./types').SoundingRequestOptions} SoundingRequestOptions */
+/** @typedef {import('./types').SoundingResponse} SoundingResponse */
+/** @typedef {import('./types').SoundingSailsApp} SoundingSailsApp */
+/** @typedef {import('./types').SoundingTransport} SoundingTransport */
+/** @typedef {import('./types').SoundingWorldEngine} SoundingWorldEngine */
+
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
 function isAbsoluteUrl(value) {
   return /^https?:\/\//i.test(value)
 }
 
+/**
+ * @param {any} value
+ * @returns {value is AnyRecord}
+ */
 function isPlainObject(value) {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
 }
 
+/**
+ * @param {string} value
+ * @returns {string}
+ */
 function trimTrailingSlash(value) {
   return value.replace(/\/$/, '')
 }
 
-function looksLikeJson({ contentType, body }) {
+/**
+ * @param {{ contentType?: string, body?: any }} input
+ * @returns {boolean}
+ */
+function shouldParseJson({ contentType, body }) {
   if (!body) {
     return false
   }
 
-  if (contentType?.includes('application/json')) {
+  const mediaType = contentType?.split(';')[0]?.trim().toLowerCase()
+
+  if (mediaType === 'application/json' || mediaType?.endsWith('+json')) {
     return true
   }
 
   return /^[\[{]/.test(String(body).trim())
 }
 
+/**
+ * @param {{
+ *   error: unknown,
+ *   status: number,
+ *   contentType: string,
+ *   url?: string,
+ *   body: string,
+ * }} input
+ * @returns {Error & { code: string, status: number, url?: string, contentType: string, body: string }}
+ */
+function createJsonParseError({ error, status, contentType, url, body }) {
+  const fromUrl = url ? ` from ${url}` : ''
+  return createSoundingError({
+    code: 'E_SOUNDING_JSON_PARSE',
+    message: `Sounding could not parse JSON response${fromUrl} (status ${status}).`,
+    details: {
+      status,
+      url,
+      contentType,
+      body,
+    },
+    cause: error,
+    name: 'SoundingJsonParseError',
+  })
+}
+
+function createVirtualResponseStreamError(error) {
+  return createSoundingError({
+    code: 'E_SOUNDING_VIRTUAL_RESPONSE_STREAM',
+    message: 'Sounding virtual response stream failed.',
+    cause: error,
+    name: 'SoundingVirtualResponseStreamError',
+  })
+}
+
+/**
+ * @param {{ body: string, status: number, contentType: string, url?: string }} input
+ * @returns {any}
+ */
+function parseJsonResponse({ body, status, contentType, url }) {
+  try {
+    return JSON.parse(body)
+  } catch (error) {
+    throw createJsonParseError({
+      error,
+      status,
+      contentType,
+      url,
+      body,
+    })
+  }
+}
+
+/**
+ * @param {any} value
+ * @returns {{ body: string, data: any }}
+ */
 function normalizeBodyValue(value) {
   if (value === undefined || value === null) {
     return {
@@ -47,6 +132,46 @@ function normalizeBodyValue(value) {
   }
 }
 
+/**
+ * @param {HeadersInit | AnyRecord | undefined} headers
+ * @returns {HeadersInit | AnyRecord | undefined}
+ */
+function normalizeRequestHeadersMetadata(headers) {
+  if (!headers) {
+    return undefined
+  }
+
+  if (typeof headers.forEach === 'function') {
+    let count = 0
+    headers.forEach(() => {
+      count += 1
+    })
+    return count > 0 ? headers : undefined
+  }
+
+  return Object.keys(headers).length > 0 ? headers : undefined
+}
+
+/**
+ * @param {{
+ *   raw: unknown,
+ *   status: number,
+ *   statusText?: string,
+ *   headers?: HeadersInit | AnyRecord,
+ *   url?: string,
+ *   redirected?: boolean,
+ *   responseBody?: any,
+ *   session?: AnyRecord,
+ *   request?: {
+ *     method: string,
+ *     target: string,
+ *     transport: SoundingTransport | 'socket',
+ *     url?: string,
+ *     headers?: HeadersInit | AnyRecord,
+ *   },
+ * }} input
+ * @returns {SoundingResponse}
+ */
 function normalizeResponse({
   raw,
   status,
@@ -55,13 +180,20 @@ function normalizeResponse({
   url,
   redirected = false,
   responseBody,
+  session,
+  request,
 }) {
   const normalizedHeaders = new Headers(headers)
   const contentType = normalizedHeaders.get('content-type') || ''
   let { body, data } = normalizeBodyValue(responseBody)
 
-  if (data === undefined && looksLikeJson({ contentType, body })) {
-    data = JSON.parse(body)
+  if (data === undefined && shouldParseJson({ contentType, body })) {
+    data = parseJsonResponse({
+      body,
+      status,
+      contentType,
+      url,
+    })
   }
 
   return {
@@ -70,7 +202,9 @@ function normalizeResponse({
     status,
     statusText,
     url,
+    request,
     redirected,
+    session,
     headers: normalizedHeaders,
     body,
     data,
@@ -86,6 +220,10 @@ function normalizeResponse({
   }
 }
 
+/**
+ * @param {{ sails?: SoundingSailsApp, getConfig?: () => AnyRecord }} input
+ * @returns {AnyRecord}
+ */
 function resolveRequestConfig({ sails, getConfig }) {
   const soundingConfig =
     (typeof getConfig === 'function' ? getConfig() : null) || sails?.config?.sounding || {}
@@ -93,6 +231,10 @@ function resolveRequestConfig({ sails, getConfig }) {
   return soundingConfig.request || {}
 }
 
+/**
+ * @param {{ sails?: SoundingSailsApp, getConfig?: () => AnyRecord, override?: string }} input
+ * @returns {string}
+ */
 function resolveBaseUrl({ sails, getConfig, override }) {
   if (override) {
     return trimTrailingSlash(override)
@@ -124,11 +266,17 @@ function resolveBaseUrl({ sails, getConfig, override }) {
     return `http://127.0.0.1:${sails.config.port}`
   }
 
-  throw new Error(
-    'Sounding could not resolve a base URL for HTTP request trials. Configure `sounding.request.baseUrl`, `sounding.browser.baseUrl`, or lift Sails with the HTTP hook.'
-  )
+  throw createSoundingError({
+    code: 'E_SOUNDING_BASE_URL_UNRESOLVED',
+    message:
+      'Sounding could not resolve a base URL for HTTP request trials. Configure `sounding.request.baseUrl`, `sounding.browser.baseUrl`, or lift Sails with the HTTP hook.',
+  })
 }
 
+/**
+ * @param {{ sails?: SoundingSailsApp, getConfig?: () => AnyRecord, target: string, baseUrl?: string }} input
+ * @returns {string}
+ */
 function resolveUrl({ sails, getConfig, target, baseUrl }) {
   if (isAbsoluteUrl(target)) {
     return target
@@ -147,6 +295,11 @@ function resolveUrl({ sails, getConfig, target, baseUrl }) {
   return `${resolvedBaseUrl}/${target}`
 }
 
+/**
+ * @param {string} method
+ * @param {any} payload
+ * @returns {any}
+ */
 function normalizePayload(method, payload) {
   if (payload === undefined) {
     return undefined
@@ -163,6 +316,160 @@ function normalizePayload(method, payload) {
   return payload
 }
 
+/**
+ * @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 {{ world?: SoundingWorldEngine, sails?: SoundingSailsApp, getConfig?: () => AnyRecord }} input
+ * @returns {string[]}
+ */
+function availableWorldActors({ world, sails, getConfig }) {
+  const auth = resolveAuthConfig({ sails, getConfig })
+  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 {{ actor: string, world?: SoundingWorldEngine, sails?: SoundingSailsApp, getConfig?: () => AnyRecord }} input
+ * @returns {SoundingActor | null}
+ */
+function resolveWorldActor({ actor, world, sails, getConfig }) {
+  const auth = resolveAuthConfig({ sails, getConfig })
+
+  return (
+    world?.current?.[auth.worldCollection]?.[actor] ||
+    world?.current?.users?.[actor] ||
+    world?.current?.creators?.[actor] ||
+    world?.current?.[actor] ||
+    null
+  )
+}
+
+/**
+ * @param {{ actor: string, world?: SoundingWorldEngine, sails?: SoundingSailsApp, getConfig?: () => AnyRecord, email?: string, modelIdentity?: string }} input
+ * @returns {Error}
+ */
+function createRequestActorUnresolvedError({
+  actor,
+  world,
+  sails,
+  getConfig,
+  email,
+  modelIdentity,
+}) {
+  const availableActors = availableWorldActors({ world, sails, getConfig })
+  const availableMessage = `Available actors: ${formatAvailable(availableActors)}.`
+  const emailMessage = email ? ` Could not find ${modelIdentity || 'actor'} with email \`${email}\`.` : ''
+
+  return createSoundingError({
+    code: 'E_SOUNDING_REQUEST_ACTOR_UNRESOLVED',
+    message: `Sounding request.as() could not resolve actor \`${actor}\`. ${availableMessage}${emailMessage}`,
+    details: {
+      actor,
+      availableActors,
+      ...(email ? { email } : {}),
+      ...(modelIdentity ? { modelIdentity } : {}),
+    },
+  })
+}
+
+/**
+ * @param {{ actor: string, sails?: SoundingSailsApp, getConfig?: () => AnyRecord, world?: SoundingWorldEngine }} input
+ * @returns {Promise<SoundingActor>}
+ */
+async function resolveEmailActor({ actor, sails, getConfig, world }) {
+  const auth = resolveAuthConfig({ sails, getConfig })
+  const email = normalizeEmail(actor)
+
+  if (!auth.model?.findOne) {
+    throw createRequestActorUnresolvedError({
+      actor,
+      world,
+      sails,
+      getConfig,
+      email,
+      modelIdentity: auth.modelIdentity,
+    })
+  }
+
+  const resolvedActor = await auth.model.findOne({ email })
+
+  if (!resolvedActor) {
+    throw createRequestActorUnresolvedError({
+      actor,
+      world,
+      sails,
+      getConfig,
+      email,
+      modelIdentity: auth.modelIdentity,
+    })
+  }
+
+  return resolvedActor
+}
+
+/**
+ * @param {SoundingActor} actor
+ * @returns {HeadersInit | AnyRecord}
+ */
+function resolveActorHeaders(actor) {
+  return actor.headers || actor.sounding?.headers || {}
+}
+
+/**
+ * @param {SoundingActor} actor
+ * @param {AnyRecord} auth
+ * @returns {AnyRecord}
+ */
+function resolveActorSession(actor, auth) {
+  return (
+    actor.session ||
+    actor.sounding?.session || {
+      ...(actor.id ? { [auth.sessionKey]: actor.id } : {}),
+      ...(actor.team ? { teamId: actor.team } : {}),
+      ...(actor.teamId ? { teamId: actor.teamId } : {}),
+    }
+  )
+}
+
+/**
+ * @param {{ sails?: SoundingSailsApp, getConfig?: () => AnyRecord, target: string, options?: SoundingRequestOptions }} input
+ * @returns {SoundingTransport}
+ */
 function resolveTransport({ sails, getConfig, target, options = {} }) {
   if (options.transport) {
     return options.transport
@@ -176,6 +483,12 @@ function resolveTransport({ sails, getConfig, target, options = {} }) {
   return requestConfig.transport || 'virtual'
 }
 
+/**
+ * @param {string} method
+ * @param {string} target
+ * @param {any} payload
+ * @returns {string}
+ */
 function normalizeVirtualUrl(method, target, payload) {
   if (
     (method === 'GET' || method === 'HEAD' || method === 'DELETE') &&
@@ -194,6 +507,10 @@ function normalizeVirtualUrl(method, target, payload) {
   return target
 }
 
+/**
+ * @param {AnyRecord} [session]
+ * @returns {(key: string, value?: any) => any[]}
+ */
 function createFlash(session = {}) {
   const flashStore = (session.__soundingFlashStore ||= {})
 
@@ -217,61 +534,173 @@ class MockClientResponse extends Transform {
   }
 }
 
+let nextVirtualRequestId = 0
+
+/**
+ * @param {AnyRecord} target
+ * @param {AnyRecord} source
+ */
+function replaceObjectContents(target, source) {
+  const flashStore = target.__soundingFlashStore
+
+  for (const key of Object.keys(target)) {
+    delete target[key]
+  }
+
+  for (const key of Object.keys(source)) {
+    target[key] = source[key]
+  }
+
+  if (flashStore && !Object.prototype.hasOwnProperty.call(source, '__soundingFlashStore')) {
+    target.__soundingFlashStore = flashStore
+  }
+}
+
+/**
+ * @param {any} value
+ * @returns {any}
+ */
+function cloneSessionValue(value) {
+  if (Array.isArray(value)) {
+    return value.map(cloneSessionValue)
+  }
+
+  if (isPlainObject(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, nested]) => [key, cloneSessionValue(nested)])
+    )
+  }
+
+  return value
+}
+
+/**
+ * @param {AnyRecord} session
+ * @returns {AnyRecord}
+ */
+function cloneSessionSnapshot(session) {
+  return cloneSessionValue(session)
+}
+
+/**
+ * Sails' virtual router deep-copies the partial request before routing it.
+ * Track the routed request so session mutations made by real route handlers
+ * can flow back into Sounding's shared virtual session object.
+ *
+ * @param {{ sails?: SoundingSailsApp, session: AnyRecord }} input
+ * @returns {{ requestId: string, sync(): void, close(): void }}
+ */
+function createVirtualSessionTracker({ sails, session }) {
+  const requestId = `sounding-${++nextVirtualRequestId}`
+  let routedReq = null
+
+  function onRoute(requestState) {
+    if (requestState?.req?._soundingRequestId === requestId) {
+      routedReq = requestState.req
+
+      if (isPlainObject(routedReq.session)) {
+        routedReq.flash = createFlash(routedReq.session)
+      }
+    }
+  }
+
+  if (typeof sails?.on === 'function') {
+    sails.on('router:route', onRoute)
+  }
+
+  return {
+    requestId,
+    sync() {
+      if (isPlainObject(session) && isPlainObject(routedReq?.session)) {
+        replaceObjectContents(session, routedReq.session)
+      }
+    },
+    close() {
+      if (typeof sails?.off === 'function') {
+        sails.off('router:route', onRoute)
+        return
+      }
+
+      if (typeof sails?.removeListener === 'function') {
+        sails.removeListener('router:route', onRoute)
+      }
+    },
+  }
+}
+
+/**
+ * @param {{ sails?: SoundingSailsApp }} input
+ * @returns {{ send(method: string, target: string, payload?: any, options?: SoundingRequestOptions): Promise<SoundingResponse> }}
+ */
 function createVirtualTransport({ sails }) {
   if (typeof sails?.router?.route !== 'function') {
-    throw new Error(
-      'Sounding could not find `sails.router.route()`. Virtual request transport requires a loaded Sails app.'
-    )
+    throw createSoundingError({
+      code: 'E_SOUNDING_VIRTUAL_TRANSPORT_UNAVAILABLE',
+      message:
+        'Sounding could not find `sails.router.route()`. Virtual request transport requires a loaded Sails app.',
+    })
   }
 
   return {
     async send(method, target, payload, options = {}) {
       return new Promise((resolve, reject) => {
         const session = options.session || defaultSessionState()
+        const sessionTracker = createVirtualSessionTracker({ sails, session })
+        const virtualUrl = normalizeVirtualUrl(method, target, normalizePayload(method, payload))
+        /** @type {MockClientResponse & { body?: any, headers?: AnyRecord, statusCode?: number, statusMessage?: string }} */
         const clientRes = new MockClientResponse()
 
         try {
           clientRes.on('finish', () => {
             try {
+              sessionTracker.sync()
               clientRes.body = clientRes.read()
               clientRes.body = clientRes.body?.toString()
-            } catch {}
 
-            if (!clientRes.body) {
-              delete clientRes.body
+              if (!clientRes.body) {
+                delete clientRes.body
+              }
+
+              const status = clientRes.statusCode || 500
+              const responseBody = clientRes.body
+              const requestHeaders = normalizeRequestHeadersMetadata(options.headers)
+
+              resolve(
+                normalizeResponse({
+                  raw: clientRes,
+                  status,
+                  statusText: clientRes.statusMessage || '',
+                  headers: clientRes.headers || {},
+                  url: target,
+                  redirected: status >= 300 && status < 400,
+                  responseBody,
+                  session: cloneSessionSnapshot(session),
+                  request: {
+                    method,
+                    target,
+                    transport: 'virtual',
+                    url: virtualUrl,
+                    ...(requestHeaders ? { headers: requestHeaders } : {}),
+                  },
+                })
+              )
+            } catch (error) {
+              reject(error)
+            } finally {
+              sessionTracker.close()
             }
-
-            if (
-              clientRes.body !== undefined &&
-              clientRes.headers?.['content-type'] === 'application/json'
-            ) {
-              clientRes.body = JSON.parse(clientRes.body)
-            }
-
-            const status = clientRes.statusCode || 500
-            const responseBody = clientRes.body
-
-            resolve(
-              normalizeResponse({
-                raw: clientRes,
-                status,
-                statusText: clientRes.statusMessage || '',
-                headers: clientRes.headers || {},
-                url: target,
-                redirected: status >= 300 && status < 400,
-                responseBody,
-              })
-            )
           })
 
           clientRes.on('error', (error) => {
-            reject(error || new Error('Error on virtual response stream'))
+            sessionTracker.close()
+            reject(createVirtualResponseStreamError(error))
           })
 
           sails.router.route(
             {
               method,
-              url: normalizeVirtualUrl(method, target, normalizePayload(method, payload)),
+              url: virtualUrl,
+              _soundingRequestId: sessionTracker.requestId,
               body: ['GET', 'HEAD', 'DELETE'].includes(method)
                 ? undefined
                 : normalizePayload(method, payload),
@@ -287,6 +716,7 @@ function createVirtualTransport({ sails }) {
             }
           )
         } catch (error) {
+          sessionTracker.close()
           reject(error)
           return
         }
@@ -295,10 +725,19 @@ function createVirtualTransport({ sails }) {
   }
 }
 
+/**
+ * @returns {AnyRecord}
+ */
 function defaultSessionState() {
   return {}
 }
 
+/**
+ * @param {string} method
+ * @param {any} payload
+ * @param {Headers} headers
+ * @returns {{ body: any, headers: Headers }}
+ */
 function normalizeBodyAndHeaders(method, payload, headers) {
   if (payload === undefined || method === 'GET' || method === 'HEAD') {
     return {
@@ -337,13 +776,24 @@ function normalizeBodyAndHeaders(method, payload, headers) {
   }
 }
 
+/**
+ * @param {{
+ *   sails?: SoundingSailsApp,
+ *   getConfig?: () => AnyRecord,
+ *   fetchImplementation?: typeof fetch,
+ * }} input
+ * @returns {{ send(method: string, target: string, payload?: any, options?: SoundingRequestOptions): Promise<SoundingResponse> }}
+ */
 function createHttpTransport({
   sails,
   getConfig,
   fetchImplementation = globalThis.fetch,
 }) {
   if (typeof fetchImplementation !== 'function') {
-    throw new Error('Sounding could not find a fetch implementation for HTTP request trials.')
+    throw createSoundingError({
+      code: 'E_SOUNDING_HTTP_FETCH_UNAVAILABLE',
+      message: 'Sounding could not find a fetch implementation for HTTP request trials.',
+    })
   }
 
   return {
@@ -354,14 +804,16 @@ function createHttpTransport({
       })
 
       const { body, headers: finalHeaders } = normalizeBodyAndHeaders(method, payload, headers)
+      const requestHeaders = normalizeRequestHeadersMetadata(finalHeaders)
+      const url = resolveUrl({
+        sails,
+        getConfig,
+        target,
+        baseUrl: options.baseUrl,
+      })
 
       const response = await fetchImplementation(
-        resolveUrl({
-          sails,
-          getConfig,
-          target,
-          baseUrl: options.baseUrl,
-        }),
+        url,
         {
           method,
           redirect: options.redirect || 'manual',
@@ -379,11 +831,31 @@ function createHttpTransport({
         url: response.url,
         redirected: response.redirected,
         responseBody: await response.text(),
+        request: {
+          method,
+          target,
+          transport: 'http',
+          url,
+          ...(requestHeaders ? { headers: requestHeaders } : {}),
+        },
       })
     },
   }
 }
 
+/**
+ * @param {{
+ *   sails?: SoundingSailsApp,
+ *   getConfig?: () => AnyRecord,
+ *   fetchImplementation?: typeof fetch,
+ *   defaultHeaders?: HeadersInit | AnyRecord,
+ *   defaultSession?: AnyRecord,
+ *   transportOverride?: SoundingTransport,
+ *   world?: SoundingWorldEngine,
+ *   defaultActor?: string,
+ * }} [options]
+ * @returns {SoundingRequestClient}
+ */
 function createRequestClient({
   sails,
   getConfig,
@@ -391,9 +863,20 @@ function createRequestClient({
   defaultHeaders = {},
   defaultSession = {},
   transportOverride,
+  world,
+  defaultActor,
 } = {}) {
   let virtualTransport = null
   let httpTransport = null
+  let defaultActorContextPromise = null
+
+  function resetDefaultSession() {
+    for (const key of Reflect.ownKeys(defaultSession)) {
+      Reflect.deleteProperty(defaultSession, key)
+    }
+
+    defaultActorContextPromise = null
+  }
 
   function getVirtualTransport() {
     virtualTransport ||= createVirtualTransport({ sails })
@@ -409,20 +892,80 @@ function createRequestClient({
     return httpTransport
   }
 
+  /**
+   * @returns {Promise<{ headers: HeadersInit | AnyRecord, session: AnyRecord } | null>}
+   */
+  async function getDefaultActorContext() {
+    if (!defaultActor) {
+      return null
+    }
+
+    defaultActorContextPromise ||= resolveEmailActor({
+      actor: defaultActor,
+      sails,
+      getConfig,
+      world,
+    }).then((actor) => {
+      const auth = resolveAuthConfig({ sails, getConfig })
+
+      return {
+        headers: resolveActorHeaders(actor),
+        session: {
+          ...defaultSession,
+          ...resolveActorSession(actor, auth),
+        },
+      }
+    })
+
+    return defaultActorContextPromise
+  }
+
+  /**
+   * @param {SoundingActor} actor
+   * @returns {SoundingRequestClient}
+   */
+  function withActor(actor) {
+    const auth = resolveAuthConfig({ sails, getConfig })
+
+    return createRequestClient({
+      sails,
+      getConfig,
+      fetchImplementation,
+      defaultHeaders: {
+        ...defaultHeaders,
+        ...resolveActorHeaders(actor),
+      },
+      defaultSession: {
+        ...defaultSession,
+        ...resolveActorSession(actor, auth),
+      },
+      transportOverride,
+      world,
+    })
+  }
+
   async function send(method, target, payloadOrOptions, maybeOptions) {
     const hasPayload = !['GET', 'HEAD'].includes(method)
     const payload = hasPayload ? payloadOrOptions : undefined
     const options = (hasPayload ? maybeOptions : payloadOrOptions) || {}
+    const defaultActorContext = await getDefaultActorContext()
+    const baseHeaders = defaultActorContext
+      ? {
+          ...defaultHeaders,
+          ...defaultActorContext.headers,
+        }
+      : defaultHeaders
+    const baseSession = defaultActorContext?.session || defaultSession
     const headers = {
-      ...defaultHeaders,
+      ...baseHeaders,
       ...(options.headers || {}),
     }
     const session = options.session
       ? {
-          ...defaultSession,
+          ...baseSession,
           ...options.session,
         }
-      : defaultSession
+      : baseSession
     const transport = resolveTransport({
       sails,
       getConfig,
@@ -447,7 +990,13 @@ function createRequestClient({
       return getHttpTransport().send(method, target, payload, transportOptions)
     }
 
-    throw new Error(`Unknown Sounding request transport: ${transport}`)
+    throw createSoundingError({
+      code: 'E_SOUNDING_UNKNOWN_TRANSPORT',
+      message: `Unknown Sounding request transport: ${transport}`,
+      details: {
+        transport,
+      },
+    })
   }
 
   return {
@@ -483,6 +1032,10 @@ function createRequestClient({
       return send('DELETE', target, payload, options)
     },
 
+    clearSession() {
+      resetDefaultSession()
+    },
+
     withHeaders(headers = {}) {
       return createRequestClient({
         sails,
@@ -494,6 +1047,8 @@ function createRequestClient({
         },
         defaultSession,
         transportOverride,
+        world,
+        defaultActor,
       })
     },
 
@@ -508,6 +1063,8 @@ function createRequestClient({
           ...session,
         },
         transportOverride,
+        world,
+        defaultActor,
       })
     },
 
@@ -519,6 +1076,8 @@ function createRequestClient({
         defaultHeaders,
         defaultSession,
         transportOverride: transport,
+        world,
+        defaultActor,
       })
     },
 
@@ -527,16 +1086,35 @@ function createRequestClient({
         return this
       }
 
-      const auth = resolveAuthConfig({ sails, getConfig })
-      const actorHeaders = actor.headers || actor.sounding?.headers || {}
-      const actorSession = actor.session ||
-        actor.sounding?.session || {
-          ...(actor.id ? { [auth.sessionKey]: actor.id } : {}),
-          ...(actor.team ? { teamId: actor.team } : {}),
-          ...(actor.teamId ? { teamId: actor.teamId } : {}),
+      if (typeof actor === 'string') {
+        if (looksLikeEmail(actor)) {
+          return createRequestClient({
+            sails,
+            getConfig,
+            fetchImplementation,
+            defaultHeaders,
+            defaultSession,
+            transportOverride,
+            world,
+            defaultActor: actor,
+          })
         }
 
-      return this.withHeaders(actorHeaders).withSession(actorSession)
+        const resolvedActor = resolveWorldActor({ actor, world, sails, getConfig })
+
+        if (!resolvedActor) {
+          throw createRequestActorUnresolvedError({
+            actor,
+            world,
+            sails,
+            getConfig,
+          })
+        }
+
+        return withActor(resolvedActor)
+      }
+
+      return withActor(actor)
     },
   }
 }