ldap-rest 0.1.4 → 0.1.6

package/docs/{DEVELOPER_GUIDE.md → client-development/README.md}

@@ -11,17 +11,17 @@ Welcome to the LDAP-Rest Developer Guide! This guide helps you build web applica
 
 ### 📚 Core Documentation
 
-- **[REST API Documentation](./api/REST_API.md)** - Complete API reference (Config, Users, Groups, Organizations)
-- **[Browser Libraries](./browser/LIBRARIES.md)** - LdapTreeViewer and LdapUserEditor
-- **[JSON Schemas](./schemas/SCHEMAS.md)** - Schema structure and validation
-- **[Integration Examples](./examples/EXAMPLES.md)** - React, Vue.js, Vanilla JavaScript examples
-- **[Plugin Development](./plugins/DEVELOPMENT.md)** - Create your own plugins
+- **[REST API Documentation](./api/rest-api.md)** - Complete API reference (Config, Users, Groups, Organizations)
+- **[Browser Libraries](./browser/libraries.md)** - LdapTreeViewer and LdapUserEditor
+- **[JSON Schemas](./schemas/README.md)** - Schema structure and validation
+- **[Integration Examples](./examples/README.md)** - React, Vue.js, Vanilla JavaScript examples
+- **[Plugin Development](../plugin-development/README.md)** - Create your own plugins
 
 ### 🔧 Reference
 
