@open-xchange/soap-client 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,34 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-08
+
+### Added
+
+- `createProvisioningClient({ url, auth, mxDomain })` (export `@open-xchange/soap-client/client`): builds a provisioning client bound to one endpoint and one set of credentials, so a single process can talk to several middlewares instead of inheriting the process-wide `PROVISIONING_URL`/`E2E_ADMIN_*` binding. Each service is also exported as a `createXService(createClient)` factory.
+
+### Changed
+
+- Importing the library no longer touches process-global state. The `.env` loading, the timeout-swallowing `unhandledRejection` filter and the `DEBUG_SOAP` PerformanceObserver now attach when the env-configured default client is first used, not at import time. The classic module exports (`.../common`, `.../reseller`) behave as before; factory clients never install the rejection filter.
+- `userService.changeByModuleAccessName` and `resellerUserService.changeByModuleAccessName` now reject on SOAP faults instead of swallowing them via `console.error` and resolving successfully. Callers that awaited them silently succeeding on a dead middleware will now see the real fault.
+- The published tarball now carries only the runtime surface (46 files down to 16). Publishing was filtered by a `.npmignore` deny-list, which also disables `.gitignore`, so `test/`, `vitest.config.js` and `catalog-info.yaml` shipped and a local `pnpm publish` packed the whole `coverage/` report. Replaced with a `files` allow-list, which fails safe when files are added.
+- `engines` now declares `node >=20.12`. This documents an existing requirement rather than adding one: `soap.js` and `bin/provision.js` call `process.loadEnvFile`, which landed in Node 20.12 / 21.7. Consumers installing with `engine-strict` on an older Node will now fail at install with a clear reason instead of at runtime with a `TypeError`.
+- Dropped the `main` field. It pointed at a non-existent `index.js` and was never consulted: `exports` declares no `"."` subpath, so a bare `import '@open-xchange/soap-client'` fails with `ERR_PACKAGE_PATH_NOT_EXPORTED` as before.
+- **Breaking:** the classic module exports now require `PROVISIONING_URL`, `E2E_ADMIN_USER` and `E2E_ADMIN_PW` to be set, and throw naming the missing variables on first use. Previously the master credentials could be left unset as long as every call carried its own `auth` (`context.admin`), which most user, account and reseller methods do; those setups now fail fast instead of reaching the middleware. Pass an endpoint and credentials explicitly with `createProvisioningClient({ url, auth })` if the environment binding does not fit.
+
+### Fixed
+
+- `oxaasService.createSharedDomain` now calls the promise-returning `createSharedDomainAsync` binding. It was calling node-soap's callback-style `createSharedDomain`, which returns `undefined` synchronously and treats its second argument as the callback: the call resolved to `undefined` before the request had completed, bypassed the retry and `wrapSoapFault` handling entirely, and threw `TypeError: callback is not a function` from inside node-soap once the response arrived — asynchronously, outside any caller's `try`/`catch`.
+- `contextService.getDefault()` now resolves the first matching context instead of always `undefined`. It indexed the promise returned by `listAsync` rather than the resolved array, so every caller dereferencing the result hit `TypeError: Cannot read properties of undefined`.
+- A call whose `auth` is present but `undefined` no longer sends the request unauthenticated. Every user, account and reseller method passes `auth: context.admin`, so a context without a resolved admin put an `auth: undefined` key into the options; the proxy spread that over the endpoint's configured credentials and wiped them, and the call went out with no auth at all despite valid credentials being configured. `auth` is now pulled out before the merge, so an absent or undefined one falls back to the endpoint default while a real one still wins.
+- A failed SOAP client construction is no longer cached for the lifetime of the process. The per-service client promise was memoized before it settled, so a WSDL fetch that exhausted its retry schedule or hit a non-retryable fault left a rejected promise in place and every later call re-threw that stale error without retrying. Construction is now re-attempted after a failure, which matters most for long-running embedders where one bad startup would otherwise poison the service until restart.
+
+## [0.1.6] - 2026-05-26
+
+### Fixed
+
+- Aborting a non-retryable SOAP fault no longer corrupts the error message. p-retry v8 passes `onFailedAttempt` a context object (`{ error, attemptNumber, retriesLeft, ... }`) rather than the error itself; the abort path was passing that context object to `AbortError`, which stored it verbatim as `.message`. p-retry rejects with that `AbortError` as-is (it only unwraps `AbortError`s thrown by the retried function, not by the callback), so consumers received an error whose `.message` was an object and crashed with `error.message.includes is not a function` — masking the real fault. We now pass the inner `context.error`, keeping `.message` a string and letting `wrapSoapFault` recover the fault downstream. Both retry sites (WSDL fetch and per-method calls) share one `handleFailedAttempt` helper.
+
 ## [0.1.5] - 2026-05-26
 
 ### Fixed
