@open-xchange/soap-client 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-09-11
+
+### Added
+
+- `userService.getMultipleData(context, users)` and `userService.getData(context, user)`. `list` and `listAll` return users with only the id filled, so their results carry no `name`, `display_name` or `primaryEmail` and cannot be compared against desired state. A caller that treats a list result as observed state sees every user as missing and recreates it. `getMultipleData` hydrates a whole set in one round trip; only each entry's id is sent. Both take a user id or an object carrying one, matching `remove`, `getModuleAccess`, `exists` and `changeCapabilities` on the same service, and reject a reference naming no user rather than sending `{ id: undefined }` and getting back an opaque `InvalidDataException`. `getMultipleData` answers `[]` for an empty result, where the raw response would be `undefined` because the element is a `List<User>` that serializes to nothing, and makes no round trip at all for an empty set of ids. It is all or nothing: the operation declares `NoSuchUserException`, so one id disappearing between the `list` and the hydrate rejects the whole call, and a caller that must tolerate that has to fall back to `getData` per id itself.
+- `userService.getUserCapabilities(context, user)` and `contextService.getContextCapabilities(id)`, returning the capability names as an array. Without them a caller can only re-apply capabilities blindly on every reconcile instead of diffing them. The middleware answers these two with a display string rather than a data structure, so the parsing sits here: it joins the set with `", "`, comma and space, and reports an empty set as the sentence `There are no capabilities set for ...`, which becomes `[]`. Handed back raw, that sentence would read as a single capability named after itself, and a freshly created context is the case that hits it.
+
+### Changed
+
+- `resellerUserService` no longer forces `name` as the login. Where an admin object carries both a `login` and a `name` that differ, its calls now send `login`, matching every other service in the package. A reseller call on a context whose admin never resolved now falls back to the configured endpoint credentials as well, instead of throwing a `TypeError` on `context.admin.name`.
+
+### Fixed
+
+- An admin object in the SOAP `admin_user` shape (`{ name, password }`) now authenticates instead of sending `login: undefined`. The transport reads `auth.login`, but the SOAP admin object names the account `name` and only the `auth` element calls it `login`, so a consumer passing its admin object straight through authenticated with no login and the middleware rejected it as a terminal authentication failure. The per-call `auth` accepts both shapes now, `login` winning when both are present. The endpoint credentials given to `createProvisioningClient` are unchanged: that element is only ever `Credentials` and the master admin has no `admin_user` counterpart, so it still requires `{ login, password }` and still throws a `TypeError` at construction without one.
+- `resellerUserService` carried the same bug from the opposite side. It built `auth: { login: context.admin.name }` itself, so an admin already in the `{ login, password }` shape authenticated with no login there. All five of its authenticated methods now send `auth: context.admin` like every other service and go through the same mapping.
+
 ## [0.2.0] - 2026-09-08
 
 ### Added
