opensecureconf-client 2.2.0 → 2.2.1

package/README.md

@@ -1,297 +1,511 @@
-# OpenSecureConf JavaScript/TypeScript Client
-
-JavaScript/TypeScript client library for [OpenSecureConf](https://github.com/yourusername/OpenSecureConf) - A secure, encrypted configuration management system with REST API.
+# OpenSecureConf TypeScript/JavaScript Client
 
 [![npm version](https://badge.fury.io/js/opensecureconf-client.svg)](https://www.npmjs.com/package/opensecureconf-client)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+A comprehensive TypeScript/JavaScript client library for OpenSecureConf - Encrypted configuration management with cluster support and HTTPS/SSL.
 
-## Features
+## 🚀 Features
 
-- 🔐 **Encrypted Configuration Management** - Create, read, update, and delete encrypted configurations
-- 🌐 **REST API Client** - Full-featured client for OpenSecureConf REST API
-- 📦 **TypeScript Support** - Written in TypeScript with full type definitions
-- 🔄 **Cluster Support** - Works with both REPLICA and FEDERATED cluster modes
+- ✅ **Full TypeScript Support** - Complete type definitions
+- 🔒 **HTTPS/SSL Support** - Production-ready with TLS
+- 🔐 **Self-Signed Certificates** - Option for development environments
+- 📦 **Batch Operations** - Bulk create, read, delete
+- 🌐 **Cluster Support** - Status and health check methods
 - ⚡ **Async/Await** - Modern promise-based API
-- 🛡️ **Error Handling** - Comprehensive error handling with custom error types
-- ⏱️ **Timeout Control** - Configurable request timeouts
-- 🧪 **Well Tested** - Comprehensive test suite with Jest
+- 🛡️ **Type-Safe** - Full TypeScript definitions
+- 🌍 **Universal** - Works in Node.js and browsers
+- 🔄 **Auto-Retry** - Built-in timeout and error handling
+- 📊 **Metrics** - Prometheus metrics support
 
-## Installation
+## 📦 Installation
 
+### NPM
 ```bash
 npm install opensecureconf-client
 ```
 
-## Quick Start
+### Yarn
+```bash
+yarn add opensecureconf-client
+```
 
-### JavaScript (CommonJS)
+### PNPM
+```bash
+pnpm add opensecureconf-client
+```
 
-```javascript
-const { OpenSecureConfClient } = require('opensecureconf-client');
+## 🎯 Quick Start
+
+### Basic HTTP Usage
+
+```typescript
+import OpenSecureConfClient from 'opensecureconf-client';
 
 const client = new OpenSecureConfClient({
   baseUrl: 'http://localhost:9000',
-  userKey: 'my-secure-encryption-key',
-  apiKey: 'your-api-key', // Optional
+  userKey: 'my-secret-key-12345',
+  apiKey: 'optional-api-key', // Optional
 });
 
-// Create a configuration
-await client.create('my-config', { setting: 'value' }, 'category');
+// Create configuration
+const config = await client.create('database', {
+  host: 'localhost',
+  port: 5432,
+  username: 'admin',
+});
 
-// Read a configuration
-const config = await client.read('my-config');
-console.log(config.value); // { setting: 'value' }
+// Read configuration
+const retrieved = await client.read('database');
+console.log(retrieved.value); // { host: 'localhost', port: 5432, ... }
+
+// Update configuration
+await client.update('database', {
+  host: 'db.example.com',
+  port: 5432,
+});
+
+// Delete configuration
+await client.delete('database');
 ```
 
-### TypeScript (ES Modules)
+### HTTPS with Valid Certificate (Production)
 
 ```typescript
-import OpenSecureConfClient from 'opensecureconf-client';
+const client = new OpenSecureConfClient({
+  baseUrl: 'https://config.example.com',
+  userKey: 'my-secret-key-12345',
+  apiKey: 'production-api-key',
+  timeout: 60000, // 60 seconds
+});
+
+// All operations work the same
+const config = await client.create('api_keys', {
+  stripe: 'sk_live_xxx',
+  aws: 'AKIA_xxx',
+});
+```
+
+### HTTPS with Self-Signed Certificate (Development)
 
+```typescript
 const client = new OpenSecureConfClient({
-  baseUrl: 'http://localhost:9000',
-  userKey: 'my-secure-encryption-key',
+  baseUrl: 'https://localhost:9443',
+  userKey: 'my-secret-key-12345',
+  rejectUnauthorized: false, // ⚠️ Accept self-signed certs (dev only!)
 });
 
-const config = await client.read('my-config');
+// Works with self-signed certificates
+const info = await client.getInfo();
+console.log(info.service); // OpenSecureConf API
 ```
 
-## API Reference
+## 📖 API Reference
+
+### Constructor Options
+
+```typescript
+interface OpenSecureConfOptions {
+  baseUrl: string;              // API server URL (http:// or https://)
+  userKey: string;              // Encryption key (min 8 chars)
+  apiKey?: string;              // Optional API key for authentication
+  timeout?: number;             // Request timeout in ms (default: 30000)
+  rejectUnauthorized?: boolean; // Reject invalid SSL certs (default: true)
+}
+```
 
 ### Methods
 
-- `create(key, value, category?)` - Create new configuration
-- `read(key)` - Read configuration by key
-- `update(key, value, category?)` - Update configuration
-- `delete(key)` - Delete configuration
-- `list(category?)` - List all configurations
-- `getClusterStatus()` - Get cluster status
-- `healthCheck()` - Perform health check
-- `getMetrics()` - Get Prometheus metrics
-- `getInfo()` - Get API information
+#### Configuration Operations
 
-## Error Handling
+```typescript
+// Create
+await client.create(
+  key: string,
+  value: Record<string, any>,
+  category?: string
+): Promise<ConfigEntry>
+
+// Read
+await client.read(key: string): Promise<ConfigEntry>
+
+// Update
+await client.update(
+  key: string,
+  value: Record<string, any>,
+  category?: string
+): Promise<ConfigEntry>
+
+// Delete
+await client.delete(key: string): Promise<{ message: string }>
+
+// List
+await client.list(category?: string): Promise<ConfigEntry[]>
+
+// Check existence
+await client.exists(key: string): Promise<boolean>
+
+// Count
+await client.count(category?: string): Promise<number>
+```
+
+#### Batch Operations
 
 ```typescript
-import { OpenSecureConfError } from 'opensecureconf-client';
+// Bulk create
+await client.bulkCreate(
+  configs: Array<{ key: string; value: Record<string, any>; category?: string }>,
+  ignoreErrors?: boolean
+): Promise<ConfigEntry[]>
+
+// Bulk read
+await client.bulkRead(
+  keys: string[],
+  ignoreErrors?: boolean
+): Promise<ConfigEntry[]>
+
+// Bulk delete
+await client.bulkDelete(
+  keys: string[],
+  ignoreErrors?: boolean
+): Promise<{ deleted: string[]; failed: Array<{ key: string; error: any }> }>
+```
 
-try {
-  await client.read('non-existent-key');
-} catch (error) {
-  if (error instanceof OpenSecureConfError) {
-    console.error(`Error ${error.statusCode}: ${error.message}`);
-  }
-}
+#### Cluster & Health
+
+```typescript
+// Get service info
+await client.getInfo(): Promise<Record<string, any>>
+
+// Cluster status
+await client.getClusterStatus(): Promise<ClusterStatus>
+
+// Health check
+await client.healthCheck(): Promise<{ status: string; node_id: string }>
+
+// Get metrics
+await client.getMetrics(): Promise<string>
 ```
 
-## Development
+## 🔒 HTTPS/SSL Configuration
 
-```bash
-npm install          # Install dependencies
-npm run build        # Build for production
-npm test             # Run tests
-npm run lint         # Lint code
+### Production (Valid Certificates)
+
+For production environments with valid SSL certificates from Let's Encrypt or a trusted CA:
+
+```typescript
+const client = new OpenSecureConfClient({
+  baseUrl: 'https://config.example.com',
+  userKey: 'my-secret-key-12345',
+  apiKey: 'production-api-key',
+  // rejectUnauthorized: true (default)
+});
 ```
 
-## License
+### Development (Self-Signed Certificates)
 
-MIT © OpenSecureConf Contributors
-"
-tests/client.test.ts,"import { OpenSecureConfClient, OpenSecureConfError } from '../src/index';
+For development with self-signed certificates:
 
-describe('OpenSecureConfClient', () => {
-  let client: OpenSecureConfClient;
+```typescript
+const client = new OpenSecureConfClient({
+  baseUrl: 'https://localhost:9443',
+  userKey: 'my-secret-key-12345',
+  rejectUnauthorized: false, // ⚠️ Only for development!
+});
+```
 
-  beforeEach(() => {
-    client = new OpenSecureConfClient({
-      baseUrl: 'http://localhost:9000',
-      userKey: 'test-user-key-12345',
-      apiKey: 'your-super-secret-api-key-here',
-    });
-  });
+**⚠️ Security Warning**: Never use `rejectUnauthorized: false` in production! This disables SSL certificate validation and makes your connection vulnerable to man-in-the-middle attacks.
 
-  describe('constructor', () => {
-    it('should create client with valid options', () => {
-      expect(client).toBeInstanceOf(OpenSecureConfClient);
-    });
+### Node.js HTTPS Agent
 
-    it('should throw error if userKey is too short', () => {
-      expect(() => {
-        new OpenSecureConfClient({
-          baseUrl: 'http://localhost:9000',
-          userKey: 'short',
-        });
-      }).toThrow('userKey must be at least 8 characters long');
-    });
-  });
+When running in Node.js, the client automatically creates an HTTPS agent with the appropriate SSL settings:
 
-  describe('CRUD operations', () => {
-    const testKey = 'test-config-key';
-    const testValue = { setting: 'value', number: 42 };
+```typescript
+// In Node.js, HTTPS agent is automatically configured
+const client = new OpenSecureConfClient({
+  baseUrl: 'https://localhost:9443',
+  userKey: 'my-secret-key-12345',
+  rejectUnauthorized: false,
+});
 
-    it('should create a configuration', async () => {
-      const result = await client.create(testKey, testValue, 'test-category');
-      expect(result).toHaveProperty('key', testKey);
-      expect(result).toHaveProperty('value');
-    });
+// Agent is used for all HTTPS requests automatically
+await client.getInfo();
+```
 
-    it('should read a configuration', async () => {
-      const result = await client.read(testKey);
-      expect(result).toHaveProperty('key', testKey);
-    });
+### Browser Usage
 
-    it('should list configurations', async () => {
-      const result = await client.list();
-      expect(Array.isArray(result)).toBe(true);
-    });
+In browser environments, the native `fetch` API handles HTTPS automatically. Certificate validation follows browser security policies:
 
-    it('should delete a configuration', async () => {
-      const result = await client.delete(testKey);
-      expect(result).toHaveProperty('message');
-    });
-  });
+```typescript
+// Works in browsers with valid certificates
+const client = new OpenSecureConfClient({
+  baseUrl: 'https://config.example.com',
+  userKey: 'my-secret-key-12345',
 });
-"
-examples/basic-usage.js,"/**
- * Basic usage example for OpenSecureConf JavaScript Client
- */
+```
+
+## 📚 Usage Examples
 
-const { OpenSecureConfClient } = require('opensecureconf-client');
+### Complete Workflow
 
-async function main() {
-  // Initialize the client
+```typescript
+import OpenSecureConfClient, { OpenSecureConfError } from 'opensecureconf-client';
+
+async function workflow() {
   const client = new OpenSecureConfClient({
-    baseUrl: 'http://localhost:9000',
+    baseUrl: 'https://localhost:9443',
     userKey: 'my-secure-encryption-key',
-    apiKey: 'your-super-secret-api-key-here', // Optional
+    apiKey: 'workflow-api-key',
+    rejectUnauthorized: false,
   });
 
   try {
-    // Create a new configuration
-    const created = await client.create(
-      'database-config',
-      {
-        host: 'localhost',
-        port: 5432,
-        database: 'myapp',
-        ssl: true,
-      },
-      'database'
-    );
-    console.log('Created:', created);
-
-    // Read a configuration
-    const config = await client.read('database-config');
-    console.log('Read:', config);
-
-    // List all configurations
-    const all = await client.list();
-    console.log('All configs:', all.length);
-
-    // Delete a configuration
-    await client.delete('database-config');
-    console.log('Deleted successfully');
+    // 1. Health check
+    const health = await client.healthCheck();
+    console.log(`Status: ${health.status}`);
+
+    // 2. Create configurations
+    await client.create('database', {
+      host: 'postgres.local',
+      port: 5432,
+    });
+
+    // 3. Batch create
+    await client.bulkCreate([
+      { key: 'redis', value: { host: 'redis.local', port: 6379 } },
+      { key: 'cache', value: { ttl: 3600, maxSize: 1000 } },
+    ], true);
+
+    // 4. List all
+    const configs = await client.list();
+    console.log(`Total: ${configs.length} configurations`);
+
+    // 5. Update
+    await client.update('database', {
+      host: 'postgres.local',
+      port: 5432,
+      ssl: true,
+    });
+
+    // 6. Cleanup
+    await client.bulkDelete(['database', 'redis', 'cache'], true);
 
   } catch (error) {
-    if (error.name === 'OpenSecureConfError') {
-      console.error('API Error:', error.statusCode, error.message);
-    } else {
-      console.error('Error:', error);
+    if (error instanceof OpenSecureConfError) {
+      console.error(`Error ${error.statusCode}: ${error.message}`);
     }
   }
 }
+```
+
+### Error Handling
+
+```typescript
+try {
+  const config = await client.read('nonexistent');
+} catch (error) {
+  if (error instanceof OpenSecureConfError) {
+    switch (error.statusCode) {
+      case 401:
+        console.error('Authentication failed');
+        break;
+      case 404:
+        console.error('Configuration not found');
+        break;
+      case 408:
+        console.error('Request timeout');
+        break;
+      default:
+        console.error(`API error: ${error.message}`);
+    }
+  }
+}
+```
 
-main();
-"
-examples/advanced-usage.ts,"/**
- * Advanced usage example with TypeScript
- */
+### Cluster Operations
 
+```typescript
+// Check cluster status
+const status = await client.getClusterStatus();
+if (status.enabled) {
+  console.log(`Mode: ${status.mode}`);
+  console.log(`Nodes: ${status.healthy_nodes}/${status.total_nodes}`);
+}
+
+// Get Prometheus metrics
+const metrics = await client.getMetrics();
+console.log(metrics);
+```
+
+## 🛠️ Advanced Usage
+
+### Custom Timeout
+
+```typescript
+const client = new OpenSecureConfClient({
+  baseUrl: 'https://config.example.com',
+  userKey: 'my-secret-key-12345',
+  timeout: 5000, // 5 seconds
+});
+```
+
+### Category Filtering
+
+```typescript
+// Create with category
+await client.create('db', { host: 'localhost' }, 'production');
+await client.create('cache', { ttl: 3600 }, 'production');
+
+// List by category
+const prodConfigs = await client.list('production');
+console.log(prodConfigs); // Only production configs
+
+// Count by category
+const count = await client.count('production');
+console.log(`Production configs: ${count}`);
+```
+
+### Batch Operations with Error Handling
+
+```typescript
+const result = await client.bulkDelete(
+  ['config1', 'config2', 'config3'],
+  true // ignoreErrors
+);
+
+console.log(`Deleted: ${result.deleted.length}`);
+console.log(`Failed: ${result.failed.length}`);
+
+for (const failure of result.failed) {
+  console.error(`Failed to delete ${failure.key}: ${failure.error}`);
+}
+```
+
+## 🔍 TypeScript Support
+
+Full TypeScript definitions included:
+
+```typescript
 import OpenSecureConfClient, {
+  OpenSecureConfOptions,
   ConfigEntry,
+  ClusterStatus,
   OpenSecureConfError,
 } from 'opensecureconf-client';
 
-interface DatabaseConfig {
-  host: string;
-  port: number;
-  database: string;
-  ssl: boolean;
-}
+// All types are fully typed
+const options: OpenSecureConfOptions = {
+  baseUrl: 'https://localhost:9443',
+  userKey: 'my-key',
+  rejectUnauthorized: false,
+};
 
-class ConfigManager {
-  private client: OpenSecureConfClient;
+const client = new OpenSecureConfClient(options);
 
-  constructor(baseUrl: string, userKey: string, apiKey?: string) {
-    this.client = new OpenSecureConfClient({
-      baseUrl,
-      userKey,
-      apiKey,
-    });
-  }
+// Return types are inferred
+const config: ConfigEntry = await client.read('key');
+const status: ClusterStatus = await client.getClusterStatus();
+```
 
-  async getDatabaseConfig(key: string): Promise<DatabaseConfig> {
-    const config = await this.client.read(key);
-    return config.value as DatabaseConfig;
-  }
+## 🔐 Security Best Practices
 
-  async setDatabaseConfig(key: string, config: DatabaseConfig): Promise<void> {
-    await this.client.create(key, config as Record<string, any>, 'database');
-  }
+### ✅ Do's
 
-  async withRetry<T>(
-    operation: () => Promise<T>,
-    maxRetries: number = 3
-  ): Promise<T> {
-    let lastError: Error | undefined;
-
-    for (let i = 0; i < maxRetries; i++) {
-      try {
-        return await operation();
-      } catch (error) {
-        lastError = error as Error;
-
-        if (error instanceof OpenSecureConfError) {
-          if (error.statusCode >= 400 && error.statusCode < 500) {
-            throw error;
-          }
-        }
-
-        if (i < maxRetries - 1) {
-          await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
-        }
-      }
-    }
+- Use HTTPS in production (`https://`)
+- Use valid SSL certificates (Let's Encrypt, trusted CA)
+- Set strong user keys (16+ characters)
+- Enable API key authentication
+- Use environment variables for secrets
+- Set appropriate timeouts
 
-    throw lastError;
-  }
-}
+### ❌ Don'ts
 
-async function main() {
-  const manager = new ConfigManager(
-    'http://localhost:9000',
-    'my-secure-encryption-key',
-    'your-super-secret-api-key-here'
-  );
+- **Never** use `rejectUnauthorized: false` in production
+- **Never** hardcode credentials in source code
+- **Never** commit secrets to version control
+- **Never** use short encryption keys (<8 chars)
+- **Never** expose API endpoints without authentication
 
-  try {
-    await manager.setDatabaseConfig('prod-db', {
-      host: 'db.example.com',
-      port: 5432,
-      database: 'production',
-      ssl: true,
-    });
+### Environment Variables
 
-    const dbConfig = await manager.getDatabaseConfig('prod-db');
-    console.log('Database config:', dbConfig);
+```typescript
+const client = new OpenSecureConfClient({
+  baseUrl: process.env.OSC_BASE_URL!,
+  userKey: process.env.OSC_USER_KEY!,
+  apiKey: process.env.OSC_API_KEY,
+  rejectUnauthorized: process.env.NODE_ENV === 'production',
+});
+```
 
-  } catch (error) {
-    if (error instanceof OpenSecureConfError) {
-      console.error(`API Error [${error.statusCode}]:`, error.detail);
-    } else {
-      console.error('Error:', error);
-    }
-  }
-}
+## 🌍 Browser vs Node.js
+
+### Node.js
+
+```typescript
+// Automatic HTTPS agent setup
+// Supports rejectUnauthorized option
+// Full control over SSL/TLS
+```
+
+### Browser
+
+```typescript
+// Uses native fetch API
+// SSL validation by browser
+// rejectUnauthorized ignored (browser controls SSL)
+// Works with CORS-enabled servers
+```
+
+## 📊 Error Codes
+
+| Status Code | Error Type | Description |
+|-------------|------------|-------------|
+| 0 | Network Error | Connection failed |
+| 400 | Bad Request | Invalid parameters |
+| 401 | Authentication | Invalid user key |
+| 403 | Forbidden | Invalid API key |
+| 404 | Not Found | Configuration not found |
+| 408 | Timeout | Request timeout |
+| 429 | Rate Limit | Too many requests |
+| 500+ | Server Error | Internal server error |
+
+## 🔗 Links
+
+- **GitHub**: [OpenSecureConf](https://github.com/lordraw77/OpenSecureConf)
+- **Docker Hub**: [lordraw/open-secureconfiguration](https://hub.docker.com/r/lordraw/open-secureconfiguration)
+- **PyPI Client**: [opensecureconf-client](https://pypi.org/project/opensecureconf-client/)
+- **Documentation**: [GitHub README](https://github.com/lordraw77/OpenSecureConf/blob/main/README.md)
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE)
+
+## 🙏 Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## 📝 Changelog
+
+### v1.1.0
+- ✨ Added HTTPS/SSL support
+- ✨ Added `rejectUnauthorized` option
+- ✨ Auto HTTPS agent for Node.js
+- ✨ Batch operations (bulkCreate, bulkRead, bulkDelete)
+- ✨ Utility methods (exists, count)
+- 🐛 Enhanced SSL error messages
+- 📚 Improved documentation
+
+### v1.0.0
+- 🎉 Initial release
+- ✅ Basic CRUD operations
+- ✅ Cluster support
+- ✅ TypeScript definitions
+
+---
+
+**OpenSecureConf TypeScript Client** - Secure configuration management made simple.
 
-main();
+**Version**: 2.2.1  
+**Author**: lordraw77  
+**Support**: [GitHub Issues](https://github.com/lordraw77/OpenSecureConf/issues)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opensecureconf-client",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "JavaScript/TypeScript client for OpenSecureConf - Encrypted configuration management REST API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",