@linagora/ldap-rest-client 1.0.10 → 1.0.12

package/README.md

@@ -1,6 +1,14 @@
 # ldap-rest-client
 
-TypeScript client for LDAP-REST API with HMAC-SHA256 and SSO cookie authentication.
+TypeScript client library for LDAP-REST API with dual authentication support (HMAC-SHA256 for backend services, SSO cookies for browsers).
+
+## Features
+
+- **Dual Authentication**: HMAC-SHA256 for backend services, SSO cookies for browsers
+- **Type-Safe**: Full TypeScript support with comprehensive type definitions
+- **Resource-Based API**: Clean, intuitive interface for users, organizations, and groups
+- **Error Handling**: Semantic error types mapped to HTTP status codes
+- **Cross-Platform**: Works in Node.js (18+) and browser environments
 
 ## Installation
 
@@ -24,11 +32,31 @@ const client = new LdapRestClient({
   },
 });
 
-// Create user
-await client.users.create(userData);
+// Create B2C user
+await client.users.create({
+  username: 'johndoe',
+  mail: 'john@example.com',
+  givenName: 'John',
+  cn: 'John Doe',
+  sn: 'Doe',
+  userPassword: 'secure-password',
+});
 
 // Create organization
-await client.organizations.create({ id, name, domain });
+await client.organizations.create({
+  id: 'acme-corp',
+  name: 'Acme Corporation',
+  domain: 'acme.com',
+});
+
+// Create B2B user in organization
+const user = await client.organizations.createUser('acme-corp', {
+  username: 'employee',
+  mail: 'employee@acme.com',
+  givenName: 'Jane',
+  cn: 'Jane Smith',
+  sn: 'Smith',
+});
 ```
 
 ### Browser (SSO Cookie)
@@ -36,159 +64,116 @@ await client.organizations.create({ id, name, domain });
 ```typescript
 const client = new LdapRestClient({
   baseUrl: 'https://ldap-rest.example.com',
+  // auth defaults to browser cookie-based authentication
 });
 
-// Manage users in organization (returns User object)
-const user = await client.organizations.createUser(orgId, userData);
-console.log(user._id); // Access unique identifier
-console.log(user.organizationId); // Access organization ID
-
-await client.organizations.listUsers(orgId, { page: 1, limit: 20 });
+// List users in organization
+const result = await client.organizations.listUsers('acme-corp', {
+  page: 1,
+  limit: 20,
+});
 
-// Manage groups (returns Group object)
-const group = await client.groups.create(orgId, { name: 'engineering' });
-await client.groups.addMembers(orgId, groupId, { usernames: ['user1'] });
+// Create and manage groups
+const group = await client.groups.create('acme-corp', {
+  name: 'engineering',
+  description: 'Engineering team',
+});
 