@@ -141,7 +157,8 @@ 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.2.0...main
+[unreleased]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.2.1...main
+[0.2.1]: https://gitlab.com/openxchange/appsuite/web-foundation/tools/-/compare/soap-client-0.2.0...soap-client-0.2.1
 [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-xchange/soap-client",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "SOAP client for OX App Suite",
   "type": "module",
   "repository": {
@@ -37,7 +37,7 @@
   },
   "devDependencies": {
     "@open-xchange/lint": "^0.3.1",
-    "vitest": "^4.1.7"
+    "vitest": "^5.0.0"
   },
   "scripts": {
     "lint": "eslint .",

package/services/common/context.js

@@ -18,7 +18,7 @@
  * Any use of the work other than as authorized under this license or copyright law is prohibited.
  */
 
-import { createClientAsync, memoizeClient, logSoapError } from '../../soap.js'
+import { createClientAsync, memoizeClient, logSoapError, parseCapabilities } from '../../soap.js'
 
 /**
  * Build a context service bound to a SOAP client constructor.
@@ -149,6 +149,18 @@ export function createContextService (createClient, { mxDomain } = {}) {
     return (await getClient()).getDataAsync({ ctx: { id } })
   }
 
+  /**
+   * The capabilities currently in effect for a context. The middleware answers
+   * with a display string (see `parseCapabilities`), so this returns the names
+   * it lists. Without it a caller can only re-apply capabilities blindly on
+   * every reconcile, never diff them.
+   * @param {number} id The context id.
+   * @returns {Promise<string[]>} Capability names, `[]` when there are none.
+   */
+  async function getContextCapabilities (id) {
+    return parseCapabilities(await (await getClient()).getContextCapabilitiesAsync({ ctx: { id } }))
+  }
+
   /**
    * This function changes the context with the specified ID.
    * @param {Object} ctx The context to change.
@@ -158,7 +170,7 @@ export function createContextService (createClient, { mxDomain } = {}) {
     return (await getClient()).changeAsync({ ctx })
   }
 
-  return { getDefault, remove, create, changeModuleAccessByName, changeCapabilities, getModuleAccess, changeModuleAccess, list, get, change }
+  return { getDefault, remove, create, changeModuleAccessByName, changeCapabilities, getModuleAccess, changeModuleAccess, list, get, change, getContextCapabilities }
 }
 
 // Classic module exports, bound to the env-configured default endpoint.
@@ -175,3 +187,4 @@ export const changeModuleAccess = (...args) => service().changeModuleAccess(...a
 export const list = (...args) => service().list(...args)
 export const get = (...args) => service().get(...args)
 export const change = (...args) => service().change(...args)
+export const getContextCapabilities = (...args) => service().getContextCapabilities(...args)

package/services/common/user.js

@@ -18,13 +18,33 @@
  * Any use of the work other than as authorized under this license or copyright law is prohibited.
  */
 
-import { createClientAsync, memoizeClient, logSoapError } from '../../soap.js'
+import { createClientAsync, memoizeClient, logSoapError, parseCapabilities } from '../../soap.js'
 
 /**
  * Build a user service bound to a SOAP client constructor.
  * @param {(type: string) => Promise<Object>} createClient
  * @returns {Object} The user service.
  */
+/**
+ * Build the `user` element of a request from whatever the caller holds.
+ *
+ * Every older method on this service takes a plain id (`remove(context, 3)`,
+ * `getModuleAccess`, `exists`, `changeCapabilities`), so a caller following the
+ * convention passes one to the newer ones too. Destructuring a number yields
+ * `{ id: undefined }`, and because `user` is `nillable minOccurs="0"` the
+ * request stays schema-valid: the mistake comes back as an opaque
+ * InvalidDataException from the middleware instead of failing here. Accept both
+ * forms, and refuse a reference that names no user at all.
+ *
+ * @param {{id: number}|number} user An id, or an object carrying one.
+ * @returns {{id: number}} The `user` element to send.
+ */
+function userRef (user) {
+  const id = user !== null && typeof user === 'object' ? user.id : user
+  if (id === undefined || id === null) throw new TypeError('userRef: a user id is required')
+  return { id }
+}
+
 export function createUserService (createClient) {
   const getClient = memoizeClient(createClient, 'OXUserService')
 
@@ -125,6 +145,71 @@ export function createUserService (createClient) {
     })
   }
 
+  /**
+   * Hydrate users. `list` and `listAll` fill only the id, so their results
+   * carry no name, display_name or email and cannot be diffed against desired
+   * state; `getMultipleData` returns the full records for a set of ids in one
+   * call. Only the id of each entry is sent, whatever else the caller holds.
+   *
+   * The response element is a `List<User>`, so an empty result serializes to
+   * zero `<return>` elements and node-soap never creates the key. That would
+   * surface as `undefined` rather than an empty list and throw in the caller's
+   * `.map`, so it is normalised here.
+   *
+   * All or nothing: the operation declares `NoSuchUserException`, so if any one
+   * id disappeared between the `list` that produced it and this call, the whole
+   * request rejects and no user is hydrated. A caller that must tolerate a
+   * concurrent deletion has to fall back to `getData` per id itself; this
+   * method will not return partial results.
+   *
+   * @param {Object} context `{ id, admin }`
+   * @param {Array<{id: number}|number>} users The users to hydrate.
+   * @returns {Promise<Array<Object>>} The full user records, `[]` for none.
+   */
+  async function getMultipleData (context, users = []) {
+    const refs = users.map(userRef)
+    if (refs.length === 0) return []
+    return (await (await getClient()).getMultipleDataAsync({
+      ctx: { id: context.id },
+      users: refs,
+      auth: context.admin
+    })) ?? []
+  }
+
+  /**
+   * Hydrate one user. Same reason as getMultipleData; prefer that one for a
+   * set, since it is a single round trip.
+   * @param {Object} context `{ id, admin }`
+   * @param {{id: number}|number} user An id, or an object carrying one.
+   * @returns {Promise<Object>} The full user record.
+   */
+  async function getData (context, user) {
+    const ref = userRef(user)
+    return (await getClient()).getDataAsync({
+      ctx: { id: context.id },
+      user: ref,
+      auth: context.admin
+    })
+  }
+
+  /**
+   * The capabilities currently in effect for a user. The middleware answers
+   * with a display string (see `parseCapabilities`), so this returns the names
+   * it lists. Without it a caller can only re-apply capabilities blindly on
+   * every reconcile, never diff them.
+   * @param {Object} context `{ id, admin }`
+   * @param {{id: number}|number} user An id, or an object carrying one.
+   * @returns {Promise<string[]>} Capability names, `[]` when there are none.
+   */
+  async function getUserCapabilities (context, user) {
+    const ref = userRef(user)
+    return parseCapabilities(await (await getClient()).getUserCapabilitiesAsync({
+      ctx: { id: context.id },
+      user: ref,
+      auth: context.admin
+    }))
+  }
+
   async function listAll (context, includeGuests = false, excludeUsers = []) {
     return (await getClient()).listAsync({
       ctx: { id: context.id },
@@ -134,7 +219,7 @@ export function createUserService (createClient) {
     })
   }
 
-  return { remove, create, change, changeByModuleAccess, changeByModuleAccessName, getModuleAccess, changeCapabilities, exists, list, listAll }
+  return { remove, create, change, changeByModuleAccess, changeByModuleAccessName, getModuleAccess, changeCapabilities, exists, list, listAll, getData, getMultipleData, getUserCapabilities }
 }
 
 // Classic module exports, bound to the env-configured default endpoint.
@@ -153,3 +238,6 @@ export const changeCapabilities = (...args) => service().changeCapabilities(...a
 export const exists = (...args) => service().exists(...args)
 export const list = (...args) => service().list(...args)
 export const listAll = (...args) => service().listAll(...args)
+export const getData = (...args) => service().getData(...args)
+export const getMultipleData = (...args) => service().getMultipleData(...args)
+export const getUserCapabilities = (...args) => service().getUserCapabilities(...args)

package/services/reseller/resellerUser.js

@@ -45,7 +45,7 @@ export function createResellerUserService (createClient) {
     return (await getClient()).changeAsync({
       ctx: { id: context.id },
       usrdata,
-      auth: { login: context.admin.name, password: context.admin.password }
+      auth: context.admin
     })
   }
 
@@ -57,7 +57,7 @@ export function createResellerUserService (createClient) {
     return (await getClient()).getModuleAccessAsync({
       ctx: { id: context.id },
       user: { id: userId },
-      auth: { login: context.admin.name, password: context.admin.password }
+      auth: context.admin
     })
   }
 
@@ -66,7 +66,7 @@ export function createResellerUserService (createClient) {
       ctx: { id: context.id },
       moduleAccess: Object.assign({}, currentAccess, moduleAccess),
       user: { id: userId },
-      auth: { login: context.admin.name, password: context.admin.password }
+      auth: context.admin
     })
   }
 
