@linagora/ldap-rest-client 1.0.2 → 1.0.3

package/README.md

@@ -66,6 +66,11 @@ client.organizations.createAdmin(orgId, { username, mail })
 client.organizations.list()
 client.organizations.get(orgId)
 client.organizations.update(orgId, updates)
+
+// Organization ownership management
+client.organizations.getOwner(orgId)
+client.organizations.setOwner(orgId, { username, mail })
+client.organizations.transferOwnership(orgId, { newOwnerUsername })
 ```
 
 ### B2B Users (within Organizations)
@@ -75,8 +80,10 @@ client.organizations.updateUser(orgId, userId, updates)
 client.organizations.disableUser(orgId, userId)
 client.organizations.deleteUser(orgId, userId)
 client.organizations.getUser(orgId, { by, value })
-client.organizations.listUsers(orgId, { page, limit, status, search })
+client.organizations.listUsers(orgId, { page, limit, status, search, sortBy, sortOrder })
 client.organizations.checkUserAvailability(orgId, { field, value })
+
+// User role management ('owner', 'admin', 'moderator', 'member')
 client.organizations.changeUserRole(orgId, userId, { role })
 ```
 
@@ -91,6 +98,45 @@ client.groups.addMembers(orgId, groupId, { usernames })
 client.groups.removeMember(orgId, groupId, userId)
 ```
 
+## Configuration
+
+### Client Options
+
+```typescript
+const client = new LdapRestClient({
+  baseUrl: 'https://ldap-rest.example.com',
+  auth: {
+    type: 'hmac',
+    serviceId: 'my-service',
+    secret: 'your-secret-key-at-least-32-chars-long',
+  },
+  timeout: 30000, // Request timeout in milliseconds (default: 30000)
+  logger: {
+    // Optional tslog configuration for custom logging
+    minLevel: 'info',
+  },
+});
+```
+
+### Authentication Types
+
+**HMAC (Backend Services)**
+```typescript
+auth: {
+  type: 'hmac',
+  serviceId: 'registration-service',
+  secret: 'your-secret-key', // Minimum 32 characters recommended
+}
+```
+
+**Cookie (Browser/SSO)**
+```typescript
+auth: {
+  type: 'cookie', // Uses cookies set by authentication service
+}
+// Or omit auth entirely (defaults to cookie)
+```
+
 ## Error Handling
 
 ```typescript

package/dist/index.d.mts

@@ -2,16 +2,22 @@ import { ISettingsParam, Logger } from 'tslog';
 
 /**
  * HMAC authentication configuration for backend services
+ * Uses HMAC-SHA256 signatures as per ADR-024
  */
 interface HmacAuthConfig {
+    /** Authentication type */
     type: 'hmac';
+    /** Service identifier (e.g., 'registration-service') */
     serviceId: string;
+    /** Shared secret key (minimum 32 characters recommended) */
     secret: string;
 }
 /**
  * SSO Cookie authentication configuration for browser requests
+ * Relies on cookies set by the authentication service
  */
 interface CookieAuthConfig {
+    /** Authentication type */
     type: 'cookie';
 }
 /**
@@ -22,16 +28,23 @@ type AuthConfig = HmacAuthConfig | CookieAuthConfig;
  * Configuration for LDAP-REST client
  */
 interface ClientConfig {
+    /** Base URL of the LDAP-REST API (e.g., 'https://ldap-rest.example.com') */
     baseUrl: string;
+    /** Authentication configuration (defaults to cookie auth if not provided) */
     auth?: AuthConfig;
+    /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
+    /** tslog logger configuration for custom logging */
     logger?: ISettingsParam<unknown>;
 }
 /**
  * HTTP client configuration
+ * Subset of configuration passed to the HTTP client
  */
 interface HttpConfig {
+    /** Base URL of the API */
     baseUrl: string;
+    /** Request timeout in milliseconds */
     timeout: number;
 }
 
@@ -209,112 +222,236 @@ declare abstract class BaseResource {
     protected buildQueryString: (params: Record<string, string | number | boolean | undefined>) => string;
 }
 
+/**
+ * Email address with optional type and label
+ */
 interface EmailAddress {
+    /** Email address */
     address: string;
+    /** Type of email (e.g., 'work', 'personal') */
     type?: string;
+    /** Custom label for the email */
     label?: string;
+    /** Whether this is the primary email */
     primary?: string;
 }
+/**
+ * Instant messaging contact information
+ */
 interface InstantMessaging {
+    /** IM protocol URI (e.g., 'xmpp:user@example.com', 'skype:username') */
     uri: string;
+    /** Protocol name (e.g., 'xmpp', 'skype', 'slack') */
     protocol?: string;
+    /** Custom label for the IM account */
     label?: string;
+    /** Whether this is the primary IM contact */
     primary?: string;
 }