-// Get user's organizations
-const orgs = await client.users.getUserOrganizations(userId, 'admin');
+await client.groups.addMembers('acme-corp', group._id, {
+  usernames: ['user1', 'user2'],
+});
 ```
 
-## API Reference
+## API Overview
 
-### Users (B2C)
-```typescript
-client.users.create(userData)
-client.users.update(username, updates)
-client.users.disable(username)
-client.users.delete(username)
-client.users.checkAvailability({ field, value })
-client.users.fetch({ by, value, fields })
-client.users.getUserOrganizations(userId, role?) // Get user's organizations by role
-
-// Technical/service accounts
-client.users.create({ ...userData, isTechnical: true }) // Create technical account
-client.users.update(username, { isTechnical: true }) // Mark user as technical
-```
+The client provides three main resource interfaces:
 
-### Organizations
-```typescript
-client.organizations.create({ id, name, domain })
-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 })
-```
+- **`client.users`** - B2C user management (top-level users)
+- **`client.organizations`** - Organization and B2B user management
+- **`client.groups`** - Group management within organizations
 
-### B2B Users (within Organizations)
-```typescript
-// Returns full User object with _id and organizationId
-const user = await client.organizations.createUser(orgId, userData)
-console.log(user._id, user.organizationId)
-
-// Returns updated User object or { success: true }
-const updatedUser = await 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, sortBy, sortOrder, isTechnical })
-client.organizations.checkUserAvailability(orgId, { field, value })
-
-// User role management ('owner', 'admin', 'moderator', 'member')
-// Returns { role, previousRole }
-const result = await client.organizations.changeUserRole(orgId, userId, { role })
-console.log(`Changed from ${result.previousRole} to ${result.role}`)
-
-// Technical/service accounts in organizations
-const techUser = await client.organizations.createUser(orgId, { ...userData, isTechnical: true })
-await client.organizations.updateUser(orgId, userId, { isTechnical: true })
-// List only technical users
-await client.organizations.listUsers(orgId, { isTechnical: true })
-```
+For complete API documentation, see **[API.md](./API.md)**.
 
-### Groups
-```typescript
-// Returns Group object directly
-const group = await client.groups.create(orgId, { name, description })
-
-client.groups.list(orgId, { page, limit })
-client.groups.get(orgId, groupId)
-client.groups.update(orgId, groupId, updates)
-client.groups.delete(orgId, groupId)
-client.groups.addMembers(orgId, groupId, { usernames })
-client.groups.removeMember(orgId, groupId, userId)
-```
+### Key Concepts
 
-## Configuration
+**Authentication:**
+- **HMAC-SHA256**: For server-to-server communication
+- **Cookie/SSO**: For browser-based applications
 
-### Client Options
+## Configuration
 
 ```typescript
 const client = new LdapRestClient({
-  baseUrl: 'https://ldap-rest.example.com',
+  baseUrl: 'https://ldap-rest.example.com', // Required
   auth: {
-    type: 'hmac',
+    type: 'hmac', // or 'cookie'
     serviceId: 'my-service',
     secret: 'your-secret-key-at-least-32-chars-long',
   },
-  timeout: 30000, // Request timeout in milliseconds (default: 30000)
+  timeout: 30000, // Optional, default: 30000ms
   logger: {
-    // Optional tslog configuration for custom logging
-    minLevel: 'info',
+    minLevel: 'info', // Optional, tslog configuration
   },
 });
 ```
 
-### 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)
-```
+See **[API.md - Configuration](./API.md#configuration)** for detailed options.
 
 ## Error Handling
 
+All errors extend `LdapRestError` and map to specific HTTP status codes:
+
 ```typescript
-import { ConflictError, NotFoundError } from '@linagora/ldap-rest-client';
+import {
+  ValidationError,
+  NotFoundError,
+  ConflictError,
+} from '@linagora/ldap-rest-client';
 
 try {
   await client.users.create(userData);
 } catch (error) {
   if (error instanceof ConflictError) {
-    // Handle conflict (409)
-  } else if (error instanceof NotFoundError) {
-    // Handle not found (404)
+    console.error('User already exists');
+  } else if (error instanceof ValidationError) {
+    console.error('Invalid data:', error.message);
   }
 }
 ```
 
-Available errors: `ValidationError`, `AuthenticationError`, `AuthorizationError`, `NotFoundError`, `ConflictError`, `RateLimitError`, `NetworkError`, `ApiError`
+**Available error types:** `ValidationError` (400), `AuthenticationError` (401), `AuthorizationError` (403), `NotFoundError` (404), `ConflictError` (409), `RateLimitError` (429), `NetworkError`, `ApiError`.
+
+See **[API.md - Error Handling](./API.md#error-handling)** for complete documentation.
+
+## Documentation
+
+- **[API Reference](./API.md)** - Complete API documentation
 
 ## Development
 
 ```bash
+# Install dependencies
 npm install
+
+# Run tests
 npm test
+
+# Build library
 npm run build
+
+# Type checking
+npm run typecheck
+
+# Linting and formatting
+npm run lint
+npm run format
 ```
 
+## Requirements
+
+- Node.js 18+
+- TypeScript 5+
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -415,6 +415,8 @@ interface User {
     address?: Address[];
     /** Whether this is a technical/service account */
     isTechnical?: boolean;
+    /** Whether this B2B user is pending invitation (only for B2B users) */
+    invited?: boolean;
 }
 /**
  * User password credentials with scrypt encryption parameters
@@ -485,6 +487,7 @@ interface CreateUserRequest extends UserCredentials, UserKeys {
     phone?: PhoneNumber[];
     address?: Address[];
     isTechnical?: boolean;
+    invited?: boolean;
 }
 /**
  * Request payload for updating a user's profile
@@ -512,6 +515,7 @@ interface UpdateUserRequest {
     phone?: PhoneNumber[];
     address?: Address[];
     isTechnical?: boolean;
+    invited?: boolean;
     [key: string]: string | number | boolean | null | undefined | UserName | EmailAddress[] | InstantMessaging[] | PhoneNumber[] | Address[];
 }
 /**
@@ -576,6 +580,18 @@ interface ListUsersResponse {
  * Returns the full user object with all fields populated
  */
 type CreateB2BUserResponse = User;
+/**
+ * Parameters for searching users across all branches
+ */
+interface SearchUsersParams {
+    /** Search field (username, email, phone, recoveryEmail) */
+    by: UserSearchField | 'recoveryEmail';
+    /** Search value */
+    value: string;
+    /** Optional comma-separated list of fields to return */
+    fields?: string;
+    [key: string]: string | undefined;
+}
 
 /**
  * Organization domain model representing a B2B organization
@@ -606,11 +622,16 @@ interface Organization {
  * - suspended: Organization is temporarily disabled
  */
 type OrganizationStatus = 'active' | 'suspended';
+/**
+ * Supported primitive types for metadata values
+ */
+type MetadataValue = string | number | boolean | null;
 /**
  * Optional metadata for organization customization
  *
  * Allows storing custom properties like industry, company size,
  * contact information, or any other organization-specific data.
+ * Supports strings, numbers, booleans, and null values.
  */
 interface OrganizationMetadata {
     /** Industry/sector (e.g., 'Technology', 'Healthcare') */
@@ -620,7 +641,7 @@ interface OrganizationMetadata {
     /** Primary contact information */
     contact?: string;
     /** Additional custom fields as key-value pairs */
-    [key: string]: string | undefined;
+    [key: string]: MetadataValue | undefined;
 }
 /**
  * Request parameters for creating an organization
@@ -905,6 +926,34 @@ declare class UsersResource extends BaseResource {
      * ```
      */
     fetch: (params: FetchUserRequest) => Promise<User>;
+    /**
+     * Search users across all branches (B2C and B2B)
+     *
+     * Returns array of all users matching the search criteria from both
+     * B2C and B2B branches. Email searches return immediately if found
+     * in B2C since email is unique.
+     *
+     * @param {SearchUsersParams} params - Search parameters (by, value, fields)
+     * @returns {Promise<User[]>} Array of matching users
+     * @throws {ApiError} On API errors
+     *
+     * @example
+     * ```typescript
+     * // Search by username across all branches
+     * const users = await client.users.search({
+     *   by: 'username',
+     *   value: 'johndoe'
+     * });
+     *
+     * // Search by email with field filtering
+     * const users = await client.users.search({
+     *   by: 'email',
+     *   value: 'john@example.com',
+     *   fields: 'cn,mail,organizationId'
+     * });
+     * ```
+     */
+    search: (params: SearchUsersParams) => Promise<User[]>;
     /**
      * Gets organizations where a user has a role
      *
@@ -1721,4 +1770,4 @@ declare class NetworkError extends LdapRestError {
     constructor(message: string, cause?: Error);
 }
 
-export { type AddGroupMembersRequest, type Address, ApiError, AuthenticationError, AuthorizationError, type ChangeUserRoleRequest, type ChangeUserRoleResponse, type CheckAvailabilityParams, type CheckAvailabilityResponse, type CheckOrganizationAvailabilityParams, type ClientConfig, ConflictError, type CreateAdminRequest, type CreateB2BUserResponse, type CreateGroupRequest, type CreateOrganizationRequest, type CreateOrganizationResponse, type CreateUserRequest, type EmailAddress, type ExtendedAddress, type FetchUserRequest, type GeoLocation, type GetOwnerResponse, type Group, GroupsResource, type InstantMessaging, LdapRestClient, LdapRestError, type ListGroupsParams, type ListGroupsResponse, type ListUsersParams, type ListUsersResponse, NetworkError, NotFoundError, type Organization, type OrganizationMetadata, type OrganizationOwner, type OrganizationRole, type OrganizationSearchField, type OrganizationStatus, OrganizationsResource, type PhoneNumber, RateLimitError, type SetOwnerRequest, type TransferOwnershipRequest, type UpdateGroupRequest, type UpdateOrganizationRequest, type UpdateUserRequest, type User, type UserCredentials, type UserKeys, type UserName, type UserSearchField, type UserStatus, UsersResource, ValidationError };
+export { type AddGroupMembersRequest, type Address, ApiError, AuthenticationError, AuthorizationError, type ChangeUserRoleRequest, type ChangeUserRoleResponse, type CheckAvailabilityParams, type CheckAvailabilityResponse, type CheckOrganizationAvailabilityParams, type ClientConfig, ConflictError, type CreateAdminRequest, type CreateB2BUserResponse, type CreateGroupRequest, type CreateOrganizationRequest, type CreateOrganizationResponse, type CreateUserRequest, type EmailAddress, type ExtendedAddress, type FetchUserRequest, type GeoLocation, type GetOwnerResponse, type Group, GroupsResource, type InstantMessaging, LdapRestClient, LdapRestError, type ListGroupsParams, type ListGroupsResponse, type ListUsersParams, type ListUsersResponse, type MetadataValue, NetworkError, NotFoundError, type Organization, type OrganizationMetadata, type OrganizationOwner, type OrganizationRole, type OrganizationSearchField, type OrganizationStatus, OrganizationsResource, type PhoneNumber, RateLimitError, type SearchUsersParams, type SetOwnerRequest, type TransferOwnershipRequest, type UpdateGroupRequest, type UpdateOrganizationRequest, type UpdateUserRequest, type User, type UserCredentials, type UserKeys, type UserName, type UserSearchField, type UserStatus, UsersResource, ValidationError };

package/dist/index.d.ts

@@ -415,6 +415,8 @@ interface User {
     address?: Address[];
     /** Whether this is a technical/service account */
     isTechnical?: boolean;
+    /** Whether this B2B user is pending invitation (only for B2B users) */
+    invited?: boolean;
 }
 /**
  * User password credentials with scrypt encryption parameters
@@ -485,6 +487,7 @@ interface CreateUserRequest extends UserCredentials, UserKeys {
     phone?: PhoneNumber[];
     address?: Address[];
     isTechnical?: boolean;
+    invited?: boolean;
 }
 /**
  * Request payload for updating a user's profile
@@ -512,6 +515,7 @@ interface UpdateUserRequest {
     phone?: PhoneNumber[];
     address?: Address[];
     isTechnical?: boolean;
+    invited?: boolean;
     [key: string]: string | number | boolean | null | undefined | UserName | EmailAddress[] | InstantMessaging[] | PhoneNumber[] | Address[];
 }
 /**
@@ -576,6 +580,18 @@ interface ListUsersResponse {
  * Returns the full user object with all fields populated
  */
 type CreateB2BUserResponse = User;
+/**
+ * Parameters for searching users across all branches
+ */
+interface SearchUsersParams {
+    /** Search field (username, email, phone, recoveryEmail) */
+    by: UserSearchField | 'recoveryEmail';
+    /** Search value */
+    value: string;
+    /** Optional comma-separated list of fields to return */
+    fields?: string;
+    [key: string]: string | undefined;
+}
 
 /**
  * Organization domain model representing a B2B organization
@@ -606,11 +622,16 @@ interface Organization {
  * - suspended: Organization is temporarily disabled
  */
 type OrganizationStatus = 'active' | 'suspended';
+/**
+ * Supported primitive types for metadata values
+ */
+type MetadataValue = string | number | boolean | null;
 /**
  * Optional metadata for organization customization
  *
  * Allows storing custom properties like industry, company size,
  * contact information, or any other organization-specific data.
+ * Supports strings, numbers, booleans, and null values.
  */
 interface OrganizationMetadata {
     /** Industry/sector (e.g., 'Technology', 'Healthcare') */
@@ -620,7 +641,7 @@ interface OrganizationMetadata {
     /** Primary contact information */
     contact?: string;
     /** Additional custom fields as key-value pairs */
-    [key: string]: string | undefined;
+    [key: string]: MetadataValue | undefined;
 }
 /**
  * Request parameters for creating an organization
@@ -905,6 +926,34 @@ declare class UsersResource extends BaseResource {
      * ```
      */
     fetch: (params: FetchUserRequest) => Promise<User>;
+    /**
+     * Search users across all branches (B2C and B2B)
+     *
+     * Returns array of all users matching the search criteria from both
+     * B2C and B2B branches. Email searches return immediately if found
+     * in B2C since email is unique.
+     *
+     * @param {SearchUsersParams} params - Search parameters (by, value, fields)
+     * @returns {Promise<User[]>} Array of matching users
+     * @throws {ApiError} On API errors
+     *
+     * @example
+     * ```typescript
+     * // Search by username across all branches
+     * const users = await client.users.search({
+     *   by: 'username',
+     *   value: 'johndoe'
+     * });
+     *
+     * // Search by email with field filtering
+     * const users = await client.users.search({
+     *   by: 'email',
+     *   value: 'john@example.com',
+     *   fields: 'cn,mail,organizationId'
+     * });
+     * ```
+     */
+    search: (params: SearchUsersParams) => Promise<User[]>;
     /**
      * Gets organizations where a user has a role
      *
@@ -1721,4 +1770,4 @@ declare class NetworkError extends LdapRestError {
     constructor(message: string, cause?: Error);
 }
 
-export { type AddGroupMembersRequest, type Address, ApiError, AuthenticationError, AuthorizationError, type ChangeUserRoleRequest, type ChangeUserRoleResponse, type CheckAvailabilityParams, type CheckAvailabilityResponse, type CheckOrganizationAvailabilityParams, type ClientConfig, ConflictError, type CreateAdminRequest, type CreateB2BUserResponse, type CreateGroupRequest, type CreateOrganizationRequest, type CreateOrganizationResponse, type CreateUserRequest, type EmailAddress, type ExtendedAddress, type FetchUserRequest, type GeoLocation, type GetOwnerResponse, type Group, GroupsResource, type InstantMessaging, LdapRestClient, LdapRestError, type ListGroupsParams, type ListGroupsResponse, type ListUsersParams, type ListUsersResponse, NetworkError, NotFoundError, type Organization, type OrganizationMetadata, type OrganizationOwner, type OrganizationRole, type OrganizationSearchField, type OrganizationStatus, OrganizationsResource, type PhoneNumber, RateLimitError, type SetOwnerRequest, type TransferOwnershipRequest, type UpdateGroupRequest, type UpdateOrganizationRequest, type UpdateUserRequest, type User, type UserCredentials, type UserKeys, type UserName, type UserSearchField, type UserStatus, UsersResource, ValidationError };
+export { type AddGroupMembersRequest, type Address, ApiError, AuthenticationError, AuthorizationError, type ChangeUserRoleRequest, type ChangeUserRoleResponse, type CheckAvailabilityParams, type CheckAvailabilityResponse, type CheckOrganizationAvailabilityParams, type ClientConfig, ConflictError, type CreateAdminRequest, type CreateB2BUserResponse, type CreateGroupRequest, type CreateOrganizationRequest, type CreateOrganizationResponse, type CreateUserRequest, type EmailAddress, type ExtendedAddress, type FetchUserRequest, type GeoLocation, type GetOwnerResponse, type Group, GroupsResource, type InstantMessaging, LdapRestClient, LdapRestError, type ListGroupsParams, type ListGroupsResponse, type ListUsersParams, type ListUsersResponse, type MetadataValue, NetworkError, NotFoundError, type Organization, type OrganizationMetadata, type OrganizationOwner, type OrganizationRole, type OrganizationSearchField, type OrganizationStatus, OrganizationsResource, type PhoneNumber, RateLimitError, type SearchUsersParams, type SetOwnerRequest, type TransferOwnershipRequest, type UpdateGroupRequest, type UpdateOrganizationRequest, type UpdateUserRequest, type User, type UserCredentials, type UserKeys, type UserName, type UserSearchField, type UserStatus, UsersResource, ValidationError };

package/dist/index.js

@@ -632,6 +632,37 @@ var UsersResource = class extends BaseResource {
     const query = this.buildQueryString(params);
     return this.http.get(`/api/v1/users${query}`);
   };
+  /**
+   * Search users across all branches (B2C and B2B)
+   *
+   * Returns array of all users matching the search criteria from both
+   * B2C and B2B branches. Email searches return immediately if found
+   * in B2C since email is unique.
+   *
+   * @param {SearchUsersParams} params - Search parameters (by, value, fields)
+   * @returns {Promise<User[]>} Array of matching users
+   * @throws {ApiError} On API errors
+   *
+   * @example
+   * ```typescript
+   * // Search by username across all branches
+   * const users = await client.users.search({
+   *   by: 'username',
+   *   value: 'johndoe'
+   * });
+   *
+   * // Search by email with field filtering
+   * const users = await client.users.search({
+   *   by: 'email',
+   *   value: 'john@example.com',
+   *   fields: 'cn,mail,organizationId'
+   * });
+   * ```
+   */
+  search = async (params) => {
+    const query = this.buildQueryString(params);
+    return this.http.get(`/api/v1/users/search${query}`);
+  };
   /**
    * Gets organizations where a user has a role
    *

package/dist/index.mjs

@@ -594,6 +594,37 @@ var UsersResource = class extends BaseResource {
     const query = this.buildQueryString(params);
     return this.http.get(`/api/v1/users${query}`);
   };
+  /**
+   * Search users across all branches (B2C and B2B)
+   *
+   * Returns array of all users matching the search criteria from both
+   * B2C and B2B branches. Email searches return immediately if found
+   * in B2C since email is unique.
+   *
+   * @param {SearchUsersParams} params - Search parameters (by, value, fields)
+   * @returns {Promise<User[]>} Array of matching users
+   * @throws {ApiError} On API errors
+   *
+   * @example
+   * ```typescript
+   * // Search by username across all branches
+   * const users = await client.users.search({
+   *   by: 'username',
+   *   value: 'johndoe'
+   * });
+   *
+   * // Search by email with field filtering
+   * const users = await client.users.search({
+   *   by: 'email',
+   *   value: 'john@example.com',
+   *   fields: 'cn,mail,organizationId'
+   * });
+   * ```
+   */
+  search = async (params) => {
+    const query = this.buildQueryString(params);
+    return this.http.get(`/api/v1/users/search${query}`);
+  };
   /**
    * Gets organizations where a user has a role
    *

package/package.json

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