@open-xchange/soap-client 0.1.6 → 0.2.1

package/services/common/user.js

@@ -18,117 +18,226 @@
  * Any use of the work other than as authorized under this license or copyright law is prohibited.
  */
 
-import { createClientAsync, logSoapError } from '../../soap.js'
-
-let OXUserService
-function getClient () {
-  if (!OXUserService) OXUserService = createClientAsync('OXUserService')
-  return OXUserService
-}
+import { createClientAsync, memoizeClient, logSoapError, parseCapabilities } from '../../soap.js'
 
 /**
- * This function removes the user with the specified context and user ID.
- * @param {Object} context The context of the user to be removed.
- * @param {number} userId The ID of the user to be removed.
- * @returns {Promise<Boolean>} Returns true if it could remove the user and false if it could not
+ * Build a user service bound to a SOAP client constructor.
+ * @param {(type: string) => Promise<Object>} createClient
+ * @returns {Object} The user service.
  */
-export async function remove (context, userId) {
-  return (await getClient()).deleteAsync({
-    ctx: { id: context.id },
-    user: { id: userId },
-    auth: context.admin
-  }).catch(logSoapError)
-}
-
 /**
- * This function creates a new user.
- * @param {Object} context The context of the user to be created.
- * @param {Object} usrdata The user to create.
- * @returns {Promise<Object>} The created user.
+ * 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.
  */
-export async function create (context, usrdata) {
-  return (await getClient()).createAsync({
-    ctx: { id: context.id },
-    usrdata,
-    auth: context.admin
-  })
+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 }
 }
 