@@ -113,7 +141,9 @@ All notable changes to this project will be documented in this file.
 
 - Initial release: extract SOAP client into its own library
 
-[unreleased]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.1.5...main
+[unreleased]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.2.0...main
+[0.2.0]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.1.6...soap-client-0.2.0
+[0.1.6]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.1.5...soap-client-0.1.6
 [0.1.5]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.1.4...soap-client-0.1.5
 [0.1.4]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.1.3...soap-client-0.1.4
 [0.1.3]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.1.2...soap-client-0.1.3

package/README.md

@@ -106,6 +106,29 @@ const context = await contextService.create({ name: 'my-context' })
 const user = await userService.create(context, { name: 'myuser', email1: 'user@example.com' })
 ```
 
+### Embedding: one client per endpoint
+
+The module exports above bind to `PROVISIONING_URL`/`E2E_ADMIN_USER`/`E2E_ADMIN_PW`
+on first use — right for the CLI and test runs, wrong for a long-running process
+that talks to many middlewares. For that, build clients explicitly:
+
+```js
+import { createProvisioningClient } from '@open-xchange/soap-client/client'
+
+const client = createProvisioningClient({
+  url: 'http://core-mw-admin.appsuite-main.svc',
+  auth: { login: 'oxadminmaster', password: secret },
+  mxDomain: 'box.ox.io' // optional, for generated context-admin addresses
+})
+await client.contextService.list('defaultcontext')
+```
+
+Factory clients install no process-global handlers and each carries its own
+endpoint, credentials and retry/fault handling. They read the environment in
+exactly two places: `MX_DOMAIN` as the fallback when `mxDomain` is omitted, and
+`DEBUG_SOAP` for timing output. Pass `mxDomain` explicitly if an ambient
+`MX_DOMAIN` must not leak into generated context-admin addresses.
+
 ## Configuration
 
 Set up your `.env` file with the required environment variables. See `.env.default` for an example.

package/client.js

@@ -0,0 +1,72 @@
+/**
+ * @copyright Copyright (c) Open-Xchange GmbH, Germany <info@open-xchange.com>
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with OX App Suite. If not, see <https://www.gnu.org/licenses/agpl-3.0.txt>.
+ *
+ * Any use of the work other than as authorized under this license or copyright law is prohibited.
+ */
+
+import { createClientFactory } from './soap.js'
+import { createContextService } from './services/common/context.js'
+import { createUserService } from './services/common/user.js'
+import { createUtilService } from './services/common/util.js'
+import { createSecondaryAccountService } from './services/secondaryAccount.js'
+import { createSharedAccountService } from './services/sharedAccount.js'
+import { createOxaasService } from './services/reseller/oxaas.js'
+import { createResellerContextService } from './services/reseller/resellerContext.js'
+import { createResellerUserService } from './services/reseller/resellerUser.js'
+
+/**
+ * @typedef {object} ProvisioningClientOptions
+ * @property {string} url  Base URL of the provisioning API (the middleware
+ *   admin endpoint), without the `/webservices` suffix.
+ * @property {{login: string, password: string}} auth  Master admin credentials.
+ * @property {string} [mxDomain]  Domain for generated context-admin email
+ *   addresses; defaults to the MX_DOMAIN environment variable.
+ */
+
+/**
+ * Create a provisioning client bound to one endpoint and one set of
+ * credentials. Any number of clients coexist in a single process; the only
+ * environment reads are the mxDomain fallback (MX_DOMAIN) and DEBUG_SOAP, and
+ * no process-global state is touched — unlike the classic module exports, which
+ * bind to PROVISIONING_URL / E2E_ADMIN_USER / E2E_ADMIN_PW on first use and
+ * install the timeout-rejection filter for CLI compatibility.
+ *
+ * @param {ProvisioningClientOptions} options
+ * @returns {{
+ *   contextService: Object,
+ *   userService: Object,
+ *   utilService: Object,
+ *   secondaryAccountService: Object,
+ *   sharedAccountService: Object,
+ *   oxaasService: Object,
+ *   resellerContextService: Object,
+ *   resellerUserService: Object
+ * }}
+ */
+export function createProvisioningClient ({ url, auth, mxDomain } = {}) {
+  const createClient = createClientFactory({ url, auth })
+  return {
+    contextService: createContextService(createClient, { mxDomain }),
+    userService: createUserService(createClient),
+    utilService: createUtilService(createClient),
+    secondaryAccountService: createSecondaryAccountService(createClient),
+    sharedAccountService: createSharedAccountService(createClient),
+    oxaasService: createOxaasService(createClient),
+    resellerContextService: createResellerContextService(createClient),
+    resellerUserService: createResellerUserService(createClient)
+  }
+}

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "@open-xchange/soap-client",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "SOAP client for OX App Suite",
-  "main": "index.js",
   "type": "module",
   "repository": {
     "type": "git",
@@ -11,26 +10,38 @@
   },
   "exports": {
     "./common": "./services/common/index.js",
-    "./reseller": "./services/reseller/index.js"
+    "./reseller": "./services/reseller/index.js",
+    "./client": "./client.js"
   },
+  "files": [
+    "bin/",
+    "services/",
+    "client.js",
+    "soap.js",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "bin": {
     "provision": "./bin/provision.js"
   },
   "keywords": [],
   "author": "",
   "license": "AGPL-3.0-or-later",
+  "engines": {
+    "node": ">=20.12"
+  },
   "dependencies": {
-    "commander": "^14.0.3",
+    "commander": "^15.0.0",
     "p-retry": "^8.0.0",
     "soap": "^1.9.3"
   },
   "devDependencies": {
-    "vitest": "^4.1.7",
-    "@open-xchange/lint": "0.3.0"
+    "@open-xchange/lint": "^0.3.1",
+    "vitest": "^4.1.7"
   },
   "scripts": {
     "lint": "eslint .",
-    "test": "vitest --run",
+    "test": "vitest --run --coverage",
     "provision": "node ./bin/provision.js"
   }
 }

package/services/common/context.js

@@ -18,147 +18,160 @@
  * Any use of the work other than as authorized under this license or copyright law is prohibited.
  */
 
-import { createClientAsync, logSoapError } from '../../soap.js'
-
-let OXContextService
-function getClient () {
-  if (!OXContextService) OXContextService = createClientAsync('OXContextService')
-  return OXContextService
-}
+import { createClientAsync, memoizeClient, logSoapError } from '../../soap.js'
 
 /**
- * This function retrieves the default context from the OXContextService.
- * @returns {Promise<Object>} The first result from the listAsync method call.
+ * Build a context service bound to a SOAP client constructor.
+ * @param {(type: string) => Promise<Object>} createClient
+ * @param {{mxDomain?: string}} [options] mxDomain feeds the default context
+ *   admin's email addresses; falls back to MX_DOMAIN from the environment.
+ * @returns {Object} The context service.
  */
-export async function getDefault () {
-  return (await getClient()).listAsync({ search_pattern: 'defaultcontext' })[0]
-}
+export function createContextService (createClient, { mxDomain } = {}) {
+  const getClient = memoizeClient(createClient, 'OXContextService')
+  const domain = () => mxDomain ?? process.env.MX_DOMAIN
 
-/**
- * This function removes the context with the specified ID.
- * Fire-and-forget operation - spawns a separate process to avoid blocking.
- * @param {number} id The ID of the context to remove.
- */
-export async function remove (id) {
-  return (await getClient()).deleteAsync({ ctx: { id } })
-}
+  /**
+   * This function retrieves the default context from the OXContextService.
+   * @returns {Promise<Object>} The first result from the listAsync method call.
+   */
+  async function getDefault () {
+    return (await (await getClient()).listAsync({ search_pattern: 'defaultcontext' }))?.[0]
+  }
 
-/**
- * This function creates a new context.
- * @param {Object} ctx The context to create.
- * @param {Object} adminUser The admin user of the context.
- *    Defaults to:
- *    ```JSON
- *    {
-        name: 'oxadmin',
-        password: 'secret',
-        display_name: 'context admin',
-        sur_name: 'admin',
-        given_name: 'context',
-        email1: `oxadmin@${process.env.MX_DOMAIN}`,
-        primaryEmail: `oxadmin@${process.env.MX_DOMAIN}`
-      }
-      All properties are needed and will be inserted if not provided.
-      ```
- * @returns {Promise<Object>} The created context.
- */
-export async function create (ctx = {}, adminUser = {}, accessCombinationName = 'all') {
-  return (await getClient())
-    .createAsync({
-      ctx,
-      admin_user: Object.assign({
-        name: 'oxadmin',
-        password: 'secret',
-        display_name: 'context admin',
-        sur_name: 'admin',
-        given_name: 'context',
-        email1: `oxadmin@${process.env.MX_DOMAIN}`,
-        primaryEmail: `oxadmin@${process.env.MX_DOMAIN}`
-      }, adminUser)
-    })
-    .then(async context => {
-      await changeModuleAccessByName(context.id, accessCombinationName)
-      return context
-    })
-    .catch(e => {
-      logSoapError(e)
-      throw e
-    })
-}
+  /**
+   * This function removes the context with the specified ID.
+   * @param {number} id The ID of the context to remove.
+   */
+  async function remove (id) {
+    return (await getClient()).deleteAsync({ ctx: { id } })
+  }
 
-/**
- * This function changes the module access of the specified context.
- * @param {number} id The ID of the context.
- * @param {string} access_combination_name The name of the access combination to set.
- * @returns {Promise<void>}
- */
-// eslint-disable-next-line camelcase
-export async function changeModuleAccessByName (id, access_combination_name) {
+  /**
+   * This function creates a new context.
+   * @param {Object} ctx The context to create (name, capabilities, config,
+   *   maxQuota, loginMappings, ... — passed through to the SOAP Context object).
+   * @param {Object} adminUser The admin user of the context. Missing fields are
+   *   filled with the oxadmin defaults (email under the configured mxDomain).
+   * @param {string} accessCombinationName Access combination applied after create.
+   * @returns {Promise<Object>} The created context.
+   */
+  async function create (ctx = {}, adminUser = {}, accessCombinationName = 'all') {
+    return (await getClient())
+      .createAsync({
+        ctx,
+        admin_user: Object.assign({
+          name: 'oxadmin',
+          password: 'secret',
+          display_name: 'context admin',
+          sur_name: 'admin',
+          given_name: 'context',
+          email1: `oxadmin@${domain()}`,
+          primaryEmail: `oxadmin@${domain()}`
+        }, adminUser)
+      })
+      .then(async context => {
+        await changeModuleAccessByName(context.id, accessCombinationName)
+        return context
+      })
+      .catch(e => {
+        logSoapError(e)
+        throw e
+      })
+  }
+
+  /**
+   * This function changes the module access of the specified context.
+   * @param {number} id The ID of the context.
+   * @param {string} access_combination_name The name of the access combination to set.
+   * @returns {Promise<void>}
+   */
   // eslint-disable-next-line camelcase
-  return (await getClient()).changeModuleAccessByNameAsync({ ctx: { id }, access_combination_name })
-}
+  async function changeModuleAccessByName (id, access_combination_name) {
+    // eslint-disable-next-line camelcase
+    return (await getClient()).changeModuleAccessByNameAsync({ ctx: { id }, access_combination_name })
+  }
 
-/**
- * This function changes the capabilities of the specified context.
- * @param {number} id The ID of the context.
- * @param {string} capsToAdd The capabilities to add.
- * @param {string} capsToRemove The capabilities to remove.
- * @returns {Promise<void>}
- */
-export async function changeCapabilities (id, capsToAdd, capsToRemove) {
-  const data = {}
-  if (capsToAdd) data.capsToAdd = capsToAdd
-  if (capsToRemove) data.capsToRemove = capsToRemove
-  return (await getClient()).changeCapabilitiesAsync({ ctx: { id }, ...data })
-}
+  /**
+   * This function changes the capabilities of the specified context.
+   * @param {number} id The ID of the context.
+   * @param {string} capsToAdd The capabilities to add.
+   * @param {string} capsToRemove The capabilities to remove.
+   * @returns {Promise<void>}
+   */
+  async function changeCapabilities (id, capsToAdd, capsToRemove) {
+    const data = {}
+    if (capsToAdd) data.capsToAdd = capsToAdd
+    if (capsToRemove) data.capsToRemove = capsToRemove
+    return (await getClient()).changeCapabilitiesAsync({ ctx: { id }, ...data })
+  }
 
-/**
- * This function retrieves the module access of the specified context.
- * @param {number} id The ID of the context.
- * @returns {Promise<Object>} The module access of the specified context.
- */
-export async function getModuleAccess (id) {
-  return (await getClient()).getModuleAccessAsync({ ctx: { id } })
-}
-/**
- * This function changes the module access of the specified context.
- * @param {number} id The ID of the context.
- * @param {Object} moduleAccess The module access to set.
- * @returns {Promise<void>}
- */
-export async function changeModuleAccess (id, moduleAccess) {
-  const currentAccess = await getModuleAccess(id)
-  return (await getClient()).changeModuleAccessAsync({ ctx: { id }, access: { ...currentAccess, ...moduleAccess } })
-}
+  /**
+   * This function retrieves the module access of the specified context.
+   * @param {number} id The ID of the context.
+   * @returns {Promise<Object>} The module access of the specified context.
+   */
+  async function getModuleAccess (id) {
+    return (await getClient()).getModuleAccessAsync({ ctx: { id } })
+  }
 
-/**
- * Search for contexts.
- * @param {String} searchPattern The pattern to search for
- * @param {Object} options Additional options
- * @param {Boolean} options.excludeDisabled Exclude disabled contexts from the search results (default: true)
- * @returns {Promise<Array<Object>>} The list of contexts that match the search pattern.
- */
-export async function list (searchPattern, { excludeDisabled } = { excludeDisabled: true }) {
-  return (await getClient()).listAsync({ search_pattern: searchPattern, exclude_disabled: excludeDisabled }).catch(e => {
-    logSoapError(e)
-    return []
-  })
-}
+  /**
+   * This function changes the module access of the specified context.
+   * @param {number} id The ID of the context.
+   * @param {Object} moduleAccess The module access to set.
+   * @returns {Promise<void>}
+   */
+  async function changeModuleAccess (id, moduleAccess) {
+    const currentAccess = await getModuleAccess(id)
+    return (await getClient()).changeModuleAccessAsync({ ctx: { id }, access: { ...currentAccess, ...moduleAccess } })
+  }
 
-/**
- * This function retrieves the context with the specified ID.
- * @param {number} id The ID of the context to retrieve.
- * @returns {Promise<Object>} The context with the specified ID.
- */
-export async function get (id) {
-  return (await getClient()).getDataAsync({ ctx: { id } })
-}
+  /**
+   * Search for contexts.
+   * @param {String} searchPattern The pattern to search for
+   * @param {Object} options Additional options
+   * @param {Boolean} options.excludeDisabled Exclude disabled contexts from the search results (default: true)
+   * @returns {Promise<Array<Object>>} The list of contexts that match the search pattern.
+   */
+  async function list (searchPattern, { excludeDisabled } = { excludeDisabled: true }) {
+    return (await getClient()).listAsync({ search_pattern: searchPattern, exclude_disabled: excludeDisabled }).catch(e => {
+      logSoapError(e)
+      return []
+    })
+  }
 
-/**
- * This function changes the context with the specified ID.
- * @param {Object} ctx The context to change.
- * @returns {Promise<void>}
- */
-export async function change (ctx) {
-  return (await getClient()).changeAsync({ ctx })
+  /**
+   * This function retrieves the context with the specified ID.
+   * @param {number} id The ID of the context to retrieve.
+   * @returns {Promise<Object>} The context with the specified ID.
+   */
+  async function get (id) {
+    return (await getClient()).getDataAsync({ ctx: { id } })
+  }
+
+  /**
+   * This function changes the context with the specified ID.
+   * @param {Object} ctx The context to change.
+   * @returns {Promise<void>}
+   */
+  async function change (ctx) {
+    return (await getClient()).changeAsync({ ctx })
+  }
+
+  return { getDefault, remove, create, changeModuleAccessByName, changeCapabilities, getModuleAccess, changeModuleAccess, list, get, change }
 }
+
+// Classic module exports, bound to the env-configured default endpoint.
+let defaultService
+const service = () => (defaultService ??= createContextService(createClientAsync))
+
+export const getDefault = (...args) => service().getDefault(...args)
+export const remove = (...args) => service().remove(...args)
+export const create = (...args) => service().create(...args)
+export const changeModuleAccessByName = (...args) => service().changeModuleAccessByName(...args)
+export const changeCapabilities = (...args) => service().changeCapabilities(...args)
+export const getModuleAccess = (...args) => service().getModuleAccess(...args)
+export const changeModuleAccess = (...args) => service().changeModuleAccess(...args)
+export const list = (...args) => service().list(...args)
+export const get = (...args) => service().get(...args)
+export const change = (...args) => service().change(...args)