@linagora/ldap-rest-client 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,1399 @@
+import { ISettingsParam, Logger } from 'tslog';
+
+/**
+ * HMAC authentication configuration for backend services
+ */
+interface HmacAuthConfig {
+    type: 'hmac';
+    serviceId: string;
+    secret: string;
+}
+/**
+ * SSO Cookie authentication configuration for browser requests
+ */
+interface CookieAuthConfig {
+    type: 'cookie';
+}
+/**
+ * Authentication configuration union type
+ */
+type AuthConfig = HmacAuthConfig | CookieAuthConfig;
+/**
+ * Configuration for LDAP-REST client
+ */
+interface ClientConfig {
+    baseUrl: string;
+    auth?: AuthConfig;
+    timeout?: number;
+    logger?: ISettingsParam<unknown>;
+}
+/**
+ * HTTP client configuration
+ */
+interface HttpConfig {
+    baseUrl: string;
+    timeout: number;
+}
+
+/**
+ * Parameters for request signature generation
+ */
+interface SignatureParams {
+    /** HTTP method (GET, POST, PATCH, DELETE) */
+    method: string;
+    /** Request path with query string */
+    path: string;
+    /** Request body as string (for POST/PATCH) */
+    body?: string;
+}
+
+/**
+ * Base authentication interface
+ *
+ * All authentication implementations must provide a sign method
+ * that returns an authorization header value or empty string.
+ */
+interface Auth {
+    /**
+     * Generates authorization header for a request
+     *
+     * @param {SignatureParams} params - Request parameters to sign
+     * @returns {string} Authorization header value or empty string if no header needed
+     */
+    sign(params: SignatureParams): string;
+}
+
+/**
+ * HTTP request options
+ */
+interface RequestOptions {
+    /** HTTP method */
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    /** Request path (relative to base URL) */
+    path: string;
+    /** Request body (will be JSON stringified) */
+    body?: unknown;
+    /** Additional headers to include */
+    headers?: Record<string, string>;
+}
+/**
+ * HTTP client with authentication and error handling
+ *
+ * Handles all HTTP communication with the LDAP-REST API including:
+ * - Optional HMAC authentication or cookie-based SSO
+ * - Error mapping and handling
+ * - Request timeouts
+ *
+ * @example
+ * ```typescript
+ * const client = new HttpClient(config, auth);
+ * const response = await client.get('/api/v1/users');
+ * ```
+ */
+declare class HttpClient {
+    private readonly config;
+    private readonly auth;
+    private readonly logger;
+    /**
+     * Creates an HTTP client instance
+     *
+     * @param {HttpConfig} config - HTTP configuration (baseUrl, timeout)
+     * @param {Auth | undefined} auth - Optional authentication handler (HMAC). If undefined, uses cookies.
+     * @param {Logger<unknown>} logger - Logger instance
+     */
+    constructor(config: HttpConfig, auth: Auth | undefined, logger: Logger<unknown>);
+    /**
+     * Makes an authenticated HTTP request
+     *
+     * @template T - Response type
+     * @param {RequestOptions} options - Request options
+     * @returns {Promise<T>} Parsed response body
+     * @throws {ApiError} When API returns an error
+     * @throws {NetworkError} When network request fails
+     */
+    request: <T>(options: RequestOptions) => Promise<T>;
+    /**
+     * Handles HTTP response
+     *
+     * Maps HTTP status codes to specific error types and parses response body.
+     *
+     * @template T - Response type
+     * @param {Response} response - Fetch API response
+     * @returns {Promise<T>} Parsed response body
+     * @throws {ApiError} When API returns an error status
+     * @private
+     */
+    private handleResponse;
+    /**
+     * Performs a GET request
+     *
+     * @template T - Response type
+     * @param {string} path - Request path
+     * @param {Record<string, string>} [headers] - Additional headers
+     * @returns {Promise<T>} Parsed response body
+     */
+    get: <T>(path: string, headers?: Record<string, string>) => Promise<T>;
+    /**
+     * Performs a POST request
+     *
+     * @template T - Response type
+     * @param {string} path - Request path
+     * @param {unknown} [body] - Request body
+     * @param {Record<string, string>} [headers] - Additional headers
+     * @returns {Promise<T>} Parsed response body
+     */
+    post: <T>(path: string, body?: unknown, headers?: Record<string, string>) => Promise<T>;
+    /**
+     * Performs a PATCH request
+     *
+     * @template T - Response type
+     * @param {string} path - Request path
+     * @param {unknown} [body] - Request body
+     * @param {Record<string, string>} [headers] - Additional headers
+     * @returns {Promise<T>} Parsed response body
+     */
+    patch: <T>(path: string, body?: unknown, headers?: Record<string, string>) => Promise<T>;
+    /**
+     * Performs a DELETE request
+     *
+     * @template T - Response type
+     * @param {string} path - Request path
+     * @param {Record<string, string>} [headers] - Additional headers
+     * @returns {Promise<T>} Parsed response body
+     */
+    delete: <T>(path: string, headers?: Record<string, string>) => Promise<T>;
+}
+
+/**
+ * Base class for all API resources
+ *
+ * Provides common functionality for resource classes including
+ * HTTP client access and query string building.
+ */
+declare abstract class BaseResource {
+    protected readonly http: HttpClient;
+    /**
+     * Creates a base resource instance
+     *
+     * @param {HttpClient} http - HTTP client for making requests
+     * @protected
+     */
+    constructor(http: HttpClient);
+    /**
+     * Builds a query string from parameters
+     *
+     * Filters out undefined and null values, and properly encodes
+     * parameter names and values for URL use.
+     *
+     * @param {Record<string, string | number | boolean | undefined>} params - Query parameters
+     * @returns {string} Formatted query string with leading '?' or empty string
+     * @protected
+     *
+     * @example
+     * ```typescript
+     * buildQueryString({ field: 'username', value: 'john' })
+     * // Returns: "?field=username&value=john"
+     * ```
+     */
+    protected buildQueryString: (params: Record<string, string | number | boolean | undefined>) => string;
+}
+
+interface EmailAddress {
+    address: string;
+    type?: string;
+    label?: string;
+    primary?: string;
+}
+interface InstantMessaging {
+    uri: string;
+    protocol?: string;
+    label?: string;
+    primary?: string;
+}
+interface PhoneNumber {
+    number: string;
+    type?: string;
+    label?: string;
+    primary?: boolean;
+}
+interface ExtendedAddress {
+    locality?: string;
+    building?: string;
+    stairs?: string;
+    floor?: string;
+    apartment?: string;
+    entrycode?: string;
+}
+interface GeoLocation {
+    geo?: [number, number];
+    cozyCategory?: string;
+}
+interface Address {
+    id?: string;
+    street?: string;
+    pobox?: string;
+    city?: string;
+    region?: string;
+    number?: string;
+    code?: string;
+    country?: string;
+    type?: string;
+    label?: string;
+    primary?: boolean;
+    extendedAddress?: ExtendedAddress;
+    formattedAddress?: string;
+    geo?: GeoLocation;
+}
+interface UserName {
+    familyName?: string;
+    givenName?: string;
+    additionalName?: string;
+    namePrefix?: string;
+    nameSuffix?: string;
+    surname?: string;
+}
+interface User {
+    cn: string;
+    sn: string;
+    givenName: string;
+    displayName: string;
+    mail: string;
+    mobile: string;
+    userPassword: string;
+    scryptR: number;
+    scryptN: number;
+    scryptP: number;
+    scryptSalt: string;
+    scryptDKLength: number;
+    iterations: number;
+    domain: string;
+    publicKey: string;
+    privateKey: string;
+    protectedKey: string;
+    twoFactorEnabled?: string;
+    workspaceUrl?: string;
+    recoveryEmail?: string;
+    pwdAccountLockedTime?: string;
+    twakeOrganizationRole?: string;
+    fullname?: string;
+    name?: UserName;
+    birthday?: string;
+    gender?: string;
+    note?: string;
+    email?: EmailAddress[];
+    impp?: InstantMessaging[];
+    birthplace?: string;
+    jobTitle?: string;
+    company?: string;
+    phone?: PhoneNumber[];
+    address?: Address[];
+}
+interface UserCredentials {
+    userPassword: string;
+    scryptN: number;
+    scryptP: number;
+    scryptR: number;
+    scryptSalt: string;
+    scryptDKLength: number;
+    iterations: number;
+}
+interface UserKeys {
+    privateKey: string;
+    publicKey: string;
+    protectedKey: string;
+}
+type UserStatus = 'active' | 'disabled';
+type UserSearchField = 'username' | 'phone' | 'email' | 'recoveryEmail';
+interface CreateUserRequest extends UserCredentials, UserKeys {
+    cn: string;
+    uid: string;
+    givenName: string;
+    sn: string;
+    displayName: string;
+    mobile: string;
+    mail: string;
+    domain: string;
+    workspaceUrl?: string;
+    twoFactorEnabled?: string;
+    recoveryEmail?: string;
+    pwdAccountLockedTime?: string;
+    twakeOrganizationRole?: string;
+    fullname?: string;
+    name?: UserName;
+    birthday?: string;
+    gender?: string;
+    note?: string;
+    email?: EmailAddress[];
+    impp?: InstantMessaging[];
+    birthplace?: string;
+    jobTitle?: string;
+    company?: string;
+    phone?: PhoneNumber[];
+    address?: Address[];
+}
+interface UpdateUserRequest {
+    mobile?: string;
+    userPassword?: string;
+    protectedKey?: string;
+    twoFactorEnabled?: string | null;
+    recoveryEmail?: string;
+    displayName?: string;
+    pwdAccountLockedTime?: string;
+    twakeOrganizationRole?: string;
+    fullname?: string;
+    name?: UserName;
+    birthday?: string;
+    gender?: string;
+    note?: string;
+    email?: EmailAddress[];
+    impp?: InstantMessaging[];
+    birthplace?: string;
+    jobTitle?: string;
+    company?: string;
+    phone?: PhoneNumber[];
+    address?: Address[];
+    [key: string]: string | number | boolean | null | undefined | UserName | EmailAddress[] | InstantMessaging[] | PhoneNumber[] | Address[];
+}
+/**
+ * Request parameters for fetching a user
+ */
+interface FetchUserRequest extends Record<string, string | undefined> {
+    by: UserSearchField;
+    value: string;
+    fields?: string;
+}
+/**
+ * Parameters for checking availability of username, email, or phone
+ */
+interface CheckAvailabilityParams extends Record<string, string> {
+    field: string;
+    value: string;
+}
+/**
+ * Response from availability check
+ */
+interface CheckAvailabilityResponse {
+    available: boolean;
+}
+/**
+ * Parameters for listing users in an organization with pagination and filtering
+ */
+interface ListUsersParams {
+    /** Page number (default: 1) */
+    page?: number;
+    /** Items per page (default: 20, max: 100) */
+    limit?: number;
+    /** Filter by status ('active' or 'disabled') */
+    status?: UserStatus;
+    /** Search by username, email, or name (min 2 characters) */
+    search?: string;
+    /** Field to sort by ('username', 'createdAt', 'mail') */
+    sortBy?: string;
+    /** Sort order ('asc' or 'desc') */
+    sortOrder?: 'asc' | 'desc';
+    [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Response from listing users in an organization
+ */
+interface ListUsersResponse {
+    /** Array of users */
+    users: User[];
+    /** Pagination information */
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+        hasNextPage: boolean;
+        hasPreviousPage: boolean;
+    };
+}
+/**
+ * Response from creating a B2B user in an organization
+ */
+interface CreateB2BUserResponse {
+    /** Base DN of the created user */
+    baseDN: string;
+}
+
+/**
+ * Organization domain model representing a B2B organization
+ *
+ * Organizations have dedicated LDAP branches (baseDN) for managing
+ * B2B users separately from B2C users in the main branch.
+ */
+interface Organization {
+    /** Unique organization identifier (must start with 'org_') */
+    id: string;
+    /** Organization display name */
+    name: string;
+    /** Organization domain (e.g., 'acme.example.com') */
+    domain: string;
+    /** LDAP base DN for this organization's branch (e.g., 'ou=org_abc123,dc=example,dc=com') */
+    baseDN: string;
+    /** Organization status (active or suspended) */
+    status: OrganizationStatus;
+    /** Organization creation timestamp */
+    createdAt: Date;
+    /** Optional metadata for custom organization properties */
+    metadata?: OrganizationMetadata;
+}
+/**
+ * Organization status
+ *
+ * - active: Organization is operational and users can authenticate
+ * - suspended: Organization is temporarily disabled
+ */
+type OrganizationStatus = 'active' | 'suspended';
+/**
+ * Optional metadata for organization customization
+ *
+ * Allows storing custom properties like industry, company size,
+ * contact information, or any other organization-specific data.
+ */
+interface OrganizationMetadata {
+    /** Industry/sector (e.g., 'Technology', 'Healthcare') */
+    industry?: string;
+    /** Organization size (e.g., '1-10', '11-50', '51-200') */
+    size?: string;
+    /** Primary contact information */
+    contact?: string;
+    /** Additional custom fields as key-value pairs */
+    [key: string]: string | undefined;
+}
+/**
+ * Request parameters for creating an organization
+ */
+interface CreateOrganizationRequest {
+    id: string;
+    name: string;
+    domain: string;
+    metadata?: OrganizationMetadata;
+}
+/**
+ * Response from creating an organization
+ */
+interface CreateOrganizationResponse {
+    success: true;
+    organization: Organization;
+}
+/**
+ * Request parameters for linking an admin user to an organization
+ */
+interface CreateAdminRequest {
+    username: string;
+    mail: string;
+}
+/**
+ * Request parameters for updating an organization
+ */
+interface UpdateOrganizationRequest {
+    /** Organization display name */
+    name?: string;
+    /** Organization status */
+    status?: OrganizationStatus;
+    /** Optional metadata updates */
+    metadata?: OrganizationMetadata;
+}
+/**
+ * User role within an organization
+ */
+type OrganizationRole = 'admin' | 'moderator' | 'member';
+/**
+ * Request parameters for changing a user's role in an organization
+ */
+interface ChangeUserRoleRequest {
+    /** New role for the user */
+    role: OrganizationRole;
+}
+
+/**
+ * Group domain model representing a group within a B2B organization
+ *
+ * Groups allow organizing users within an organization for access control
+ * and team management.
+ */
+interface Group {
+    /** Unique group identifier */
+    id: string;
+    /** Group common name */
+    cn: string;
+    /** Group description */
+    description?: string;
+    /** Organization ID this group belongs to */
+    organizationId: string;
+    /** LDAP base DN for this group */
+    baseDN: string;
+    /** Array of usernames that are members of this group */
+    members: string[];
+    /** Group creation timestamp */
+    createdAt: string;
+}
+/**
+ * Request parameters for creating a group
+ */
+interface CreateGroupRequest {
+    /** Group common name (unique within organization) */
+    name: string;
+    /** Optional group description */
+    description?: string;
+}
+/**
+ * Response from creating a group
+ */
+interface CreateGroupResponse {
+    success: true;
+    group: Group;
+}
+/**
+ * Request parameters for updating a group
+ */
+interface UpdateGroupRequest {
+    /** Group description */
+    description?: string;
+    /** Group common name */
+    name?: string;
+}
+/**
+ * Request parameters for adding members to a group
+ */
+interface AddGroupMembersRequest {
+    /** Array of usernames to add to the group */
+    usernames: string[];
+}
+/**
+ * Parameters for listing groups with pagination
+ */
+interface ListGroupsParams {
+    /** Page number (default: 1) */
+    page?: number;
+    /** Items per page (default: 20, max: 100) */
+    limit?: number;
+    [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Response from listing groups
+ */
+interface ListGroupsResponse {
+    /** Organization identifier */
+    organizationId: string;
+    /** Array of groups */
+    groups: Group[];
+    /** Pagination information */
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+    };
+}
+
+/**
+ * Users resource - Manages B2C users in main LDAP branch
+ *
+ * Provides methods for creating, updating, deleting, and querying users
+ * in the main LDAP branch (B2C users). All operations require HMAC authentication.
+ *
+ * @example
+ * ```typescript
+ * const client = new LdapRestClient(config);
+ *
+ * // Create user
+ * await client.users.create({
+ *   cn: 'johndoe',
+ *   uid: 'johndoe',
+ *   // ... other fields
+ * });
+ *
+ * // Check availability
+ * const { available } = await client.users.checkAvailability({
+ *   field: 'username',
+ *   value: 'johndoe'
+ * });
+ * ```
+ */
+declare class UsersResource extends BaseResource {
+    /**
+     * Creates a new user in the main LDAP branch
+     *
+     * @param {CreateUserRequest} data - User data including credentials and profile
+     * @returns {Promise<{ success: true }>} Success response
+     * @throws {ConflictError} When username/email/phone already exists
+     * @throws {ApiError} On other API errors
+     */
+    create: (data: CreateUserRequest) => Promise<{
+        success: true;
+    }>;
+    /**
+     * Updates an existing user
+     *
+     * @param {string} userId - User identifier (username)
+     * @param {UpdateUserRequest} data - Fields to update
+     * @returns {Promise<{ success: true }>} Success response
+     * @throws {NotFoundError} When user is not found
+     * @throws {ApiError} On other API errors
+     */
+    update: (userId: string, data: UpdateUserRequest) => Promise<{
+        success: true;
+    }>;
+    /**
+     * Disables a user account
+     *
+     * Sets pwdAccountLockedTime to lock the account using LDAP PPolicy.
+     *
+     * @param {string} userId - User identifier (username)
+     * @returns {Promise<{ success: true }>} Success response
+     * @throws {NotFoundError} When user is not found
+     * @throws {ApiError} On other API errors
+     */
+    disable: (userId: string) => Promise<{
+        success: true;
+    }>;
+    /**
+     * Deletes a user
+     *
+     * Permanently removes the user from LDAP.
+     *
+     * @param {string} userId - User identifier (username)
+     * @returns {Promise<{ success: true }>} Success response
+     * @throws {NotFoundError} When user is not found
+     * @throws {ApiError} On other API errors
+     */
+    delete: (userId: string) => Promise<{
+        success: true;
+    }>;
+    /**
+     * Checks if a username, phone, or email is available
+     *
+     * @param {CheckAvailabilityParams} params - Field and value to check
+     * @returns {Promise<CheckAvailabilityResponse>} Availability status
+     * @throws {ApiError} On API errors
+     *
+     * @example
+     * ```typescript
+     * const result = await client.users.checkAvailability({
+     *   field: 'username',
+     *   value: 'johndoe'
+     * });
+     *
+     * ```
+     */
+    checkAvailability: (params: CheckAvailabilityParams) => Promise<CheckAvailabilityResponse>;
+    /**
+     * Fetches a user by identifier
+     *
+     * @param {FetchUserRequest} params - Fetch parameters (by, value, fields)
+     * @returns {Promise<User>} User data
+     * @throws {NotFoundError} When user is not found
+     * @throws {ApiError} On other API errors
+     *
+     * @example
+     * ```typescript
+     * const user = await client.users.fetch({
+     *   by: 'username',
+     *   value: 'johndoe',
+     *   fields: 'cn,mail,mobile'
+     * });
+     * ```
+     */
+    fetch: (params: FetchUserRequest) => Promise<User>;
+}
+
+/**
+ * Organizations resource - Manages organizations for B2B
+ *
+ * Provides methods for creating organizations and managing organization admins.
+ * Organizations have dedicated LDAP branches for B2B users.
+ *
+ * @example
+ * ```typescript
+ * const client = new LdapRestClient(config);
+ *
+ * // Create organization
+ * const org = await client.organizations.create({
+ *   id: 'org_abc123',
+ *   name: 'Acme Corp',
+ *   domain: 'acme.example.com',
+ *   metadata: { industry: 'Technology' }
+ * });
+ *
+ * // Link admin user
+ * await client.organizations.createAdmin('org_abc123', {
+ *   username: 'admin',
+ *   mail: 'admin@acme.example.com'
+ * });
+ * ```
+ */
+declare class OrganizationsResource extends BaseResource {
+    /**
+     * Creates a new organization with dedicated LDAP branch
+     *
+     * @param {CreateOrganizationRequest} data - Organization data
+     * @returns {Promise<CreateOrganizationResponse>} Organization details including baseDN
+     * @throws {ConflictError} When organization already exists
+     * @throws {ApiError} On other API errors
+     */
+    create: (data: CreateOrganizationRequest) => Promise<CreateOrganizationResponse>;
+    /**
+     * Checks if an organization identifier is available
+     *
+     * @param {CheckAvailabilityParams} params - Field and value to check
+     * @returns {Promise<CheckAvailabilityResponse>} Availability status
+     * @throws {ApiError} On API errors
+     *
+     * @example
+     * ```typescript
+     * const result = await client.organizations.checkAvailability({
+     *   field: 'domain',
+     *   value: 'acme.example.com'
+     * });
+     * ```
+     */
+    checkAvailability: (params: CheckAvailabilityParams) => Promise<CheckAvailabilityResponse>;
+    /**
+     * Links a user as the first admin of an organization
+     *
+     * Associates an existing user account with an organization and grants
+     * admin privileges. Typically called after organization creation.
+     *
+     * @param {string} organizationId - Organization identifier
+     * @param {CreateAdminRequest} data - Admin user details (username and email)
+     * @returns {Promise<{ success: true }>} Success response
+     * @throws {NotFoundError} When organization or user is not found
+     * @throws {ConflictError} When user is already an admin
+     * @throws {ApiError} On other API errors
+     *
+     * @example
+     * ```typescript
+     * await client.organizations.createAdmin('org_abc123', {
+     *   username: 'john.doe',
+     *   mail: 'john.doe@acme.example.com'
+     * });
+     * ```
+     */
+    createAdmin: (organizationId: string, data: CreateAdminRequest) => Promise<{
+        success: true;
+    }>;
+    /**
+     * Gets a list of organizations for the authenticated user
+     *
+     * Requires SSO cookie authentication. Returns organizations where the
+     * authenticated user has admin role.
+     *
+     * @returns {Promise<Organization[]>} Array of organizations
+     * @throws {ApiError} On API errors
+     *
+     * @example
+     * ```typescript
+     * const organizations = await client.organizations.list();
+     * ```
+     */
+    list: () => Promise<Organization[]>;
+    /**
+     * Gets details of a specific organization
+     *
+     * Requires SSO cookie authentication.
+     *
+     * @param {string} organizationId - Organization identifier
+     * @returns {Promise<Organization>} Organization details
+     * @throws {NotFoundError} When organization is not found
+     * @throws {ApiError} On other API errors
+     *
+     * @example
+     * ```typescript
+     * const org = await client.organizations.get('org_abc123');
+     * ```
+     */
+    get: (organizationId: string) => Promise<Organization>;
+    /**
+     * Updates an organization
+     *
+     * Requires SSO cookie authentication and admin role.
+     *
+     * @param {string} organizationId - Organization identifier
+     * @param {UpdateOrganizationRequest} data - Fields to update
+     * @returns {Promise<{ success: true }>} Success response
+     * @throws {NotFoundError} When organization is not found
+     * @throws {ForbiddenError} When user lacks admin privileges
+     * @throws {ApiError} On other API errors
+     *
+     * @example
+     * ```typescript
+     * await client.organizations.update('org_abc123', {
+     *   name: 'New Organization Name',
+     *   status: 'active'
+     * });
+     * ```
+     */
+    update: (organizationId: string, data: UpdateOrganizationRequest) => Promise<{
+        success: true;
+    }>;
+    /**
+     * Creates a new user in an organization's LDAP branch
+     *
+     * Requires SSO cookie authentication and admin role in the target organization.
+     *
+     * @param {string} organizationId - Organization identifier
+     * @param {CreateUserRequest} data - User data including credentials and profile
+     * @returns {Promise<CreateB2BUserResponse>} Response with user's baseDN
+     * @throws {ForbiddenError} When user lacks admin privileges
+     * @throws {NotFoundError} When organization is not found
+     * @throws {ConflictError} When username/email/phone already exists
+     * @throws {ApiError} On other API errors
+     *
+     * @example
+     * ```typescript
+     * const result = await client.organizations.createUser('org_abc123', {
+     *   cn: 'john.doe',
+     *   uid: 'john.doe',
+     *   // ... other user fields
+     * });
+     * ```
+     */
+    createUser: (organizationId: string, data: CreateUserRequest) => Promise<CreateB2BUserResponse>;
+    /**
+     * Updates a user in an organization
+     *
+     * Requires SSO cookie authentication and admin role in the target organization.
+     *
+     * @param {string} organizationId - Organization identifier
+     * @param {string} userId - User identifier (username)
+     * @param {UpdateUserRequest} data - Fields to update
+     * @returns {Promise<{ success: true }>} Success response
+     * @throws {NotFoundError} When user or organization is not found
+     * @throws {ForbiddenError} When user lacks admin privileges
+     * @throws {ApiError} On other API errors
+     *
+     * @example
+     * ```typescript
+     * await client.organizations.updateUser('org_abc123', 'john.doe', {
+     *   mobile: '+33687654321'
+     * });
+     * ```
+     */
+    updateUser: (organizationId: string, userId: string, data: UpdateUserRequest) => Promise<{
+        success: true;
+    }>;
+    /**
+     * Disables a user in an organization
+     *
+     * Locks the account by setting pwdAccountLockedTime using LDAP PPolicy.
+     * Requires SSO cookie authentication and admin role.
+     *
+     * @param {string} organizationId - Organization identifier
+     * @param {string} userId - User identifier (username)
+     * @returns {Promise<{ success: true }>} Success response
+     * @throws {NotFoundError} When user or organization is not found
+     * @throws {ForbiddenError} When user lacks admin privileges
+     * @throws {ApiError} On other API errors
+     *
+     * @example
+     * ```typescript
+     * await client.organizations.disableUser('org_abc123', 'john.doe');
+     * ```
+     */
+    disableUser: (organizationId: string, userId: string) => Promise<{
+        success: true;
+    }>;
+    /**
+     * Deletes a user from an organization
+     *
+     * Permanently removes the user from the organization's LDAP branch.
+     * Requires SSO cookie authentication and admin role.
+     *
+     * @param {string} organizationId - Organization identifier
+     * @param {string} userId - User identifier (username)
+     * @returns {Promise<{ success: true }>} Success response
+     * @throws {NotFoundError} When user or organization is not found
+     * @throws {ForbiddenError} When user lacks admin privileges
+     * @throws {ApiError} On other API errors
+     *
+     * @example
+     * ```typescript
+     * await client.organizations.deleteUser('org_abc123', 'john.doe');
+     * ```
+     */
+    deleteUser: (organizationId: string, userId: string) => Promise<{
+        success: true;
+    }>;
+    /**
+     * Fetches a user from an organization by identifier
+     *
+     * Requires SSO cookie authentication and admin role.
+     *
+     * @param {string} organizationId - Organization identifier
+     * @param {FetchUserRequest} params - Fetch parameters (by, value, fields)
+     * @returns {Promise<User>} User data
+     * @throws {NotFoundError} When user or organization is not found
+     * @throws {ForbiddenError} When user lacks admin privileges
+     * @throws {ApiError} On other API errors
+     *
+     * @example
+     * ```typescript
+     * const user = await client.organizations.getUser('org_abc123', {
+     *   by: 'username',
+     *   value: 'john.doe',
+     *   fields: 'cn,mail,mobile'
+     * });
+     * ```
+     */
+    getUser: (organizationId: string, params: FetchUserRequest) => Promise<User>;
+    /**
+     * Lists users in an organization with pagination and filtering
+     *
+     * Requires SSO cookie authentication and admin role.
+     *
+     * @param {string} organizationId - Organization identifier
+     * @param {ListUsersParams} params - Pagination and filter parameters
+     * @returns {Promise<ListUsersResponse>} Paginated list of users
+     * @throws {NotFoundError} When organization is not found
+     * @throws {ForbiddenError} When user lacks admin privileges
+     * @throws {ApiError} On other API errors
+     *
+     * @example
+     * ```typescript
+     * const result = await client.organizations.listUsers('org_abc123', {
+     *   page: 1,
+     *   limit: 20,
+     *   status: 'active',
+     *   search: 'john',
+     *   sortBy: 'createdAt',
+     *   sortOrder: 'desc'
+     * });
+     * ```
+     */
+    listUsers: (organizationId: string, params?: ListUsersParams) => Promise<ListUsersResponse>;
+    /**
+     * Checks if a username, phone, or email is available in an organization
+     *
+     * Requires SSO cookie authentication and admin role.
+     *
+     * @param {string} organizationId - Organization identifier
+     * @param {CheckAvailabilityParams} params - Field and value to check
+     * @returns {Promise<CheckAvailabilityResponse>} Availability status
+     * @throws {NotFoundError} When organization is not found
+     * @throws {ForbiddenError} When user lacks admin privileges
+     * @throws {ApiError} On other API errors
+     *
+     * @example
+     * ```typescript
+     * const result = await client.organizations.checkUserAvailability('org_abc123', {
+     *   field: 'username',
+     *   value: 'john.doe'
+     * });
+     * ```
+     */
+    checkUserAvailability: (organizationId: string, params: CheckAvailabilityParams) => Promise<CheckAvailabilityResponse>;
+    /**
+     * Changes a user's role in an organization
+     *
+     * Available roles: admin, moderator, member.
+     * Requires SSO cookie authentication and admin role.
+     * Cannot change your own role or remove the last admin.
+     *
+     * @param {string} organizationId - Organization identifier
+     * @param {string} userId - User identifier (username)
+     * @param {ChangeUserRoleRequest} data - New role
+     * @returns {Promise<{ success: true }>} Success response
+     * @throws {NotFoundError} When user or organization is not found
+     * @throws {ForbiddenError} When attempting self-demotion or removing last admin
+     * @throws {ApiError} On other API errors
+     *
+     * @example
+     * ```typescript
+     * await client.organizations.changeUserRole('org_abc123', 'john.doe', {
+     *   role: 'moderator'
+     * });
+     * ```
+     */
+    changeUserRole: (organizationId: string, userId: string, data: ChangeUserRoleRequest) => Promise<{
+        success: true;
+    }>;
+}
+
+/**
+ * Groups resource - Manages groups within B2B organizations
+ *
+ * Provides methods for creating, updating, deleting groups and managing
+ * group memberships. All operations require SSO cookie authentication
+ * and admin role in the target organization.
+ *
+ * @example
+ * ```typescript
+ * const client = new LdapRestClient(config);
+ *
+ * // Create group
+ * const group = await client.groups.create('org_abc123', {
+ *   name: 'engineering',
+ *   description: 'Engineering team'
+ * });
+ *
+ * // Add members
+ * await client.groups.addMembers('org_abc123', 'grp_xyz789', {
+ *   usernames: ['john.doe', 'jane.smith']
+ * });
+ * ```
+ */
+declare class GroupsResource extends BaseResource {
+    /**
+     * Creates a new group in an organization
+     *
+     * Requires SSO cookie authentication and admin role in the target organization.
+     *
+     * @param {string} organizationId - Organization identifier
+     * @param {CreateGroupRequest} data - Group data (name and optional description)
+     * @returns {Promise<CreateGroupResponse>} Created group details
+     * @throws {ForbiddenError} When user lacks admin privileges
+     * @throws {NotFoundError} When organization is not found
+     * @throws {ConflictError} When group name already exists
+     * @throws {ApiError} On other API errors
+     *
+     * @examples
+     * ```typescript
+     * const result = await client.groups.create('org_abc123', {
+     *   name: 'engineering',
+     *   description: 'Engineering team'
+     * });
+     * ```
+     */
+    create: (organizationId: string, data: CreateGroupRequest) => Promise<CreateGroupResponse>;
+    /**
+     * Lists all groups in an organization with pagination
+     *
+     * Requires SSO cookie authentication and admin role.
+     *
+     * @param {string} organizationId - Organization identifier
+     * @param {ListGroupsParams} params - Pagination parameters (page, limit)
+     * @returns {Promise<ListGroupsResponse>} Paginated list of groups
+     * @throws {NotFoundError} When organization is not found
+     * @throws {ForbiddenError} When user lacks admin privileges
+     * @throws {ApiError} On other API errors
+     *
+     * @example
+     * ```typescript
+     * const result = await client.groups.list('org_abc123', {
+     *   page: 1,
+     *   limit: 20
+     * });
+     * ```
+     */
+    list: (organizationId: string, params?: ListGroupsParams) => Promise<ListGroupsResponse>;
+    /**
+     * Gets details of a specific group
+     *
+     * Requires SSO cookie authentication and admin role.
+     *
+     * @param {string} organizationId - Organization identifier
+     * @param {string} groupId - Group identifier
+     * @returns {Promise<Group>} Group details including members
+     * @throws {NotFoundError} When organization or group is not found
+     * @throws {ForbiddenError} When user lacks admin privileges
+     * @throws {ApiError} On other API errors
+     *
+     * @example
+     * ```typescript
+     * const group = await client.groups.get('org_abc123', 'grp_xyz789');
+     * ```
+     */
+    get: (organizationId: string, groupId: string) => Promise<Group>;
+    /**
+     * Updates a group's properties
+     *
+     * Requires SSO cookie authentication and admin role.
+     *
+     * @param {string} organizationId - Organization identifier
+     * @param {string} groupId - Group identifier
+     * @param {UpdateGroupRequest} data - Fields to update (name, description)
+     * @returns {Promise<{ success: true }>} Success response
+     * @throws {NotFoundError} When organization or group is not found
+     * @throws {ForbiddenError} When user lacks admin privileges
+     * @throws {ConflictError} When new group name already exists
+     * @throws {ApiError} On other API errors
+     *
+     * @example
+     * ```typescript
+     * await client.groups.update('org_abc123', 'grp_xyz789', {
+     *   description: 'Updated description'
+     * });
+     * ```
+     */
+    update: (organizationId: string, groupId: string, data: UpdateGroupRequest) => Promise<{
+        success: true;
+    }>;
+    /**
+     * Deletes a group from an organization
+     *
+     * Permanently removes the group. Members are not deleted, only the group itself.
+     * Requires SSO cookie authentication and admin role.
+     *
+     * @param {string} organizationId - Organization identifier
+     * @param {string} groupId - Group identifier
+     * @returns {Promise<{ success: true }>} Success response
+     * @throws {NotFoundError} When organization or group is not found
+     * @throws {ForbiddenError} When user lacks admin privileges
+     * @throws {ApiError} On other API errors
+     *
+     * @example
+     * ```typescript
+     * await client.groups.delete('org_abc123', 'grp_xyz789');
+     * ```
+     */
+    delete: (organizationId: string, groupId: string) => Promise<{
+        success: true;
+    }>;
+    /**
+     * Adds users to a group
+     *
+     * Adds one or more users to the group's member list.
+     * Requires SSO cookie authentication and admin role.
+     *
+     * @param {string} organizationId - Organization identifier
+     * @param {string} groupId - Group identifier
+     * @param {AddGroupMembersRequest} data - Usernames to add
+     * @returns {Promise<{ success: true }>} Success response
+     * @throws {NotFoundError} When organization, group, or users are not found
+     * @throws {ForbiddenError} When user lacks admin privileges
+     * @throws {ApiError} On other API errors
+     *
+     * @example
+     * ```typescript
+     * await client.groups.addMembers('org_abc123', 'grp_xyz789', {
+     *   usernames: ['alice.johnson', 'bob.wilson']
+     * });
+     * ```
+     */
+    addMembers: (organizationId: string, groupId: string, data: AddGroupMembersRequest) => Promise<{
+        success: true;
+    }>;
+    /**
+     * Removes a user from a group
+     *
+     * Removes a specific user from the group's member list.
+     * Requires SSO cookie authentication and admin role.
+     *
+     * @param {string} organizationId - Organization identifier
+     * @param {string} groupId - Group identifier
+     * @param {string} userId - User identifier (username) to remove
+     * @returns {Promise<{ success: true }>} Success response
+     * @throws {NotFoundError} When organization, group, or user is not found
+     * @throws {ForbiddenError} When user lacks admin privileges
+     * @throws {ApiError} On other API errors
+     *
+     * @example
+     * ```typescript
+     * await client.groups.removeMember('org_abc123', 'grp_xyz789', 'bob.wilson');
+     * ```
+     */
+    removeMember: (organizationId: string, groupId: string, userId: string) => Promise<{
+        success: true;
+    }>;
+}
+
+/**
+ * LDAP-REST API Client
+ *
+ * Main client class for interacting with the LDAP-REST API.
+ * Provides access to Users, Organizations, and Groups resources with HMAC or Cookie authentication.
+ *
+ * @example
+ * ```typescript
+ * // HMAC authentication for backend services
+ * const client = new LdapRestClient({
+ *   baseUrl: 'https://ldap-rest.example.com',
+ *   auth: {
+ *     type: 'hmac',
+ *     serviceId: 'my-service',
+ *     secret: 'my-secret-key-at-least-32-chars',
+ *   }
+ * });
+ *
+ * // Cookie authentication for browser (SSO)
+ * const browserClient = new LdapRestClient({
+ *   baseUrl: 'https://ldap-rest.example.com'
+ * });
+ *
+ * await client.users.create({ ... });
+ * await client.groups.create('org_abc123', { name: 'engineering' });
+ * ```
+ */
+declare class LdapRestClient {
+    readonly users: UsersResource;
+    readonly organizations: OrganizationsResource;
+    readonly groups: GroupsResource;
+    private readonly config;
+    /**
+     * Creates a new LDAP-REST client instance
+     *
+     * @param {ClientConfig} config - Client configuration
+     * @throws {Error} When configuration is invalid
+     */
+    constructor(config: ClientConfig);
+    /**
+     * Gets the configured base URL
+     *
+     * @returns {string} The base URL of the LDAP-REST API
+     */
+    getBaseUrl: () => string;
+}
+
+/**
+ * Base error class for all LDAP-REST client errors
+ *
+ * All errors thrown by the client extend from this base class,
+ * providing consistent error handling with status codes and error codes.
+ */
+declare class LdapRestError extends Error {
+    /** Error class name (automatically set to constructor name) */
+    readonly name: string;
+    /** HTTP status code associated with the error (if applicable) */
+    readonly statusCode?: number;
+    /** Machine-readable error code for programmatic handling */
+    readonly code?: string;
+    /**
+     * Creates a new LDAP-REST error
+     *
+     * @param {string} message - Human-readable error message
+     * @param {number} [statusCode] - HTTP status code
+     * @param {string} [code] - Machine-readable error code
+     */
+    constructor(message: string, statusCode?: number, code?: string);
+}
+
+/**
+ * Error thrown when the API returns an error response
+ *
+ * Generic API error for non-specific HTTP errors that don't fall
+ * into other specialized error categories.
+ */
+declare class ApiError extends LdapRestError {
+    /**
+     * Creates a new API error
+     *
+     * @param {string} message - Human-readable error message
+     * @param {number} statusCode - HTTP status code
+     * @param {string} code - Machine-readable error code
+     */
+    constructor(message: string, statusCode: number, code: string);
+    /**
+     * Creates an ApiError from an API response body
+     *
+     * @param {number} statusCode - HTTP status code from response
+     * @param {{ error: string; code: string }} body - Response body containing error details
+     * @returns {ApiError} New ApiError instance
+     */
+    static fromResponse(statusCode: number, body: {
+        error: string;
+        code: string;
+    }): ApiError;
+}
+/**
+ * Error thrown when request validation fails (HTTP 400)
+ *
+ * Indicates that the request parameters or body failed validation
+ * before being sent to the server, or the server rejected the request
+ * due to invalid data.
+ */
+declare class ValidationError extends LdapRestError {
+    /**
+     * Creates a new validation error
+     *
+     * @param {string} message - Description of what validation failed
+     */
+    constructor(message: string);
+}
+/**
+ * Error thrown when authentication fails (HTTP 401)
+ *
+ * Indicates that the HMAC signature is invalid or the request
+ * lacks proper authentication credentials.
+ */
+declare class AuthenticationError extends LdapRestError {
+    /**
+     * Creates a new authentication error
+     *
+     * @param {string} message - Authentication failure reason
+     */
+    constructor(message: string);
+}
+/**
+ * Error thrown when authorization fails (HTTP 403)
+ *
+ * Indicates that the authenticated service lacks permission
+ * to perform the requested operation.
+ */
+declare class AuthorizationError extends LdapRestError {
+    /**
+     * Creates a new authorization error
+     *
+     * @param {string} message - Authorization failure reason
+     */
+    constructor(message: string);
+}
+/**
+ * Error thrown when a resource is not found (HTTP 404)
+ *
+ * Indicates that the requested user, organization, or other
+ * resource does not exist in the LDAP directory.
+ */
+declare class NotFoundError extends LdapRestError {
+    /**
+     * Creates a new not found error
+     *
+     * @param {string} message - Description of what was not found
+     * @param {string} [code] - Optional specific error code (defaults to 'NOT_FOUND')
+     */
+    constructor(message: string, code?: string);
+}
+/**
+ * Error thrown when a resource conflict occurs (HTTP 409)
+ *
+ * Indicates that the operation conflicts with existing data,
+ * such as attempting to create a user with a duplicate username,
+ * email, or phone number.
+ */
+declare class ConflictError extends LdapRestError {
+    /**
+     * Creates a new conflict error
+     *
+     * @param {string} message - Description of the conflict
+     * @param {string} [code] - Optional specific error code (e.g., 'USERNAME_EXISTS', 'EMAIL_EXISTS')
+     */
+    constructor(message: string, code?: string);
+}
+/**
+ * Error thrown when rate limit is exceeded (HTTP 429)
+ *
+ * Indicates that too many requests have been sent in a given
+ * time period. The client should wait before retrying.
+ */
+declare class RateLimitError extends LdapRestError {
+    /** Number of seconds to wait before retrying (from Retry-After header) */
+    readonly retryAfter?: number;
+    /**
+     * Creates a new rate limit error
+     *
+     * @param {string} message - Rate limit error message
+     * @param {number} [retryAfter] - Seconds to wait before retrying
+     */
+    constructor(message: string, retryAfter?: number);
+}
+/**
+ * Error thrown when a network request fails
+ *
+ * Indicates connection failures, timeouts, or other network-level
+ * errors that prevent the request from reaching the server.
+ */
+declare class NetworkError extends LdapRestError {
+    /** Original error that caused the network failure */
+    readonly cause?: Error;
+    /**
+     * Creates a new network error
+     *
+     * @param {string} message - Network error description
+     * @param {Error} [cause] - Original error that caused the failure
+     */
+    constructor(message: string, cause?: Error);
+}
+
+export { type AddGroupMembersRequest, type Address, ApiError, AuthenticationError, AuthorizationError, type ChangeUserRoleRequest, type CheckAvailabilityParams, type CheckAvailabilityResponse, type ClientConfig, ConflictError, type CreateAdminRequest, type CreateB2BUserResponse, type CreateGroupRequest, type CreateGroupResponse, type CreateOrganizationRequest, type CreateOrganizationResponse, type CreateUserRequest, type EmailAddress, type ExtendedAddress, type FetchUserRequest, type GeoLocation, type Group, GroupsResource, type InstantMessaging, LdapRestClient, LdapRestError, type ListGroupsParams, type ListGroupsResponse, type ListUsersParams, type ListUsersResponse, NetworkError, NotFoundError, type Organization, type OrganizationMetadata, type OrganizationRole, type OrganizationStatus, OrganizationsResource, type PhoneNumber, RateLimitError, type UpdateGroupRequest, type UpdateOrganizationRequest, type UpdateUserRequest, type User, type UserCredentials, type UserKeys, type UserName, type UserSearchField, type UserStatus, UsersResource, ValidationError };