-- **[API Reference](./api/REFERENCE.md)** - Complete API reference with all endpoints
-- [Authentication](./api/REST_API.md#authentication) - OpenID, Token, LemonLDAP::NG
-- [Troubleshooting](./api/REFERENCE.md#troubleshooting) - Common issues and solutions
+- **[API Reference](./api/reference.md)** - Complete API reference with all endpoints
+- [Authentication](./api/rest-api.md#authentication) - OpenID, Token, LemonLDAP::NG
+- [Troubleshooting](./api/reference.md#troubleshooting) - Common issues and solutions
 
 ---
 
@@ -152,14 +152,14 @@ console.log(config);
 
 ### API Documentation
 
-- **[REST API Guide](./api/REST_API.md)**
+- **[REST API Guide](./api/rest-api.md)**
   - Configuration API
   - Organizations API
   - Users API
   - Groups API
   - Authentication
 
-- **[Complete API Reference](./api/REFERENCE.md)**
+- **[Complete API Reference](./api/reference.md)**
   - All endpoints with examples
   - Request/response formats
   - Error codes
@@ -167,7 +167,7 @@ console.log(config);
 
 ### Browser Libraries
 
-- **[Browser Libraries Guide](./browser/LIBRARIES.md)**
+- **[Browser Libraries Guide](./browser/libraries.md)**
   - LdapTreeViewer - Interactive LDAP tree
   - LdapUserEditor - Complete user editor
   - Configuration options
@@ -176,7 +176,7 @@ console.log(config);
 
 ### Schemas
 
-- **[JSON Schemas Guide](./schemas/SCHEMAS.md)**
+- **[JSON Schemas Guide](./schemas/README.md)**
   - Schema structure
   - Entity metadata
   - Attribute types
@@ -186,7 +186,7 @@ console.log(config);
 
 ### Integration
 
-- **[Integration Examples](./examples/EXAMPLES.md)**
+- **[Integration Examples](./examples/README.md)**
   - React application
   - Vue.js application
   - Vanilla JavaScript
@@ -195,7 +195,7 @@ console.log(config);
 
 ### Plugin Development
 
-- **[Plugin Development Guide](./plugins/DEVELOPMENT.md)**
+- **[Plugin Development Guide](../plugin-development/README.md)**
   - Creating plugins
   - Custom configuration
   - Hooks system
@@ -234,7 +234,7 @@ LDAP-Rest uses JSON schemas to define LDAP entity structure:
 }
 ```
 
-See [JSON Schemas Guide](./schemas/SCHEMAS.md) for details.
+See [JSON Schemas Guide](./schemas/README.md) for details.
 
 ### Dynamic Configuration
 
@@ -252,7 +252,7 @@ const usersEndpoint = config.features.ldapFlatGeneric.flatResources.find(
 const users = await fetch(usersEndpoint).then(r => r.json());
 ```
 
-See [REST API Guide](./api/REST_API.md) for details.
+See [REST API Guide](./api/rest-api.md) for details.
 
 ### Plugin-Based Extensibility
 
@@ -263,25 +263,25 @@ Extend LDAP-Rest with custom plugins that:
 - Integrate external systems
 - Implement custom logic
 
-See [Plugin Development Guide](./plugins/DEVELOPMENT.md) for details.
+See [Plugin Development Guide](../plugin-development/README.md) for details.
 
 ---
 
 ## Next Steps
 
-1. **Learn the API** - Read the [REST API Guide](./api/REST_API.md)
-2. **Try the Libraries** - Check the [Browser Libraries Guide](./browser/LIBRARIES.md)
-3. **See Examples** - Explore [Integration Examples](./examples/EXAMPLES.md)
-4. **Build a Plugin** - Follow the [Plugin Development Guide](./plugins/DEVELOPMENT.md)
+1. **Learn the API** - Read the [REST API Guide](./api/rest-api.md)
+2. **Try the Libraries** - Check the [Browser Libraries Guide](./browser/libraries.md)
+3. **See Examples** - Explore [Integration Examples](./examples/README.md)
+4. **Build a Plugin** - Follow the [Plugin Development Guide](../plugin-development/README.md)
 
 ---
 
 ## Resources
 
 - [GitHub Repository](https://github.com/linagora/ldap-rest)
-- [Contributing Guide](../CONTRIBUTING.md)
-- [Plugin Development](../src/plugins/README.md)
-- [Hooks Reference](../HOOKS.md)
+- [Contributing Guide](../../CONTRIBUTING.md)
+- [Plugin Development](../plugin-development/README.md)
+- [Hooks Reference](../plugin-development/hooks.md)
 
 ---
 

package/docs/client-development/api/README.md

@@ -0,0 +1,75 @@
+# REST API
+
+LDAP-Rest REST API documentation.
+
+## Overview
+
+The LDAP-Rest REST API exposes endpoints for managing LDAP entities.
+
+## Documentation
+
+- **[rest-api.md](rest-api.md)** - Complete API usage guide
+- **[reference.md](reference.md)** - Technical reference (HTTP codes, headers, URL encoding)
+- **[openapi.md](openapi.md)** - OpenAPI specification
+
+## Authentication
+
+All API requests require authentication. See the [authentication documentation](../../usage/plugins/auth/README.md).
+
+### Token Example
+
+```bash
+curl -H "Authorization: Bearer your-token" \
+  http://localhost:8081/api/v1/ldap/users
+```
+
+## Main Endpoints
+
+### Entities (ldapFlatGeneric)
+
+```
+GET    /api/v1/ldap/{pluralName}           # List
+GET    /api/v1/ldap/{pluralName}/{id}      # Get
+POST   /api/v1/ldap/{pluralName}           # Create
+PUT    /api/v1/ldap/{pluralName}/{id}      # Modify
+DELETE /api/v1/ldap/{pluralName}/{id}      # Delete
+```
+
+### Groups
+
+```
+GET    /api/v1/ldap/groups
+GET    /api/v1/ldap/groups/{cn}
+POST   /api/v1/ldap/groups
+PUT    /api/v1/ldap/groups/{cn}
+DELETE /api/v1/ldap/groups/{cn}
+```
+
+### Organizations
+
+```
+GET    /api/v1/ldap/organizations/top
+GET    /api/v1/ldap/organizations/{dn}/subnodes
+POST   /api/v1/ldap/organizations
+PUT    /api/v1/ldap/organizations/{dn}
+DELETE /api/v1/ldap/organizations/{dn}
+```
+
+### Configuration
+
+```
+GET    /api/v1/config     # Available capabilities and schemas
+```
+
+## Response Codes
+
+| Code | Description               |
+| ---- | ------------------------- |
+| 200  | Success                   |
+| 201  | Created                   |
+| 400  | Invalid request           |
+| 401  | Not authenticated         |
+| 403  | Access forbidden          |
+| 404  | Not found                 |
+| 409  | Conflict (existing entry) |
+| 500  | Server error              |

package/docs/client-development/browser/README.md

@@ -0,0 +1,65 @@
+# Browser Libraries
+
+Web components for integrating LDAP-Rest into your applications.
+
+## Overview
+
+LDAP-Rest provides reusable web components for LDAP management.
+
+## Documentation
+
+- **[libraries.md](libraries.md)** - Complete component documentation
+
+## Available Components
+
+| Component            | Description                    |
+| -------------------- | ------------------------------ |
+| `LdapTreeViewer`     | LDAP tree navigation           |
+| `LdapUserEditor`     | User editing                   |
+| `LdapGroupEditor`    | Group management               |
+| `LdapUnitEditor`     | Organizational unit management |
+| `LdapResourceEditor` | Resource management            |
+
+## Utilities
+
+| Module                        | Description                    |
+| ----------------------------- | ------------------------------ |
+| `browser-shared-utils-totp`   | TOTP client for authentication |
+| `browser-shared-utils-hmac`   | HMAC client for authentication |
+| `browser-shared-utils-dom`    | DOM utilities                  |
+| `browser-shared-utils-form`   | Form utilities                 |
+| `browser-shared-utils-schema` | JSON schema utilities          |
+
+## Installation
+
+```bash
+npm install ldap-rest
+```
+
+## Import
+
+```typescript
+// Components
+import { LdapTreeViewer, LdapUserEditor } from 'ldap-rest/browser';
+
+// Utilities
+import { TotpAuthClient } from 'ldap-rest/browser-shared-utils-totp';
+import { HmacAuthClient } from 'ldap-rest/browser-shared-utils-hmac';
+```
+
+## Quick Example
+
+```typescript
+import { LdapTreeViewer } from 'ldap-rest/browser';
+
+const viewer = new LdapTreeViewer({
+  apiUrl: 'http://localhost:8081/api/v1',
+  container: document.getElementById('tree'),
+});
+
+viewer.render();
+```
+
+## Demos
+
+Interactive examples are available in the [examples](../examples/README.md) folder.

package/docs/{plugins/DEVELOPMENT.md → plugin-development/README.md}

@@ -205,15 +205,10 @@ Create a standalone file anywhere on your system, e.g., `/opt/custom-plugins/my-
  */
 import type { Express, Request, Response } from 'express';
 
-// Import from ldap-rest (if installed as npm package)
-// import DmPlugin, { asyncHandler } from 'ldap-rest/plugin';
-
-// Or use relative path to node_modules
-import DmPlugin from './node_modules/ldap-rest/dist/abstract/plugin.js';
-import type { DM } from './node_modules/ldap-rest/dist/bin/index.js';
-import type { Hooks } from './node_modules/ldap-rest/dist/hooks.js';
-// Import asyncHandler for error handling
-import { asyncHandler } from './node_modules/ldap-rest/dist/lib/utils.js';
+// Import from ldap-rest
+import DmPlugin, { asyncHandler } from 'ldap-rest/plugin';
+import type { DM } from 'ldap-rest';
+import type { Hooks } from 'ldap-rest/hooks';
 
 export default class ExternalAuditPlugin extends DmPlugin {
   name = 'externalAudit';

package/docs/plugin-development/hooks.md

@@ -0,0 +1,18 @@
+# Core hooks
+
+Set here the documentation of all hooks.
+
+Typescript definitions into [hooks.ts](./src/hooks.ts)
+
+## Demo hooks
+
+- **hello**: called by [helloworld demo plugin](./src/plugins/helloworld.ts)
+
+## [LDAP](./src/lib/ldapActions.ts) hooks
+
+- **ldapopts**: called before any ldapsearch to modify search options
+- **ldapsearchresult**: called after any ldapsearch to modify search result
+- **ldapaddrequest**: called before any ldapadd
+- **ldapmodifyrequest**: called before any ldapmodify
+- **ldapdeleterequest**: called before any ldapdelete
+- **ldaprenamerequest**: called before any ldap rename/modifyDN operation

package/docs/usage/README.md

@@ -0,0 +1,89 @@
+# Usage - Getting Started
+
+Getting started and usage guide for LDAP-Rest.
+
+## Installation
+
+```bash
+npm install ldap-rest
+```
+
+## Quick Start
+
+### Minimal Configuration
+
+```bash
+ldap-rest \
+  --plugin core/ldap/flatGeneric \
+  --ldap-url ldap://localhost:389 \
+  --ldap-dn "cn=admin,dc=example,dc=com" \
+  --ldap-pwd "password" \
+  --ldap-base "dc=example,dc=com" \
+  --ldap-flat-schema ./schemas/standard/users.json
+```
+
+### With Authentication
+
+```bash
+ldap-rest \
+  --plugin core/auth/token \
+  --plugin core/ldap/flatGeneric \
+  --auth-token "secret-token" \
+  --ldap-flat-schema ./schemas/standard/users.json \
+  ...
+```
+
+### Complete Configuration
+
+```bash
+ldap-rest \
+  --plugin core/auth/token \
+  --plugin core/ldap/flatGeneric \
+  --plugin core/ldap/groups \
+  --plugin core/ldap/organization \
+  --plugin core/ldap/bulkImport \
+  --plugin core/ldap/externalUsersInGroups \
+  --plugin core/static \
+  --plugin core/weblogs \
+  --ldap-flat-schema ./schemas/standard/users.json \
+  --bulk-import-schemas "users:./schemas/standard/users.json" \
+  --auth-token "admin-token" \
+  --static-path ./static \
+  ...
+```
+
+## LDAP Connection
+
+### Single URL
+
+```bash
+--ldap-url ldap://localhost:389
+```
+
+### Failover (High Availability)
+
+```bash
+--ldap-url ldap://ldap1.example.com,ldap://ldap2.example.com,ldap://ldap3.example.com
+```
+
+The system will:
+
+1. Try each URL in order
+2. Use the first successful connection
+3. Automatically failover on connection failure
+
+## Log Levels
+
+```bash
+--log-level error   # Errors only
+--log-level warn    # Warnings and errors
+--log-level notice  # Web access logs (recommended for production)
+--log-level info    # General information
+--log-level debug   # Everything, including debug output
+```
+
+## Next Steps
+
+- **[Configuration](configuration.md)** - CLI options and environment variables
+- **[Plugins](plugins/README.md)** - Choose and configure plugins
+- **[Troubleshooting](troubleshooting.md)** - Problem resolution