+/**
+ * Phone number with optional type and label
+ */
 interface PhoneNumber {
+    /** Phone number (preferably in international format, e.g., '+33612345678') */
     number: string;
+    /** Type of phone (e.g., 'mobile', 'home', 'work', 'fax') */
     type?: string;
+    /** Custom label for the phone number */
     label?: string;
+    /** Whether this is the primary phone number */
     primary?: boolean;
 }
+/**
+ * Extended address details for buildings and apartments
+ */
 interface ExtendedAddress {
+    /** Locality or neighborhood name */
     locality?: string;
+    /** Building name or number */
     building?: string;
+    /** Staircase identifier */
     stairs?: string;
+    /** Floor number */
     floor?: string;
+    /** Apartment number */
     apartment?: string;
+    /** Entry code or access code */
     entrycode?: string;
 }
+/**
+ * Geographic location with coordinates
+ */
 interface GeoLocation {
+    /** Geographic coordinates as [latitude, longitude] */
     geo?: [number, number];
+    /** Category for Cozy Cloud integration */
     cozyCategory?: string;
 }
+/**
+ * Physical address with comprehensive location details
+ */
 interface Address {
+    /** Unique identifier for the address */
     id?: string;
+    /** Street name */
     street?: string;
+    /** Post office box number */
     pobox?: string;
+    /** City name */
     city?: string;
+    /** State, province, or region */
     region?: string;
+    /** Street number */
     number?: string;
+    /** Postal or ZIP code */
     code?: string;
+    /** Country name or code */
     country?: string;
+    /** Type of address (e.g., 'home', 'work', 'billing') */
     type?: string;
+    /** Custom label for the address */
     label?: string;
+    /** Whether this is the primary address */
     primary?: boolean;
+    /** Extended address details (building, floor, apartment, etc.) */
     extendedAddress?: ExtendedAddress;
+    /** Single-line formatted address string */
     formattedAddress?: string;
+    /** Geographic location with coordinates */
     geo?: GeoLocation;
 }
+/**
+ * Structured name components for a user
+ */
 interface UserName {
+    /** Family name or last name */
     familyName?: string;
+    /** Given name or first name */
     givenName?: string;
+    /** Middle name or additional names */
     additionalName?: string;
+    /** Name prefix (e.g., 'Dr.', 'Mr.', 'Ms.') */
     namePrefix?: string;
+    /** Name suffix (e.g., 'Jr.', 'Sr.', 'III') */
     nameSuffix?: string;
+    /** Surname (alternative to familyName) */
     surname?: string;
 }
+/**
+ * Complete user model with all profile fields, credentials, and encryption keys
+ */
 interface User {
+    /** Common name (username) */
     cn: string;
+    /** Surname or last name */
     sn: string;
+    /** Given name or first name */
     givenName: string;
+    /** Display name shown in UI */
     displayName: string;
+    /** Primary email address */
     mail: string;
+    /** Primary mobile phone number */
     mobile: string;
+    /** Encrypted user password */
     userPassword: string;
+    /** Scrypt parameter: block size */
     scryptR: number;
+    /** Scrypt parameter: CPU/memory cost */
     scryptN: number;
+    /** Scrypt parameter: parallelization */
     scryptP: number;
+    /** Salt for password encryption */
     scryptSalt: string;
+    /** Derived key length for scrypt */
     scryptDKLength: number;
+    /** Number of iterations for key derivation */
     iterations: number;
+    /** User's domain */
     domain: string;
+    /** User's public encryption key */
     publicKey: string;
+    /** User's private encryption key */
     privateKey: string;
+    /** Protected encryption key */
     protectedKey: string;
+    /** Whether two-factor authentication is enabled */
     twoFactorEnabled?: string;
+    /** URL of user's workspace */
     workspaceUrl?: string;
+    /** Recovery email for account recovery */
     recoveryEmail?: string;
+    /** Timestamp when password account was locked */
     pwdAccountLockedTime?: string;
+    /** User's role in Twake organization ('owner', 'admin', 'moderator', 'member') */
     twakeOrganizationRole?: string;
+    /** Full name as a single string */
     fullname?: string;
+    /** Structured name components */
     name?: UserName;
+    /** Birthday in ISO 8601 format (YYYY-MM-DD) */
     birthday?: string;
+    /** Gender */
     gender?: string;
+    /** Personal note or description */
     note?: string;
+    /** Array of email addresses */
     email?: EmailAddress[];
+    /** Array of instant messaging contacts */
     impp?: InstantMessaging[];
+    /** Place of birth */
     birthplace?: string;
+    /** Job title or position */
     jobTitle?: string;
+    /** Company or organization name */
     company?: string;
+    /** Array of phone numbers */
     phone?: PhoneNumber[];
+    /** Array of physical addresses */
     address?: Address[];
 }
