@open-xchange/soap-client 0.1.6 → 0.2.1

package/services/secondaryAccount.js

@@ -1,52 +1,67 @@
-import { createClientAsync } from '../soap.js'
-
-let OXSecondaryAccountService
-function getClient () {
-  if (!OXSecondaryAccountService) OXSecondaryAccountService = createClientAsync('OXSecondaryAccountService')
-  return OXSecondaryAccountService
-}
+import { createClientAsync, memoizeClient } from '../soap.js'
 
 /**
- * Creates a secondary account using the OX Secondary Account Service
- * @async
- * @param {Object} accountData - The data for the secondary account to be created
- * @param {Object} context - The context object where the account will be created
- * @param {Array<Object>} users - Array of users to associate with the secondary account
- * @param {Array<Object>} groups - Array of groups to associate with the secondary account
- * @returns {Promise<Object>} The created secondary account object
- * @throws {Error} If the account creation fails
+ * Build a secondary-account service bound to a SOAP client constructor.
+ * @param {(type: string) => Promise<Object>} createClient
+ * @returns {Object} The secondary account service.
  */
-export async function create (accountData, context, users = [], groups = []) {
-  return (await getClient()).createAsync({
-    accountDataOnCreate: accountData,
-    context: { id: context.id },
-    users: users || [],
-    auth: context.admin
-  })
-}
+export function createSecondaryAccountService (createClient) {
+  const getClient = memoizeClient(createClient, 'OXSecondaryAccountService')
 
-export async function list (context) {
-  return (await getClient()).listAsync({
-    context: { id: context.id },
-    auth: context.admin
-  })
-}
-export async function remove (primaryAddress, context, users, groups) {
-  return (await getClient()).deleteAsync({
-    primaryAddress,
-    context: { id: context.id },
-    users,
-    auth: context.admin
-  })
-}
+  /**
+   * Creates a secondary account using the OX Secondary Account Service
+   * @async
+   * @param {Object} accountData - The data for the secondary account to be created
+   * @param {Object} context - The context object where the account will be created
+   * @param {Array<Object>} users - Array of users to associate with the secondary account
+   * @param {Array<Object>} groups - Array of groups to associate with the secondary account
+   * @returns {Promise<Object>} The created secondary account object
+   * @throws {Error} If the account creation fails
+   */
+  async function create (accountData, context, users = [], groups = []) {
+    return (await getClient()).createAsync({
+      accountDataOnCreate: accountData,
+      context: { id: context.id },
+      users: users || [],
+      auth: context.admin
+    })
+  }
 
-export async function update (primaryAddress, accountData, context, users, groups) {
-  return (await getClient()).updateAsync({
-    primaryAddress,
-    accountDataUpdate: accountData,
-    context: { id: context.id },
-    users,
-    groups,
-    auth: context.admin
-  })
+  async function list (context) {
+    return (await getClient()).listAsync({
+      context: { id: context.id },
+      auth: context.admin
+    })
+  }
+
+  async function remove (primaryAddress, context, users, groups) {
+    return (await getClient()).deleteAsync({
+      primaryAddress,
+      context: { id: context.id },
+      users,
+      auth: context.admin
+    })
+  }
+
+  async function update (primaryAddress, accountData, context, users, groups) {
+    return (await getClient()).updateAsync({
+      primaryAddress,
+      accountDataUpdate: accountData,
+      context: { id: context.id },
+      users,
+      groups,
+      auth: context.admin
+    })
+  }
+
+  return { create, list, remove, update }
 }
+
+// Classic module exports, bound to the env-configured default endpoint.
+let defaultService
+const service = () => (defaultService ??= createSecondaryAccountService(createClientAsync))
+
+export const create = (...args) => service().create(...args)
+export const list = (...args) => service().list(...args)
+export const remove = (...args) => service().remove(...args)
+export const update = (...args) => service().update(...args)

package/services/sharedAccount.js

@@ -18,116 +18,132 @@
  * Any use of the work other than as authorized under this license or copyright law is prohibited.
  */
 
-import { createClientAsync } from '../soap.js'
-
-let OXSharedAccountService
-function getClient () {
-  if (!OXSharedAccountService) OXSharedAccountService = createClientAsync('OXSharedAccountService')
-  return OXSharedAccountService
-}
+import { createClientAsync, memoizeClient } from '../soap.js'
 
 /**
- * Creates a shared account using the OX Shared Account Service
- *
- * @param {Object} context - The context object where the account will be created
- * @param {Object} sharedAccountData - The data for the shared account to be created
- * @returns {Promise<Object>} The created shared account object
- * @throws {Error} If the shared account creation fails
+ * Build a shared-account service bound to a SOAP client constructor.
+ * @param {(type: string) => Promise<Object>} createClient
+ * @returns {Object} The shared account service.
  */
-export async function create (context, sharedAccountData) {
-  return (await getClient()).createAsync({
-    ctx: { id: context.id },
-    sharedAccountData,  // display_name, given_name, imapServer, language, mailenabled, name, sur_name, primaryEmail, email1, smtpServer, timezone, password
-    auth: context.admin
-  })
-}
+export function createSharedAccountService (createClient) {
+  const getClient = memoizeClient(createClient, 'OXSharedAccountService')
 
-/**
- * Converts an existing user to a shared account using the OX Shared Account Service
- *
- * @param {Object} context - The context of the user to be converted
- * @param {number} userId - ID of the user to be converted
- * @param {string} password - The password for the new shared account
- * @returns {Promise<void>}
- * @throws {Error} If the conversion fails
- */
-export async function convertUserToSharedAccount (context, userId, password) {
-  return (await getClient()).convertUserToSharedAccountAsync({
-    ctx: { id: context.id },
-    user: { id: userId },
-    password,
-    auth: context.admin
-  })
-}
+  /**
+   * Creates a shared account using the OX Shared Account Service
+   *
+   * @param {Object} context - The context object where the account will be created
+   * @param {Object} sharedAccountData - The data for the shared account to be created
+   * @returns {Promise<Object>} The created shared account object
+   * @throws {Error} If the shared account creation fails
+   */
+  async function create (context, sharedAccountData) {
+    return (await getClient()).createAsync({
+      ctx: { id: context.id },
+      sharedAccountData, // display_name, given_name, imapServer, language, mailenabled, name, sur_name, primaryEmail, email1, smtpServer, timezone, password
+      auth: context.admin
+    })
+  }
 
-/**
- * Add users and groups with specified permissions and capabilities to an existing shared account using the OX Shared Account Service.
- *
- * @param {Object} context - The context of the users and groups
- * @param {Object} sharedAccountContext - The context of the shared account
- * @param {number} sharedAccountId - ID of the shared account
- * @param {Object} permissions - The users, groups, capabilities, and module-specific permissions.
- * @returns {Promise<Object>} The shared account object
- * @throws {Error} If the creation of the shared account permissions fails
- */
-export async function createSharedAccountPermissions (context, sharedAccountContext, sharedAccountId, permissions) {
-  return (await getClient()).createSharedAccountPermissionsAsync({
-    ctx: { id: context.id },
-    sharedAccountCtx: { id: sharedAccountContext.id },
-    sharedAccount: { id: sharedAccountId },
-    groups: permissions.groups ?? [],
-    users: permissions.users?.map(user => ({ id: user.userdata.id })) ?? [],
-    capabilities: {
-      grantedCapability: permissions.capabilities?.grantedCapability ?? [],
-      deniedCapability: permissions.capabilities?.deniedCapability ?? [],
-    },
-    mailConfig: permissions.mailConfig,
-    calendarConfig: permissions.calendarConfig,
-    auth: context.admin
-  })
-}
+  /**
+   * Converts an existing user to a shared account using the OX Shared Account Service
+   *
+   * @param {Object} context - The context of the user to be converted
+   * @param {number} userId - ID of the user to be converted
+   * @param {string} password - The password for the new shared account
+   * @returns {Promise<void>}
+   * @throws {Error} If the conversion fails
+   */
+  async function convertUserToSharedAccount (context, userId, password) {
+    return (await getClient()).convertUserToSharedAccountAsync({
+      ctx: { id: context.id },
+      user: { id: userId },
+      password,
+      auth: context.admin
+    })
+  }
 
-/**
- * List all shared accounts in the specified context
- *
- * @param {Object} context - The context object whose shared account will be listed
- * @param {*} pattern - An optional search pattern for the contexts
- * @returns {Promise<Object[]>} The list of shared account objects
- */
-export async function list (context, pattern = '*') {
-  return (await getClient()).listAsync({
-    ctx: { id: context.id },
-    search_pattern: pattern,
-    auth: context.admin
-  })
-}
+  /**
+   * Add users and groups with specified permissions and capabilities to an existing shared account using the OX Shared Account Service.
+   *
+   * @param {Object} context - The context of the users and groups
+   * @param {Object} sharedAccountContext - The context of the shared account
+   * @param {number} sharedAccountId - ID of the shared account
+   * @param {Object} permissions - The users, groups, capabilities, and module-specific permissions.
+   * @returns {Promise<Object>} The shared account object
+   * @throws {Error} If the creation of the shared account permissions fails
+   */
+  async function createSharedAccountPermissions (context, sharedAccountContext, sharedAccountId, permissions) {
+    return (await getClient()).createSharedAccountPermissionsAsync({
+      ctx: { id: context.id },
+      sharedAccountCtx: { id: sharedAccountContext.id },
+      sharedAccount: { id: sharedAccountId },
+      groups: permissions.groups ?? [],
+      users: permissions.users?.map(user => ({ id: user.userdata.id })) ?? [],
+      capabilities: {
+        grantedCapability: permissions.capabilities?.grantedCapability ?? [],
+        deniedCapability: permissions.capabilities?.deniedCapability ?? [],
+      },
+      mailConfig: permissions.mailConfig,
+      calendarConfig: permissions.calendarConfig,
+      auth: context.admin
+    })
+  }
 
-/**
- * Get all data of a specified shared account in the specified context
- *
- * @param {*} context - The context where the shared account exists
- * @param {number} sharedAccountId - ID of the requested shared account
- * @returns {Promise<Object>} The shared account object
- */
-export async function getData (context, sharedAccountId) {
-  return (await getClient()).getDataAsync({
-    ctx: { id: context.id },
-    sharedAccount: { id: sharedAccountId },
-    auth: context.admin
-  })
-}
+  /**
+   * List all shared accounts in the specified context
+   *
+   * @param {Object} context - The context object whose shared account will be listed
+   * @param {*} pattern - An optional search pattern for the contexts
+   * @returns {Promise<Object[]>} The list of shared account objects
+   */
+  async function list (context, pattern = '*') {
+    return (await getClient()).listAsync({
+      ctx: { id: context.id },
+      search_pattern: pattern,
+      auth: context.admin
+    })
+  }
 
-/**
- * Remove a specified shared account in the specified context
- *
- * @param {*} context - The context object where the account will be removed
- * @param {number} sharedAccountId - ID of the shared account to be removed
- * @returns {Promise<void>}
- */
-export async function remove (context, sharedAccountId) {
-  return (await getClient()).deleteAsync({
-    ctx: { id: context.id },
-    sharedAccount: { id: sharedAccountId },
-    auth: context.admin
-  })
+  /**
+   * Get all data of a specified shared account in the specified context
+   *
+   * @param {*} context - The context where the shared account exists
+   * @param {number} sharedAccountId - ID of the requested shared account
+   * @returns {Promise<Object>} The shared account object
+   */
+  async function getData (context, sharedAccountId) {
+    return (await getClient()).getDataAsync({
+      ctx: { id: context.id },
+      sharedAccount: { id: sharedAccountId },
+      auth: context.admin
+    })
+  }
+
+  /**
+   * Remove a specified shared account in the specified context
+   *
+   * @param {*} context - The context object where the account will be removed
+   * @param {number} sharedAccountId - ID of the shared account to be removed
+   * @returns {Promise<void>}
+   */
+  async function remove (context, sharedAccountId) {
+    return (await getClient()).deleteAsync({
+      ctx: { id: context.id },
+      sharedAccount: { id: sharedAccountId },
+      auth: context.admin
+    })
+  }
+
+  return { create, convertUserToSharedAccount, createSharedAccountPermissions, list, getData, remove }
 }
+
+// Classic module exports, bound to the env-configured default endpoint.
+let defaultService
+const service = () => (defaultService ??= createSharedAccountService(createClientAsync))
+
+export const create = (...args) => service().create(...args)
+export const convertUserToSharedAccount = (...args) => service().convertUserToSharedAccount(...args)
+export const createSharedAccountPermissions = (...args) => service().createSharedAccountPermissions(...args)
+export const list = (...args) => service().list(...args)
+export const getData = (...args) => service().getData(...args)
+export const remove = (...args) => service().remove(...args)

package/soap.js

@@ -40,12 +40,9 @@ const RETRY_OPTIONS = {
   randomize: true     // jitter to avoid thundering herd across parallel shards
 }
 
-for (const envFile of ['.env', '.env.defaults']) {
-  try { process.loadEnvFile(envFile) } catch {}
-}
-
-// This flag enables debug output including timing information.
-const debug = process.env.DEBUG_SOAP === 'true'
+// This flag enables debug output including timing information. Read lazily so
+// importing the module has no environment-dependent behavior.
+const debug = () => process.env.DEBUG_SOAP === 'true'
 
 /**
  * Walk one layer of common error-wrapper shapes:
@@ -91,44 +88,44 @@ function describeError (err) {
     'unknown'
 }
 
-// Handle specifically timeout-related unhandled promise rejections as fallback
-process.on('unhandledRejection', (reason, promise) => {
-  const r = unwrapError(reason)
-  if (r?.code === 'ECONNABORTED' && (r?.message?.includes('timeout') || r?.message?.includes('exceeded'))) {
-    return
-  }
-
-  // Log other unhandled rejections as they indicate real problems
-  console.error('Unhandled promise rejection:', describeError(reason))
-})
-
-// This URL is used to create the SOAP client.
-const provisioningUrl = String(process.env.PROVISIONING_URL).replace(/\/$/, '')
-
-// This user is used to authenticate against the provisioning API.
-const provisioningAuth = {
-  auth: {
-    login: process.env.E2E_ADMIN_USER,
-    password: process.env.E2E_ADMIN_PW
-  }
+// Swallow specifically timeout-related unhandled promise rejections as
+// fallback; log everything else, as those indicate real problems. Installed
+// on demand (idempotent) — importing the module must not touch process-global
+// state. The env-configured default client installs it for backwards
+// compatibility with the CLI and test-runner consumers; factory clients from
+// createClientFactory never do, so embedding applications keep their own
+// rejection policy.
+let rejectionFilterInstalled = false
+function installTimeoutRejectionFilter () {
+  if (rejectionFilterInstalled) return
+  rejectionFilterInstalled = true
+  process.on('unhandledRejection', (reason, promise) => {
+    const r = unwrapError(reason)
+    if (r?.code === 'ECONNABORTED' && (r?.message?.includes('timeout') || r?.message?.includes('exceeded'))) {
+      return
+    }
+    console.error('Unhandled promise rejection:', describeError(reason))
+  })
 }
 
 /**
- * This code creates a PerformanceObserver instance which asynchronously observes
- * performance measurement events. It logs the name of the event (which is the name
- * of the SOAP method in this context) and the time it took to execute in milliseconds.
- *
- * This is used for performance tracking of the SOAP methods.
+ * Lazily create the PerformanceObserver that logs SOAP method timings when
+ * DEBUG_SOAP is enabled. One observer per process, created on first client
+ * construction rather than at import time.
  * @see https://nodejs.org/api/perf_hooks.html
- * @params {PerformanceObserverEntryList} items The list of performance entries.
  * @returns {void}
  */
-const obs = new PerformanceObserver((items) => {
-  items.getEntries().forEach((entry) => {
-    if (debug) console.log(`${entry.name} took ${Math.round(entry.duration)}ms`)
+let debugObserverInstalled = false
+function ensureDebugObserver () {
+  if (debugObserverInstalled || !debug()) return
+  debugObserverInstalled = true
+  const obs = new PerformanceObserver((items) => {
+    items.getEntries().forEach((entry) => {
+      console.log(`${entry.name} took ${Math.round(entry.duration)}ms`)
+    })
   })
-})
-obs.observe({ entryTypes: ['measure'] })
+  obs.observe({ entryTypes: ['measure'] })
+}
 
 async function logSoapError (e) {
   console.error(describeError(e))
@@ -243,15 +240,169 @@ function handleFailedAttempt (context, label) {
 }
 
 /**
- * This function creates a SOAP client for the specified service type.
+ * @typedef {object} TransportOptions
+ * @property {string} url  Base URL of the provisioning API (e.g. the core-mw
+ *   admin Service), without the `/webservices` suffix.
+ * @property {{login: string, password: string}} auth  Master admin credentials
+ *   injected into every SOAP call unless the call passes its own `auth`. This
+ *   one is a `Credentials` element and nothing else, so it is `login` only —
+ *   see {@link AdminCredentials} for the per-call shape, which is wider.
+ */
+
+/**
+ * @typedef {object} AdminCredentials
+ * @property {string} [login]  The account name as the `auth` element calls it.
+ * @property {string} [name]  The same account as the SOAP `admin_user` object
+ *   calls it. Used when `login` is absent.
+ * @property {string} password
+ */
+
+/**
+ * Read the account name out of an admin object.
+ *
+ * The SOAP `admin_user` object names the account `name`; only the `auth`
+ * element calls it `login`. Consumers hold the former and the transport needs
+ * the latter, and every one of them used to bridge that itself: the CLI
+ * (`bin/provision.js`), `resellerUserService` and appsuite-codeceptjs's
+ * `Context` constructor each added a `login` in their own way, and anyone who
+ * forgot authenticated with `login: undefined` and got a terminal
+ * "Authentication failed" from the middleware. Reading both shapes in one
+ * place removes the trap; `login` wins when both are present, so the bridges
+ * that remain outside this package keep working unchanged.
+ *
+ * @param {AdminCredentials} [admin]
+ * @returns {string|undefined}
+ */
+function adminLogin (admin) {
+  return admin?.login || admin?.name
+}
+
+/**
+ * The capability reads answer with a display string, not a data structure, so
+ * parsing belongs here rather than in every caller.
+ *
+ * `OXUserServicePortTypeImpl.getUserCapabilities` and its context twin sort the
+ * set into a `TreeSet` and join it with `", "`, comma and space, so a plain
+ * `split(',')` leaves a blank in front of every entry but the first and nothing
+ * ever compares equal to the desired state. Worse, an empty set is reported as
+ * a sentence:
+ *
+ *     There are no capabilities set for user 3 in context 42
+ *     There are no capabilities set for context 42
+ *
+ * Returned verbatim that becomes one capability named after the sentence, which
+ * a reconciler then tries to remove. A context that has just been created is
+ * exactly the case that hits it, so the empty answer is the common one.
+ *
+ * @param {string} [capabilities] The raw `return` of a capabilities call.
+ * @returns {string[]} The capability names, or `[]` when there are none.
+ */
+function parseCapabilities (capabilities) {
+  if (typeof capabilities !== 'string') return []
+  if (/^There are no capabilities set for /.test(capabilities)) return []
+  return capabilities.split(',').map(c => c.trim()).filter(Boolean)
+}
+
+/**
+ * Create a per-endpoint SOAP client constructor. Multiple factories coexist in
+ * one process, each bound to its own endpoint and credentials — nothing is
+ * read from the environment and no process-global state is touched.
+ * @param {TransportOptions} options
+ * @returns {(type: string) => Promise<Object>} createClientAsync bound to the endpoint.
+ */
+function createClientFactory ({ url, auth }) {
+  if (!url) throw new TypeError('createClientFactory: url is required')
+  // Deliberately narrower than the per-call `auth` below: this is the master
+  // admin, which has no `admin_user` counterpart, so no SOAP object names it
+  // `name`. Accepting one would only let a wrong object through construction
+  // and turn it into a terminal "Authentication failed" on the first call.
+  if (!auth?.login || !auth?.password) throw new TypeError('createClientFactory: auth {login, password} is required')
+  const baseUrl = String(url).replace(/\/$/, '')
+  const defaultAuth = { auth: { login: auth.login, password: auth.password } }
+  return (type) => createTypedClientAsync(type, baseUrl, defaultAuth)
+}
+
+/**
+ * Memoize one SOAP client per service type, but only once it resolves.
+ *
+ * A plain `promise ??= createClient(type)` caches a rejection for the lifetime
+ * of the process: if the WSDL fetch exhausts its retry schedule or hits a
+ * non-retryable fault, every later call re-throws that stale error without ever
+ * touching the network again. That is fatal for a long-running embedder, where
+ * one bad startup would poison the service until the process restarts. Clearing
+ * the slot on failure keeps the happy path a single shared client while letting
+ * the next call re-attempt construction.
+ *
+ * @param {(type: string) => Promise<Object>} createClient
+ * @param {string} type The name of the service type.
+ * @returns {() => Promise<Object>} Getter returning the memoized client.
+ */
+function memoizeClient (createClient, type) {
+  let clientPromise
+  return () => (clientPromise ??= createClient(type).catch(e => {
+    clientPromise = undefined
+    throw e
+  }))
+}
+
+// The env-configured default transport behind the classic module exports.
+// Built lazily on first use: loads .env files, installs the timeout-rejection
+// filter (CLI/test-runner compatibility), and binds PROVISIONING_URL +
+// E2E_ADMIN_USER/PW. Factory transports never take this path.
+let defaultCreateClient
+function getDefaultCreateClient () {
+  if (!defaultCreateClient) {
+    for (const envFile of ['.env', '.env.defaults']) {
+      try { process.loadEnvFile(envFile) } catch {}
+    }
+    installTimeoutRejectionFilter()
+    // Report the missing *environment variables*, not createClientFactory's
+    // parameter names: a caller of the classic module exports never touched
+    // that function and would otherwise get an error naming an API it has
+    // never heard of. Note this is stricter than before — calls that carry
+    // their own `auth` (every user/account/reseller method takes
+    // `context.admin`) used to work with the master credentials unset, and
+    // now fail here. See the CHANGELOG entry for 0.2.0.
+    const missing = ['PROVISIONING_URL', 'E2E_ADMIN_USER', 'E2E_ADMIN_PW'].filter(key => !process.env[key])
+    if (missing.length) {
+      throw new TypeError(
+        `@open-xchange/soap-client: missing ${missing.join(', ')}. The module exports bind to the ` +
+        'environment; set these in .env, or use createProvisioningClient({ url, auth }) from ' +
+        "'@open-xchange/soap-client/client' to pass an endpoint and credentials explicitly."
+      )
+    }
+    defaultCreateClient = createClientFactory({
+      url: process.env.PROVISIONING_URL,
+      auth: { login: process.env.E2E_ADMIN_USER, password: process.env.E2E_ADMIN_PW }
+    })
+  }
+  return defaultCreateClient
+}
+
+/**
+ * This function creates a SOAP client for the specified service type, bound to
+ * the env-configured default endpoint (PROVISIONING_URL, E2E_ADMIN_USER/PW).
  * @param {string} type The name of the service type.
  * @returns {Promise<Object>} The SOAP client.
  */
 async function createClientAsync (type) {
+  return getDefaultCreateClient()(type)
+}
+
+/**
+ * Create a SOAP client for the specified service type against a specific
+ * endpoint with specific credentials.
+ * @param {string} type The name of the service type.
+ * @param {string} baseUrl Base URL without trailing slash.
+ * @param {{auth: {login: string, password: string}}} defaultAuth Auth option injected per call.
+ * @returns {Promise<Object>} The SOAP client.
+ */
+async function createTypedClientAsync (type, baseUrl, defaultAuth) {
+  ensureDebugObserver()
   const startMark = `${type}-start`
   const endMark = `${type}-end`
   performance.mark(startMark)
-  const endpoint = `${provisioningUrl}/webservices/${type}`
+  const endpoint = `${baseUrl}/webservices/${type}`
   const url = `${endpoint}/?wsdl`
   // The WSDL fetch itself can hit transient network errors (ECONNRESET,
   // ETIMEDOUT, ...). Without retry here, a single TLS hiccup during
@@ -284,11 +435,21 @@ async function createClientAsync (type) {
           const startMark = `${prop}-start`
           const endMark = `${prop}-end`
           performance.mark(startMark)
-          const soapOptions = { ...provisioningAuth, ...options }
-          if (soapOptions.auth) {
-            // only send login and password instead of complete admin object.
-            // this can fail because of ambiguous namespacing
-            soapOptions.auth = { login: soapOptions.auth.login, password: soapOptions.auth.password }
+          // Pull `auth` out before merging. Spreading `options` wholesale made a
+          // present-but-undefined `auth` (every user/account/reseller method
+          // sends `auth: context.admin`, and a context without a resolved admin
+          // makes that undefined) overwrite the endpoint credentials, so the
+          // call went out unauthenticated even though valid ones were
+          // configured. An absent or undefined `auth` now falls back to the
+          // endpoint default; a real one still wins.
+          const { auth, ...rest } = options ?? {}
+          const soapOptions = { ...defaultAuth, ...rest }
+          if (auth) {
+            // Send login and password only, never the whole admin object:
+            // the extra fields can fail on ambiguous namespacing. `adminLogin`
+            // reads either name the account goes by, so callers may pass an
+            // `admin_user` object straight through (see AdminCredentials).
+            soapOptions.auth = { login: adminLogin(auth), password: auth.password }
           }
 
           try {
@@ -313,4 +474,4 @@ async function createClientAsync (type) {
   })
 }
 
-export { createClientAsync, logSoapError, describeError, shouldAbortRetry, wrapSoapFault, unwrapError, handleFailedAttempt }
+export { createClientAsync, createClientFactory, adminLogin, parseCapabilities, memoizeClient, installTimeoutRejectionFilter, logSoapError, describeError, shouldAbortRetry, wrapSoapFault, unwrapError, handleFailedAttempt }