@@ -75,7 +75,7 @@ export function createResellerUserService (createClient) {
       ctx: { id: context.id },
       access_combination_name: accessCombinationName,
       user: { id: userId },
-      auth: { login: context.admin.name, password: context.admin.password }
+      auth: context.admin
     })
   }
 
@@ -84,7 +84,7 @@ export function createResellerUserService (createClient) {
       ctx: { id: context.id },
       usrdata,
       access_combination_name: 'all',
-      auth: { login: context.admin.name, password: context.admin.password }
+      auth: context.admin
     })
   }
 

package/soap.js

@@ -244,9 +244,65 @@ function handleFailedAttempt (context, label) {
  * @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`.
+ *   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
@@ -256,6 +312,10 @@ function handleFailedAttempt (context, label) {
  */
 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 } }
@@ -385,9 +445,11 @@ async function createTypedClientAsync (type, baseUrl, defaultAuth) {
           const { auth, ...rest } = options ?? {}
           const soapOptions = { ...defaultAuth, ...rest }
           if (auth) {
-            // only send login and password instead of complete admin object.
-            // this can fail because of ambiguous namespacing
-            soapOptions.auth = { login: auth.login, password: auth.password }
+            // 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 {
@@ -412,4 +474,4 @@ async function createTypedClientAsync (type, baseUrl, defaultAuth) {
   })
 }
 
-export { createClientAsync, createClientFactory, memoizeClient, installTimeoutRejectionFilter, logSoapError, describeError, shouldAbortRetry, wrapSoapFault, unwrapError, handleFailedAttempt }
+export { createClientAsync, createClientFactory, adminLogin, parseCapabilities, memoizeClient, installTimeoutRejectionFilter, logSoapError, describeError, shouldAbortRetry, wrapSoapFault, unwrapError, handleFailedAttempt }