+/**
+ * User password credentials with scrypt encryption parameters
+ */
 interface UserCredentials {
+    /** Encrypted password */
     userPassword: string;
+    /** Scrypt CPU/memory cost parameter (power of 2, e.g., 16384) */
     scryptN: number;
+    /** Scrypt parallelization parameter (typically 1) */
     scryptP: number;
+    /** Scrypt block size parameter (typically 8) */
     scryptR: number;
+    /** Random salt for password hashing */
     scryptSalt: string;
+    /** Derived key length in bytes (typically 32) */
     scryptDKLength: number;
+    /** Number of PBKDF2 iterations */
     iterations: number;
 }
+/**
+ * User's cryptographic keys for end-to-end encryption
+ */
 interface UserKeys {
+    /** User's private encryption key */
     privateKey: string;
+    /** User's public encryption key */
     publicKey: string;
+    /** Password-protected version of the private key */
     protectedKey: string;
 }
+/**
+ * User account status
+ */
 type UserStatus = 'active' | 'disabled';
+/**
+ * Fields that can be used to search for users
+ */
 type UserSearchField = 'username' | 'phone' | 'email' | 'recoveryEmail';
+/**
+ * Request payload for creating a new B2C user
+ * Includes all required fields plus optional profile information
+ */
 interface CreateUserRequest extends UserCredentials, UserKeys {
     cn: string;
     uid: string;
@@ -342,6 +479,10 @@ interface CreateUserRequest extends UserCredentials, UserKeys {
     phone?: PhoneNumber[];
     address?: Address[];
 }
+/**
+ * Request payload for updating a user's profile
+ * All fields are optional and only provided fields will be updated
+ */
 interface UpdateUserRequest {
     mobile?: string;
     userPassword?: string;

package/dist/index.d.ts

@@ -2,16 +2,22 @@ import { ISettingsParam, Logger } from 'tslog';
 
 /**
  * HMAC authentication configuration for backend services
+ * Uses HMAC-SHA256 signatures as per ADR-024
  */
 interface HmacAuthConfig {
+    /** Authentication type */
     type: 'hmac';
+    /** Service identifier (e.g., 'registration-service') */
     serviceId: string;
+    /** Shared secret key (minimum 32 characters recommended) */
     secret: string;
 }
 /**
  * SSO Cookie authentication configuration for browser requests
+ * Relies on cookies set by the authentication service
  */
 interface CookieAuthConfig {
+    /** Authentication type */
     type: 'cookie';
 }
 /**
@@ -22,16 +28,23 @@ type AuthConfig = HmacAuthConfig | CookieAuthConfig;
  * Configuration for LDAP-REST client
  */
 interface ClientConfig {
+    /** Base URL of the LDAP-REST API (e.g., 'https://ldap-rest.example.com') */
     baseUrl: string;
+    /** Authentication configuration (defaults to cookie auth if not provided) */
     auth?: AuthConfig;
+    /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
+    /** tslog logger configuration for custom logging */
     logger?: ISettingsParam<unknown>;
 }
 /**
  * HTTP client configuration
+ * Subset of configuration passed to the HTTP client
  */
 interface HttpConfig {
+    /** Base URL of the API */
     baseUrl: string;
+    /** Request timeout in milliseconds */
     timeout: number;
 }
 
@@ -209,112 +222,236 @@ declare abstract class BaseResource {
     protected buildQueryString: (params: Record<string, string | number | boolean | undefined>) => string;
 }
 
+/**
+ * Email address with optional type and label
+ */
 interface EmailAddress {
+    /** Email address */
     address: string;
+    /** Type of email (e.g., 'work', 'personal') */
     type?: string;
+    /** Custom label for the email */
     label?: string;
+    /** Whether this is the primary email */
     primary?: string;
 }
+/**
+ * Instant messaging contact information
+ */
 interface InstantMessaging {
+    /** IM protocol URI (e.g., 'xmpp:user@example.com', 'skype:username') */
     uri: string;
+    /** Protocol name (e.g., 'xmpp', 'skype', 'slack') */
     protocol?: string;
+    /** Custom label for the IM account */
     label?: string;
+    /** Whether this is the primary IM contact */
     primary?: string;
 }
+/**
+ * Phone number with optional type and label
+ */
 interface PhoneNumber {
+    /** Phone number (preferably in international format, e.g., '+33612345678') */
     number: string;
+    /** Type of phone (e.g., 'mobile', 'home', 'work', 'fax') */
     type?: string;
+    /** Custom label for the phone number */
     label?: string;
+    /** Whether this is the primary phone number */
     primary?: boolean;
 }
+/**
+ * Extended address details for buildings and apartments
+ */
 interface ExtendedAddress {
+    /** Locality or neighborhood name */
     locality?: string;
+    /** Building name or number */
     building?: string;
+    /** Staircase identifier */
     stairs?: string;
+    /** Floor number */
     floor?: string;
+    /** Apartment number */
     apartment?: string;
+    /** Entry code or access code */
     entrycode?: string;
 }
+/**
+ * Geographic location with coordinates
+ */
 interface GeoLocation {
+    /** Geographic coordinates as [latitude, longitude] */
     geo?: [number, number];
+    /** Category for Cozy Cloud integration */
     cozyCategory?: string;
 }
+/**
+ * Physical address with comprehensive location details
+ */
 interface Address {
+    /** Unique identifier for the address */
     id?: string;
+    /** Street name */
     street?: string;
+    /** Post office box number */
     pobox?: string;
+    /** City name */
     city?: string;
+    /** State, province, or region */
     region?: string;
+    /** Street number */
     number?: string;
+    /** Postal or ZIP code */
     code?: string;
+    /** Country name or code */
     country?: string;
+    /** Type of address (e.g., 'home', 'work', 'billing') */
     type?: string;
+    /** Custom label for the address */
     label?: string;
+    /** Whether this is the primary address */
     primary?: boolean;
+    /** Extended address details (building, floor, apartment, etc.) */
     extendedAddress?: ExtendedAddress;
+    /** Single-line formatted address string */
     formattedAddress?: string;
+    /** Geographic location with coordinates */
     geo?: GeoLocation;
 }
+/**
+ * Structured name components for a user
+ */
 interface UserName {
+    /** Family name or last name */
     familyName?: string;
+    /** Given name or first name */
     givenName?: string;
+    /** Middle name or additional names */
     additionalName?: string;
+    /** Name prefix (e.g., 'Dr.', 'Mr.', 'Ms.') */
     namePrefix?: string;
+    /** Name suffix (e.g., 'Jr.', 'Sr.', 'III') */
     nameSuffix?: string;
+    /** Surname (alternative to familyName) */
     surname?: string;
 }
+/**
+ * Complete user model with all profile fields, credentials, and encryption keys
+ */
 interface User {
+    /** Common name (username) */
     cn: string;
+    /** Surname or last name */
     sn: string;
+    /** Given name or first name */
     givenName: string;
+    /** Display name shown in UI */
     displayName: string;
+    /** Primary email address */
     mail: string;
+    /** Primary mobile phone number */
     mobile: string;
+    /** Encrypted user password */
     userPassword: string;
+    /** Scrypt parameter: block size */
     scryptR: number;
+    /** Scrypt parameter: CPU/memory cost */
     scryptN: number;
+    /** Scrypt parameter: parallelization */
     scryptP: number;
+    /** Salt for password encryption */
     scryptSalt: string;
+    /** Derived key length for scrypt */
     scryptDKLength: number;
+    /** Number of iterations for key derivation */
     iterations: number;
+    /** User's domain */
     domain: string;
+    /** User's public encryption key */
     publicKey: string;
+    /** User's private encryption key */
     privateKey: string;
+    /** Protected encryption key */
     protectedKey: string;
+    /** Whether two-factor authentication is enabled */
     twoFactorEnabled?: string;
+    /** URL of user's workspace */
     workspaceUrl?: string;
+    /** Recovery email for account recovery */
     recoveryEmail?: string;
+    /** Timestamp when password account was locked */
     pwdAccountLockedTime?: string;
+    /** User's role in Twake organization ('owner', 'admin', 'moderator', 'member') */
     twakeOrganizationRole?: string;
+    /** Full name as a single string */
     fullname?: string;
+    /** Structured name components */
     name?: UserName;
+    /** Birthday in ISO 8601 format (YYYY-MM-DD) */
     birthday?: string;
+    /** Gender */
     gender?: string;
+    /** Personal note or description */
     note?: string;
+    /** Array of email addresses */
     email?: EmailAddress[];
+    /** Array of instant messaging contacts */
     impp?: InstantMessaging[];
+    /** Place of birth */
     birthplace?: string;
+    /** Job title or position */
     jobTitle?: string;
+    /** Company or organization name */
     company?: string;
+    /** Array of phone numbers */
     phone?: PhoneNumber[];
+    /** Array of physical addresses */
     address?: Address[];
 }
+/**
+ * User password credentials with scrypt encryption parameters
+ */
 interface UserCredentials {
+    /** Encrypted password */
     userPassword: string;
+    /** Scrypt CPU/memory cost parameter (power of 2, e.g., 16384) */
     scryptN: number;
+    /** Scrypt parallelization parameter (typically 1) */
     scryptP: number;
+    /** Scrypt block size parameter (typically 8) */
     scryptR: number;
+    /** Random salt for password hashing */
     scryptSalt: string;
+    /** Derived key length in bytes (typically 32) */
     scryptDKLength: number;
+    /** Number of PBKDF2 iterations */
     iterations: number;
 }
+/**
+ * User's cryptographic keys for end-to-end encryption
+ */
 interface UserKeys {
+    /** User's private encryption key */
     privateKey: string;
+    /** User's public encryption key */
     publicKey: string;
+    /** Password-protected version of the private key */
     protectedKey: string;
 }
+/**
+ * User account status
+ */
 type UserStatus = 'active' | 'disabled';
+/**
+ * Fields that can be used to search for users
+ */
 type UserSearchField = 'username' | 'phone' | 'email' | 'recoveryEmail';
+/**
+ * Request payload for creating a new B2C user
+ * Includes all required fields plus optional profile information
+ */
 interface CreateUserRequest extends UserCredentials, UserKeys {
     cn: string;
     uid: string;
@@ -342,6 +479,10 @@ interface CreateUserRequest extends UserCredentials, UserKeys {
     phone?: PhoneNumber[];
     address?: Address[];
 }
+/**
+ * Request payload for updating a user's profile
+ * All fields are optional and only provided fields will be updated
+ */
 interface UpdateUserRequest {
     mobile?: string;
     userPassword?: string;

package/dist/index.js

@@ -38,6 +38,11 @@ module.exports = __toCommonJS(index_exports);
 
 // src/config/ClientConfig.ts
 var ConfigValidator = class {
+  /**
+   * Validates the client configuration
+   * @param {ClientConfig} config - Configuration to validate
+   * @throws {Error} If configuration is invalid
+   */
   static validate(config) {
     if (!config.baseUrl || config.baseUrl.trim().length === 0) {
       throw new Error("baseUrl is required");
@@ -64,6 +69,11 @@ var ConfigValidator = class {
       throw new Error("timeout must be a positive number");
     }
   }
+  /**
+   * Normalizes the client configuration by applying defaults
+   * @param {ClientConfig} config - Configuration to normalize
+   * @returns {NormalizedClientConfig} Normalized configuration with defaults applied
+   */
   static normalize(config) {
     return {
       baseUrl: config.baseUrl.replace(/\/$/, ""),
@@ -72,6 +82,11 @@ var ConfigValidator = class {
       logger: config.logger
     };
   }
+  /**
+   * Extracts HTTP-specific configuration from normalized config
+   * @param {NormalizedClientConfig} config - Normalized configuration
+   * @returns {HttpConfig} HTTP client configuration
+   */
   static toHttpConfig(config) {
     return {
       baseUrl: config.baseUrl,

package/dist/index.mjs

@@ -1,5 +1,10 @@
 // src/config/ClientConfig.ts
 var ConfigValidator = class {
+  /**
+   * Validates the client configuration
+   * @param {ClientConfig} config - Configuration to validate
+   * @throws {Error} If configuration is invalid
+   */
   static validate(config) {
     if (!config.baseUrl || config.baseUrl.trim().length === 0) {
       throw new Error("baseUrl is required");
@@ -26,6 +31,11 @@ var ConfigValidator = class {
       throw new Error("timeout must be a positive number");
     }
   }
+  /**
+   * Normalizes the client configuration by applying defaults
+   * @param {ClientConfig} config - Configuration to normalize
+   * @returns {NormalizedClientConfig} Normalized configuration with defaults applied
+   */
   static normalize(config) {
     return {
       baseUrl: config.baseUrl.replace(/\/$/, ""),
@@ -34,6 +44,11 @@ var ConfigValidator = class {
       logger: config.logger
     };
   }
+  /**
+   * Extracts HTTP-specific configuration from normalized config
+   * @param {NormalizedClientConfig} config - Normalized configuration
+   * @returns {HttpConfig} HTTP client configuration
+   */
   static toHttpConfig(config) {
     return {
       baseUrl: config.baseUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linagora/ldap-rest-client",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "TypeScript API client for LDAP-REST",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",