ldap-rest-client

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

npm install @linagora/ldap-rest-client

Quick Start

Backend (HMAC Authentication)

import { LdapRestClient } from '@linagora/ldap-rest-client';

const client = new LdapRestClient({
  baseUrl: 'https://ldap-rest.example.com',
  auth: {
    type: 'hmac',
    serviceId: 'registration-service',
    secret: 'your-secret-key-at-least-32-chars-long',
  },
});

// Create B2C user
await client.users.create({
  username: 'johndoe',
  mail: '[email protected]',
  givenName: 'John',
  cn: 'John Doe',
  sn: 'Doe',
  userPassword: 'secure-password',
});

// Create organization
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: '[email protected]',
  givenName: 'Jane',
  cn: 'Jane Smith',
  sn: 'Smith',
});

Browser (SSO Cookie)

const client = new LdapRestClient({
  baseUrl: 'https://ldap-rest.example.com',
  // auth defaults to browser cookie-based authentication
});

// List users in organization
const result = await client.organizations.listUsers('acme-corp', {
  page: 1,
  limit: 20,
});

// Create and manage groups
const group = await client.groups.create('acme-corp', {
  name: 'engineering',
  description: 'Engineering team',
});

await client.groups.addMembers('acme-corp', group._id, {
  usernames: ['user1', 'user2'],
});

API Overview

The client provides three main resource interfaces:

• client.users - B2C user management (top-level users)
• client.organizations - Organization and B2B user management
• client.groups - Group management within organizations

For complete API documentation, see API.md.

Key Concepts

Authentication:

• HMAC-SHA256: For server-to-server communication
• Cookie/SSO: For browser-based applications

Configuration

const client = new LdapRestClient({
  baseUrl: 'https://ldap-rest.example.com', // Required
  auth: {
    type: 'hmac', // or 'cookie'
    serviceId: 'my-service',
    secret: 'your-secret-key-at-least-32-chars-long',
  },
  timeout: 30000, // Optional, default: 30000ms
  logger: {
    minLevel: 'info', // Optional, tslog configuration
  },
});

See API.md - Configuration for detailed options.

Error Handling

All errors extend LdapRestError and map to specific HTTP status codes:

import {
  ValidationError,
  NotFoundError,
  ConflictError,
} from '@linagora/ldap-rest-client';

try {
  await client.users.create(userData);
} catch (error) {
  if (error instanceof ConflictError) {
    console.error('User already exists');
  } else if (error instanceof ValidationError) {
    console.error('Invalid data:', error.message);
  }
}

Available error types: ValidationError (400), AuthenticationError (401), AuthorizationError (403), NotFoundError (404), ConflictError (409), RateLimitError (429), NetworkError, ApiError.

See API.md - Error Handling for complete documentation.

Documentation

• API Reference - Complete API documentation

Development

# 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