-/**
- * This function changes the context with the specified ID.
- * @param {Object} context The context of the user to be changed.
- * @param {Object} usrdata The user to change.
- * @returns {Promise<void>}
- */
-export async function change (context, usrdata) {
-  return (await getClient()).changeAsync({
-    ctx: { id: context.id },
-    usrdata,
-    auth: context.admin
-  })
-}
+export function createUserService (createClient) {
+  const getClient = memoizeClient(createClient, 'OXUserService')
 
-export async function changeByModuleAccess (context, userId, currentAccess, moduleAccess) {
-  return (await getClient()).changeByModuleAccessAsync({
-    ctx: { id: context.id },
-    moduleAccess: Object.assign({}, currentAccess, moduleAccess),
-    user: { id: userId },
-    auth: context.admin
-  })
-}
+  /**
+   * This function removes the user with the specified context and user ID.
+   * @param {Object} context The context of the user to be removed.
+   * @param {number} userId The ID of the user to be removed.
+   * @returns {Promise<Boolean>} Returns true if it could remove the user and false if it could not
+   */
+  async function remove (context, userId) {
+    return (await getClient()).deleteAsync({
+      ctx: { id: context.id },
+      user: { id: userId },
+      auth: context.admin
+    }).catch(logSoapError)
+  }
 
-export async function changeByModuleAccessName (context, userId, accessCombinationName) {
-  return (await getClient()).changeByModuleAccessNameAsync({
-    ctx: { id: context.id },
-    access_combination_name: accessCombinationName,
-    user: { id: userId },
-    auth: context.admin
-  }).catch(error => console.error('Module access change error:', error))
-}
+  /**
+   * This function creates a new user.
+   * @param {Object} context The context of the user to be created.
+   * @param {Object} usrdata The user to create.
+   * @returns {Promise<Object>} The created user.
+   */
+  async function create (context, usrdata) {
+    return (await getClient()).createAsync({
+      ctx: { id: context.id },
+      usrdata,
+      auth: context.admin
+    })
+  }
 
-export async function getModuleAccess (context, userId) {
-  return (await getClient()).getModuleAccessAsync({
-    ctx: { id: context.id },
-    user: { id: userId },
-    auth: context.admin
-  }).then(
-    (res) => res
-  )
-}
+  /**
+   * This function changes the user with the specified data. Only the fields
+   * present in usrdata are sent.
+   * @param {Object} context The context of the user to be changed.
+   * @param {Object} usrdata The user to change.
+   * @returns {Promise<void>}
+   */
+  async function change (context, usrdata) {
+    return (await getClient()).changeAsync({
+      ctx: { id: context.id },
+      usrdata,
+      auth: context.admin
+    })
+  }
 
-export async function changeCapabilities (context, userId, capsToAdd, capsToRemove) {
-  const data = {
-    ctx: { id: context.id },
-    user: { id: userId },
-    auth: context.admin
+  async function changeByModuleAccess (context, userId, currentAccess, moduleAccess) {
+    return (await getClient()).changeByModuleAccessAsync({
+      ctx: { id: context.id },
+      moduleAccess: Object.assign({}, currentAccess, moduleAccess),
+      user: { id: userId },
+      auth: context.admin
+    })
   }
-  if (capsToAdd) data.capsToAdd = capsToAdd
-  if (capsToRemove) data.capsToRemove = capsToRemove
-  return (await getClient()).changeCapabilitiesAsync(data)
-}
 
-export async function exists (context, userId) {
-  return (await getClient()).existsAsync({
-    ctx: { id: context.id },
-    user: { id: userId },
-    auth: context.admin
-  })
-}
+  async function changeByModuleAccessName (context, userId, accessCombinationName) {
+    return (await getClient()).changeByModuleAccessNameAsync({
+      ctx: { id: context.id },
+      access_combination_name: accessCombinationName,
+      user: { id: userId },
+      auth: context.admin
+    })
+  }
 
-export async function list (context, searchPattern, includeGuests = false) {
-  return (await getClient()).listAsync({
-    ctx: { id: context.id },
-    search_pattern: searchPattern,
-    include_guests: includeGuests,
-    auth: context.admin
-  })
-}
+  async function getModuleAccess (context, userId) {
+    return (await getClient()).getModuleAccessAsync({
+      ctx: { id: context.id },
+      user: { id: userId },
+      auth: context.admin
+    })
+  }
+
+  async function changeCapabilities (context, userId, capsToAdd, capsToRemove) {
+    const data = {
+      ctx: { id: context.id },
+      user: { id: userId },
+      auth: context.admin
+    }
+    if (capsToAdd) data.capsToAdd = capsToAdd
+    if (capsToRemove) data.capsToRemove = capsToRemove
+    return (await getClient()).changeCapabilitiesAsync(data)
+  }
+
+  async function exists (context, userId) {
+    return (await getClient()).existsAsync({
+      ctx: { id: context.id },
+      user: { id: userId },
+      auth: context.admin
+    })
+  }
+
+  async function list (context, searchPattern, includeGuests = false) {
+    return (await getClient()).listAsync({
+      ctx: { id: context.id },
+      search_pattern: searchPattern,
+      include_guests: includeGuests,
+      auth: context.admin
+    })
+  }
+
+  /**
+   * 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
+    }))
+  }
 
-export async function listAll (context, includeGuests = false, excludeUsers = []) {
-  return (await getClient()).listAsync({
-    ctx: { id: context.id },
-    include_guests: includeGuests,
-    exclude_users: excludeUsers,
-    auth: context.admin
-  })
+  async function listAll (context, includeGuests = false, excludeUsers = []) {
+    return (await getClient()).listAsync({
+      ctx: { id: context.id },
+      include_guests: includeGuests,
+      exclude_users: excludeUsers,
+      auth: context.admin
+    })
+  }
+
+  return { remove, create, change, changeByModuleAccess, changeByModuleAccessName, getModuleAccess, changeCapabilities, exists, list, listAll, getData, getMultipleData, getUserCapabilities }
 }
+
+// Classic module exports, bound to the env-configured default endpoint.
+// Note: changeByModuleAccessName used to swallow SOAP errors via console.error;
+// it now rejects like every other operation (see CHANGELOG, Unreleased).
+let defaultService
+const service = () => (defaultService ??= createUserService(createClientAsync))
+
+export const remove = (...args) => service().remove(...args)
+export const create = (...args) => service().create(...args)
+export const change = (...args) => service().change(...args)
+export const changeByModuleAccess = (...args) => service().changeByModuleAccess(...args)
+export const changeByModuleAccessName = (...args) => service().changeByModuleAccessName(...args)
+export const getModuleAccess = (...args) => service().getModuleAccess(...args)
+export const changeCapabilities = (...args) => service().changeCapabilities(...args)
+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/common/util.js

@@ -18,18 +18,32 @@
  * Any use of the work other than as authorized under this license or copyright law is prohibited.
  */
 
-import { createClientAsync } from '../../soap.js'
+import { createClientAsync, memoizeClient } from '../../soap.js'
 
 /**
- * This function retrieves the ID of the first filestorage.
- * @returns {Promise<number>} The ID of the first filestorage.
+ * Build a util service bound to a SOAP client constructor.
+ * @param {(type: string) => Promise<Object>} createClient
+ * @returns {Object} The util service.
  */
-let fileStoreId
+export function createUtilService (createClient) {
+  const getClient = memoizeClient(createClient, 'OXUtilService')
+  let fileStoreId
 
-export async function getFilestorageId () {
-  const OXUtilService = createClientAsync('OXUtilService')
+  /**
+   * This function retrieves the ID of the first filestorage.
+   * @returns {Promise<number>} The ID of the first filestorage.
+   */
+  async function getFilestorageId () {
+    if (fileStoreId) return fileStoreId
+    fileStoreId = (await (await getClient()).listFilestoreAsync())[0]?.id
+    return fileStoreId
+  }
 
-  if (fileStoreId) return fileStoreId
-  fileStoreId = (await (await OXUtilService).listFilestoreAsync())[0]?.id
-  return fileStoreId
+  return { getFilestorageId }
 }
+
+// Classic module export, bound to the env-configured default endpoint.
+let defaultService
+const service = () => (defaultService ??= createUtilService(createClientAsync))
+
+export const getFilestorageId = (...args) => service().getFilestorageId(...args)

package/services/reseller/oxaas.js

@@ -18,18 +18,30 @@
  * Any use of the work other than as authorized under this license or copyright law is prohibited.
  */
 
-import { createClientAsync } from '../../soap.js'
+import { createClientAsync, memoizeClient } from '../../soap.js'
 
-let OXaaSService
-function getClient () {
-  if (!OXaaSService) OXaaSService = createClientAsync('OXaaSService')
-  return OXaaSService
-}
+/**
+ * Build an OXaaS service bound to a SOAP client constructor.
+ * @param {(type: string) => Promise<Object>} createClient
+ * @returns {Object} The OXaaS service.
+ */
+export function createOxaasService (createClient) {
+  const getClient = memoizeClient(createClient, 'OXaaSService')
 
-export async function setMailQuota (data) {
-  return (await getClient()).setMailQuotaAsync(data)
-}
+  async function setMailQuota (data) {
+    return (await getClient()).setMailQuotaAsync(data)
+  }
 
-export async function createSharedDomain (data) {
-  return (await getClient()).createSharedDomain(data)
+  async function createSharedDomain (data) {
+    return (await getClient()).createSharedDomainAsync(data)
+  }
+
+  return { setMailQuota, createSharedDomain }
 }
+
+// Classic module exports, bound to the env-configured default endpoint.
+let defaultService
+const service = () => (defaultService ??= createOxaasService(createClientAsync))
+
+export const setMailQuota = (...args) => service().setMailQuota(...args)
+export const createSharedDomain = (...args) => service().createSharedDomain(...args)

package/services/reseller/resellerContext.js

@@ -18,42 +18,58 @@
  * Any use of the work other than as authorized under this license or copyright law is prohibited.
  */
 
-import { createClientAsync, logSoapError } from '../../soap.js'
+import { createClientAsync, memoizeClient, logSoapError } from '../../soap.js'
 
-let OXResellerContextService
-function getClient () {
-  if (!OXResellerContextService) OXResellerContextService = createClientAsync('OXResellerContextService')
-  return OXResellerContextService
-}
+/**
+ * Build a reseller-context service bound to a SOAP client constructor.
+ * @param {(type: string) => Promise<Object>} createClient
+ * @returns {Object} The reseller context service.
+ */
+export function createResellerContextService (createClient) {
+  const getClient = memoizeClient(createClient, 'OXResellerContextService')
 
-export async function create (data) {
-  return (await getClient()).createAsync(data)
-}
+  async function create (data) {
+    return (await getClient()).createAsync(data)
+  }
 
-export async function remove (contextId) {
-  return (await getClient()).deleteAsync({
-    ctx: { id: contextId }
-  }).catch(logSoapError)
-}
+  async function remove (contextId) {
+    return (await getClient()).deleteAsync({
+      ctx: { id: contextId }
+    }).catch(logSoapError)
+  }
 
-export async function change (ctx) {
-  return (await getClient()).changeAsync({ ctx })
-}
+  async function change (ctx) {
+    return (await getClient()).changeAsync({ ctx })
+  }
 
-export async function get (id) {
-  return (await getClient()).getDataAsync({ ctx: { id } })
-}
+  async function get (id) {
+    return (await getClient()).getDataAsync({ ctx: { id } })
+  }
 
-export async function getModuleAccess (id) {
-  return (await getClient()).getModuleAccessAsync({ ctx: id })
-}
+  async function getModuleAccess (id) {
+    return (await getClient()).getModuleAccessAsync({ ctx: id })
+  }
 
-export async function changeModuleAccess (id, access) {
-  const currentAccess = await getModuleAccess(id)
+  async function changeModuleAccess (id, access) {
+    const currentAccess = await getModuleAccess(id)
+    return (await getClient()).changeModuleAccessAsync({ ctx: { id }, access: { ...currentAccess, ...access } })
+  }
 
-  return (await getClient()).changeModuleAccessAsync({ ctx: { id }, access: { ...currentAccess, ...access } })
-}
+  async function listAll (data) {
+    return (await getClient()).listAllAsync(data)
+  }
 
-export async function listAll (data) {
-  return (await getClient()).listAllAsync(data)
+  return { create, remove, change, get, getModuleAccess, changeModuleAccess, listAll }
 }
+
+// Classic module exports, bound to the env-configured default endpoint.
+let defaultService
+const service = () => (defaultService ??= createResellerContextService(createClientAsync))
+
+export const create = (...args) => service().create(...args)
+export const remove = (...args) => service().remove(...args)
+export const change = (...args) => service().change(...args)
+export const get = (...args) => service().get(...args)
+export const getModuleAccess = (...args) => service().getModuleAccess(...args)
+export const changeModuleAccess = (...args) => service().changeModuleAccess(...args)
+export const listAll = (...args) => service().listAll(...args)

package/services/reseller/resellerUser.js

@@ -18,76 +18,94 @@
  * Any use of the work other than as authorized under this license or copyright law is prohibited.
  */
 
-import { createClientAsync, logSoapError } from '../../soap.js'
-
-let OXResellerUserService
-function getClient () {
-  if (!OXResellerUserService) OXResellerUserService = createClientAsync('OXResellerUserService')
-  return OXResellerUserService
-}
-
-export async function remove (contextId, userId) {
-  return (await getClient()).deleteAsync({
-    ctx: { id: contextId },
-    user: { id: userId }
-  }).catch(logSoapError)
-}
+import { createClientAsync, memoizeClient, logSoapError } from '../../soap.js'
 
 /**
- * This function changes the context with the specified ID.
- * @param {Object} context The context of the user to be changed.
- * @param {Object} usrdata The user to change.
- * @returns {Promise<void>}
+ * Build a reseller-user service bound to a SOAP client constructor.
+ * @param {(type: string) => Promise<Object>} createClient
+ * @returns {Object} The reseller user service.
  */
-export async function change (context, usrdata) {
-  return (await getClient()).changeAsync({
-    ctx: { id: context.id },
-    usrdata,
-    auth: { login: context.admin.name, password: context.admin.password }
-  })
-}
+export function createResellerUserService (createClient) {
+  const getClient = memoizeClient(createClient, 'OXResellerUserService')
 
-export async function get (data) {
-  return (await getClient()).getDataAsync(data)
-}
+  async function remove (contextId, userId) {
+    return (await getClient()).deleteAsync({
+      ctx: { id: contextId },
+      user: { id: userId }
+    }).catch(logSoapError)
+  }
 
-export async function getModuleAccess (context, userId) {
-  return (await getClient()).getModuleAccessAsync({
-    ctx: { id: context.id },
-    user: { id: userId },
-    auth: { login: context.admin.name, password: context.admin.password }
-  }).then(
-    (res) => res
-  )
-}
+  /**
+   * This function changes the user with the specified data.
+   * @param {Object} context The context of the user to be changed.
+   * @param {Object} usrdata The user to change.
+   * @returns {Promise<void>}
+   */
+  async function change (context, usrdata) {
+    return (await getClient()).changeAsync({
+      ctx: { id: context.id },
+      usrdata,
+      auth: context.admin
+    })
+  }
 
-export async function changeByModuleAccess (context, userId, currentAccess, moduleAccess) {
-  return (await getClient()).changeByModuleAccessAsync({
-    ctx: { id: context.id },
-    moduleAccess: Object.assign({}, currentAccess, moduleAccess),
-    user: { id: userId },
-    auth: { login: context.admin.name, password: context.admin.password }
-  })
-}
+  async function get (data) {
+    return (await getClient()).getDataAsync(data)
+  }
 
-export async function changeByModuleAccessName (context, userId, accessCombinationName) {
-  return (await getClient()).changeByModuleAccessNameAsync({
-    ctx: { id: context.id },
-    access_combination_name: accessCombinationName,
-    user: { id: userId },
-    auth: { login: context.admin.name, password: context.admin.password }
-  }).catch(error => console.error('Module access change error: ', error))
-}
+  async function getModuleAccess (context, userId) {
+    return (await getClient()).getModuleAccessAsync({
+      ctx: { id: context.id },
+      user: { id: userId },
+      auth: context.admin
+    })
+  }
 
-export async function createByModuleAccessName (context, usrdata) {
-  return (await getClient()).createByModuleAccessNameAsync({
-    ctx: { id: context.id },
-    usrdata,
-    access_combination_name: 'all',
-    auth: { login: context.admin.name, password: context.admin.password }
-  })
-}
+  async function changeByModuleAccess (context, userId, currentAccess, moduleAccess) {
+    return (await getClient()).changeByModuleAccessAsync({
+      ctx: { id: context.id },
+      moduleAccess: Object.assign({}, currentAccess, moduleAccess),
+      user: { id: userId },
+      auth: context.admin
+    })
+  }
+
+  async function changeByModuleAccessName (context, userId, accessCombinationName) {
+    return (await getClient()).changeByModuleAccessNameAsync({
+      ctx: { id: context.id },
+      access_combination_name: accessCombinationName,
+      user: { id: userId },
+      auth: context.admin
+    })
+  }
+
+  async function createByModuleAccessName (context, usrdata) {
+    return (await getClient()).createByModuleAccessNameAsync({
+      ctx: { id: context.id },
+      usrdata,
+      access_combination_name: 'all',
+      auth: context.admin
+    })
+  }
 
-export async function listAll (data) {
-  return await (await getClient()).listAllAsync(data)
+  async function listAll (data) {
+    return (await getClient()).listAllAsync(data)
+  }
+
+  return { remove, change, get, getModuleAccess, changeByModuleAccess, changeByModuleAccessName, createByModuleAccessName, listAll }
 }
+
+// Classic module exports, bound to the env-configured default endpoint.
+// Note: changeByModuleAccessName used to swallow SOAP errors via console.error;
+// it now rejects like every other operation (see CHANGELOG, Unreleased).
+let defaultService
+const service = () => (defaultService ??= createResellerUserService(createClientAsync))
+
+export const remove = (...args) => service().remove(...args)
+export const change = (...args) => service().change(...args)
+export const get = (...args) => service().get(...args)
+export const getModuleAccess = (...args) => service().getModuleAccess(...args)
+export const changeByModuleAccess = (...args) => service().changeByModuleAccess(...args)
+export const changeByModuleAccessName = (...args) => service().changeByModuleAccessName(...args)
+export const createByModuleAccessName = (...args) => service().createByModuleAccessName(...args)
+export const listAll = (...args) => service().listAll(...args)