opensecureconf-client 1.0.2__py3-none-any.whl → 2.0.2__py3-none-any.whl

opensecureconf_client-2.0.2.dist-info/METADATA

@@ -0,0 +1,1289 @@
+Metadata-Version: 2.4
+Name: opensecureconf-client
+Version: 2.0.2
+Summary: Python client library for OpenSecureConf encrypted configuration management API with clustering support
+Author-email: Alessandro Pioli <alessandro.pioli+apioli-pypi@gmail.com>
+Maintainer-email: Alessandro Pioli <alessandro.pioli+apioli-pypi@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/lordraw77/OpenSecureConf
+Project-URL: Documentation, https://github.com/lordraw77/OpenSecureConf/blob/main/client/README.md
+Project-URL: Repository, https://github.com/lordraw77/OpenSecureConf/tree/main/client
+Project-URL: Issues, https://github.com/lordraw77/OpenSecureConf/issues
+Keywords: configuration,encryption,api-client,secure,config-management,clustering,distributed-config,secrets-management
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: urllib3>=1.26.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pylint>=2.17.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Provides-Extra: enhanced
+Requires-Dist: urllib3>=2.0.0; extra == "enhanced"
+Dynamic: license-file
+
+# OpenSecureConf Python Client
+
+[![PyPI version](https://badge.fury.io/py/opensecureconf-client.svg)](https://badge.fury.io/py/opensecureconf-client)
+[![Python](https://img.shields.io/pypi/pyversions/opensecureconf-client.svg)](https://pypi.org/project/opensecureconf-client/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A powerful Python client library for interacting with the [OpenSecureConf API](https://github.com/lordraw77/OpenSecureConf), providing encrypted configuration management with clustering support, automatic retry logic, and comprehensive monitoring capabilities.
+
+## 📋 Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Features](#core-features)
+  - [Basic CRUD Operations](#basic-crud-operations)
+  - [Cluster Awareness](#cluster-awareness)
+  - [Batch Operations](#batch-operations)
+  - [Retry Logic](#retry-logic)
+  - [Health Checks](#health-checks)
+  - [Utility Methods](#utility-methods)
+- [Advanced Usage](#advanced-usage)
+- [API Reference](#api-reference)
+- [Error Handling](#error-handling)
+- [Configuration Options](#configuration-options)
+- [Best Practices](#best-practices)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## ✨ Features
+
+### Core Capabilities
+- 🔐 **Encrypted Configuration Management**: Securely store and retrieve encrypted configurations using PBKDF2 + Fernet
+- 🚀 **Simple & Intuitive API**: Clean interface for CRUD operations
+- 🛡️ **Type-Safe**: Fully typed with comprehensive error handling
+- 📦 **Lightweight**: Minimal dependencies (only `requests` and `urllib3`)
+
+### Enhanced Features
+- 🔄 **Automatic Retry Logic**: Exponential backoff for transient failures
+- 🌐 **Cluster Awareness**: Monitor and interact with clustered deployments
+- ⚡ **Connection Pooling**: Optimized HTTP connection management
+- 📊 **Structured Logging**: Built-in logging for debugging and monitoring
+- 🔢 **Batch Operations**: Efficient bulk create, read, and delete operations
+- 🏥 **Health Checks**: Built-in connectivity and cluster health monitoring
+- 🎯 **Utility Methods**: Convenient helpers for common operations
+- 🔌 **Context Manager**: Automatic resource cleanup
+
+## 📦 Installation
+
+### Standard Installation
+
+```bash
+pip install opensecureconf-client
+```
+
+### Development Installation
+
+```bash
+pip install opensecureconf-client[dev]
+```
+
+### From Source
+
+```bash
+git clone https://github.com/lordraw77/OpenSecureConf.git
+cd OpenSecureConf/client
+pip install -e .
+```
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```python
+from opensecureconf_client import OpenSecureConfClient
+
+# Initialize the client
+client = OpenSecureConfClient(
+    base_url="http://localhost:9000",
+    user_key="my-secure-key-min-8-chars",
+    api_key="cluster-secret-key-123"  # Optional: if API key authentication is enabled
+)
+
+# Create a configuration
+config = client.create(
+    key="database",
+    value={"host": "localhost", "port": 5432, "username": "admin", "password": "secret"},
+    category="production"
+)
+print(f"Created: {config['key']}")
+
+# Read a configuration
+db_config = client.read("database")
+print(f"Host: {db_config['value']['host']}")
+
+# Update a configuration
+updated = client.update(
+    key="database",
+    value={"host": "db.example.com", "port": 5432, "username": "admin", "password": "secret"}
+)
+
+# List all configurations
+configs = client.list_all(category="production")
+for cfg in configs:
+    print(f"- {cfg['key']}: {cfg['category']}")
+
+# Delete a configuration
+client.delete("database")
+
+# Close the client
+client.close()
+```
+
+### Using Context Manager (Recommended)
+
+```python
+from opensecureconf_client import OpenSecureConfClient
+
+with OpenSecureConfClient(
+    base_url="http://localhost:9000",
+    user_key="my-secure-key-min-8-chars"
+) as client:
+    # Create and use configurations
+    config = client.create("app", {"version": "1.0.0", "debug": False})
+    print(config)
+    # Session automatically closed when exiting context
+```
+
+### Enhanced Client with All Features
+
+```python
+from opensecureconf_client_enhanced import OpenSecureConfClient
+
+# Initialize with advanced features
+client = OpenSecureConfClient(
+    base_url="http://localhost:9000",
+    user_key="my-secure-key-min-8-chars",
+    api_key="cluster-secret-key-123",
+    enable_retry=True,          # Enable automatic retry
+    max_retries=3,              # Max retry attempts
+    backoff_factor=1.0,         # Exponential backoff factor
+    pool_connections=20,        # Connection pool size
+    pool_maxsize=50,            # Max pool size
+    log_level="INFO"            # Logging level
+)
+
+# Use all the enhanced features...
+```
+
+## 🎯 Core Features
+
+### Basic CRUD Operations
+
+#### Create Configuration
+
+```python
+# Create a simple configuration
+config = client.create(
+    key="api_settings",
+    value={"base_url": "https://api.example.com", "timeout": 30, "retries": 3},
+    category="production"
+)
+
+# Create with validation
+if not client.exists("api_settings"):
+    config = client.create("api_settings", {"base_url": "https://api.example.com"})
+```
+
+#### Read Configuration
+
+```python
+# Read a specific configuration
+config = client.read("api_settings")
+print(f"API URL: {config['value']['base_url']}")
+
+# Safe read with default value
+config = client.get_or_default(
+    "optional_setting",
+    default={"enabled": False, "timeout": 30}
+)
+```
+
+#### Update Configuration
+
+```python
+# Update existing configuration
+updated = client.update(
+    key="api_settings",
+    value={"base_url": "https://api.example.com", "timeout": 60, "retries": 5},
+    category="production"
+)
+```
+
+#### Delete Configuration
+
+```python
+# Delete a single configuration
+result = client.delete("api_settings")
+print(result["message"])
+
+# Conditional delete
+if client.exists("temporary_config"):
+    client.delete("temporary_config")
+```
+
+#### List Configurations
+
+```python
+# List all configurations
+all_configs = client.list_all()
+print(f"Total configurations: {len(all_configs)}")
+
+# List by category
+prod_configs = client.list_all(category="production")
+for config in prod_configs:
+    print(f"- {config['key']}: {config['value']}")
+
+# Get count
+total = client.count()
+prod_count = client.count(category="production")
+print(f"Production configs: {prod_count}/{total}")
+```
+
+### Cluster Awareness
+
+Monitor and interact with OpenSecureConf clusters:
+
+```python
+# Check cluster status
+status = client.get_cluster_status()
+if status['enabled']:
+    print(f"Cluster Mode: {status['mode']}")  # REPLICA or FEDERATED
+    print(f"Node ID: {status['node_id']}")
+    print(f"Healthy Nodes: {status['healthy_nodes']}/{status['total_nodes']}")
+else:
+    print("Clustering is disabled")
+
+# Check node health
+health = client.get_cluster_health()
+print(f"Node Status: {health['status']}")
+```
+
+**Cluster Modes:**
+- **REPLICA**: Active-active replication with automatic synchronization
+- **FEDERATED**: Distributed storage with cross-node queries
+
+### Batch Operations
+
+Perform multiple operations efficiently:
+
+#### Bulk Create
+
+```python
+# Create multiple configurations at once
+configs_to_create = [
+    {
+        "key": "service1",
+        "value": {"url": "http://service1.local", "timeout": 30},
+        "category": "microservices"
+    },
+    {
+        "key": "service2",
+        "value": {"url": "http://service2.local", "timeout": 60},
+        "category": "microservices"
+    },
+    {
+        "key": "service3",
+        "value": {"url": "http://service3.local", "timeout": 45},
+        "category": "microservices"
+    }
+]
+
+# Create all configurations (stop on first error)
+results = client.bulk_create(configs_to_create)
+print(f"Created {len(results)} configurations")
+
+# Create all configurations (continue on errors)
+results = client.bulk_create(configs_to_create, ignore_errors=True)
+print(f"Created {len(results)} configurations")
+```
+
+#### Bulk Read
+
+```python
+# Read multiple configurations at once
+keys = ["service1", "service2", "service3", "api_settings"]
+
+# Read all (stop on first error)
+configs = client.bulk_read(keys)
+
+# Read all (skip missing keys)
+configs = client.bulk_read(keys, ignore_errors=True)
+for config in configs:
+    print(f"{config['key']}: {config['value']['url']}")
+```
+
+#### Bulk Delete
+
+```python
+# Delete multiple configurations
+keys_to_delete = ["temp1", "temp2", "temp3"]
+
+# Delete all (stop on first error)
+result = client.bulk_delete(keys_to_delete)
+
+# Delete all (continue on errors)
+result = client.bulk_delete(keys_to_delete, ignore_errors=True)
+print(f"Deleted: {len(result['deleted'])}")
+print(f"Failed: {len(result['failed'])}")
+
+# Inspect failures
+for failure in result['failed']:
+    print(f"Failed to delete '{failure['key']}': {failure['error']}")
+```
+
+### Retry Logic
+
+The enhanced client includes automatic retry with exponential backoff:
+
+```python
+# Configure retry behavior
+client = OpenSecureConfClient(
+    base_url="http://localhost:9000",
+    user_key="my-key",
+    enable_retry=True,
+    max_retries=5,              # Retry up to 5 times
+    backoff_factor=2.0,         # 2^n seconds between retries
+    timeout=30
+)
+
+# Automatic retry on transient failures (429, 500, 502, 503, 504)
+try:
+    config = client.read("my_config")
+except Exception as e:
+    print(f"Failed after {client.max_retries} retries: {e}")
+```
+
+**Retry Strategy:**
+- Status codes: `429, 500, 502, 503, 504`
+- HTTP methods: All methods including POST
+- Backoff: `backoff_factor * (2 ^ retry_count)` seconds
+
+### Health Checks
+
+Built-in health monitoring:
+
+```python
+# Simple ping check
+if client.ping():
+    print("✓ Server is healthy and reachable")
+else:
+    print("✗ Server is not reachable")
+
+# Get detailed service information
+info = client.get_service_info()
+print(f"Service: {info['service']}")
+print(f"Version: {info['version']}")
+print(f"Features: {', '.join(info['features'])}")
+print(f"Cluster Enabled: {info['cluster_enabled']}")
+
+# Monitor cluster health
+if info['cluster_enabled']:
+    health = client.get_cluster_health()
+    print(f"Cluster Health: {health['status']}")
+```
+
+### Utility Methods
+
+Convenient helper methods:
+
+#### Check Existence
+
+```python
+# Check if a key exists
+if client.exists("database"):
+    print("Configuration exists")
+    config = client.read("database")
+else:
+    print("Configuration does not exist")
+    config = client.create("database", {"host": "localhost"})
+```
+
+#### Get with Default
+
+```python
+# Get configuration or return default
+config = client.get_or_default(
+    "optional_feature",
+    default={"enabled": False, "timeout": 30}
+)
+
+# Use the configuration
+if config['value']['enabled']:
+    timeout = config['value']['timeout']
+```
+
+#### Count Configurations
+
+```python
+# Count all configurations
+total = client.count()
+print(f"Total configurations: {total}")
+
+# Count by category
+prod_count = client.count(category="production")
+dev_count = client.count(category="development")
+print(f"Production: {prod_count}, Development: {dev_count}")
+```
+
+#### List Categories
+
+```python
+# Get all unique categories
+categories = client.list_categories()
+print(f"Available categories: {', '.join(categories)}")
+
+# Process by category
+for category in categories:
+    count = client.count(category=category)
+    print(f"{category}: {count} configurations")
+```
+
+## 🔧 Advanced Usage
+
+### Custom Connection Pooling
+
+```python
+from opensecureconf_client_enhanced import OpenSecureConfClient
+
+# Configure connection pooling for high-traffic scenarios
+client = OpenSecureConfClient(
+    base_url="http://localhost:9000",
+    user_key="my-key",
+    pool_connections=50,    # Number of connection pools
+    pool_maxsize=100,       # Maximum pool size
+    timeout=60              # Request timeout
+)
+```
+
+### Structured Logging
+
+```python
+import logging
+
+# Enable detailed logging
+logging.basicConfig(
+    level=logging.DEBUG,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+
+client = OpenSecureConfClient(
+    base_url="http://localhost:9000",
+    user_key="my-key",
+    log_level="DEBUG"  # DEBUG, INFO, WARNING, ERROR
+)
+
+# All operations will be logged
+config = client.create("test", {"data": "value"})
+# Output: 2026-01-14 17:00:00 - opensecureconf_client - INFO - POST /configs - Status: 201 - Duration: 0.045s
+```
+
+### SSL Configuration
+
+```python
+# Disable SSL verification (not recommended for production)
+client = OpenSecureConfClient(
+    base_url="https://localhost:9000",
+    user_key="my-key",
+    verify_ssl=False
+)
+
+# Use custom SSL certificate
+import requests
+session = requests.Session()
+session.verify = '/path/to/ca-bundle.crt'
+
+client = OpenSecureConfClient(
+    base_url="https://localhost:9000",
+    user_key="my-key",
+    verify_ssl=True
+)
+client._session = session
+```
+
+### Environment-Based Configuration
+
+```python
+import os
+from opensecureconf_client_enhanced import OpenSecureConfClient
+
+# Load from environment variables
+client = OpenSecureConfClient(
+    base_url=os.getenv("OSC_URL", "http://localhost:9000"),
+    user_key=os.getenv("OSC_USER_KEY"),
+    api_key=os.getenv("OSC_API_KEY"),
+    enable_retry=os.getenv("OSC_RETRY", "true").lower() == "true",
+    max_retries=int(os.getenv("OSC_MAX_RETRIES", "3")),
+    log_level=os.getenv("OSC_LOG_LEVEL", "INFO")
+)
+```
+
+### Working with Clusters
+
+```python
+from opensecureconf_client_enhanced import OpenSecureConfClient
+
+# Connect to any node in the cluster
+client = OpenSecureConfClient(
+    base_url="http://node1.example.com:9000",  # Can be any node
+    user_key="my-key",
+    api_key="cluster-secret-key"
+)
+
+# Check cluster topology
+status = client.get_cluster_status()
+print(f"Connected to: {status['node_id']}")
+print(f"Cluster mode: {status['mode']}")
+
+# In REPLICA mode: writes are automatically replicated
+config = client.create("shared_config", {"data": "value"})
+# This configuration is now available on all nodes
+
+# In FEDERATED mode: reads check all nodes
+config = client.read("distributed_config")
+# This searches across all federated nodes
+
+# Monitor cluster health
+if status['healthy_nodes'] < status['total_nodes']:
+    print(f"Warning: {status['total_nodes'] - status['healthy_nodes']} nodes are down")
+```
+
+## 📚 API Reference
+
+### OpenSecureConfClient
+
+Main client class for interacting with OpenSecureConf API.
+
+#### Constructor
+
+```python
+OpenSecureConfClient(
+    base_url: str,
+    user_key: str,
+    api_key: Optional[str] = None,
+    timeout: int = 30,
+    verify_ssl: bool = True,
+    enable_retry: bool = True,
+    max_retries: int = 3,
+    backoff_factor: float = 1.0,
+    pool_connections: int = 10,
+    pool_maxsize: int = 20,
+    log_level: str = "WARNING"
+)
+```
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `base_url` | `str` | Required | Base URL of the OpenSecureConf API server |
+| `user_key` | `str` | Required | User encryption key (minimum 8 characters) |
+| `api_key` | `Optional[str]` | `None` | API key for authentication (if enabled on server) |
+| `timeout` | `int` | `30` | Request timeout in seconds |
+| `verify_ssl` | `bool` | `True` | Verify SSL certificates |
+| `enable_retry` | `bool` | `True` | Enable automatic retry with exponential backoff |
+| `max_retries` | `int` | `3` | Maximum number of retry attempts |
+| `backoff_factor` | `float` | `1.0` | Exponential backoff multiplier |
+| `pool_connections` | `int` | `10` | Number of connection pools to cache |
+| `pool_maxsize` | `int` | `20` | Maximum size of the connection pool |
+| `log_level` | `str` | `"WARNING"` | Logging level (DEBUG, INFO, WARNING, ERROR) |
+
+#### Methods
+
+##### Health & Status
+
+###### `ping() -> bool`
+
+Check if the API server is reachable.
+
+**Returns:** `True` if server is healthy, `False` otherwise
+
+**Example:**
+```python
+if client.ping():
+    print("Server is online")
+```
+
+###### `get_service_info() -> Dict[str, Any]`
+
+Get information about the OpenSecureConf service.
+
+**Returns:** Dictionary with service metadata
+- `service`: Service name
+- `version`: API version
+- `features`: List of enabled features
+- `cluster_enabled`: Whether clustering is enabled
+- `cluster_mode`: Cluster mode (if enabled)
+
+**Example:**
+```python
+info = client.get_service_info()
+print(f"Version: {info['version']}")
+```
+
+##### Cluster Operations
+
+###### `get_cluster_status() -> Dict[str, Any]`
+
+Get cluster status and node information.
+
+**Returns:** Dictionary with cluster status
+- `enabled`: Whether clustering is enabled
+- `mode`: Cluster mode (replica or federated)
+- `node_id`: Current node identifier
+- `total_nodes`: Total number of nodes
+- `healthy_nodes`: Number of healthy nodes
+
+**Raises:** `ClusterError` if cluster status cannot be retrieved
+
+**Example:**
+```python
+status = client.get_cluster_status()
+print(f"Healthy: {status['healthy_nodes']}/{status['total_nodes']}")
+```
+
+###### `get_cluster_health() -> Dict[str, Any]`
+
+Check cluster node health.
+
+**Returns:** Dictionary with health status
+
+**Example:**
+```python
+health = client.get_cluster_health()
+print(f"Status: {health['status']}")
+```
+
+##### Configuration CRUD
+
+###### `create(key: str, value: Dict[str, Any], category: Optional[str] = None) -> Dict[str, Any]`
+
+Create a new encrypted configuration entry.
+
+**Parameters:**
+- `key`: Unique configuration key (1-255 characters)
+- `value`: Configuration data as dictionary
+- `category`: Optional category for grouping (max 100 characters)
+
+**Returns:** Dictionary with created configuration
+
+**Raises:**
+- `ConfigurationExistsError`: If key already exists
+- `ValueError`: If parameters are invalid
+
+**Example:**
+```python
+config = client.create(
+    "database",
+    {"host": "localhost", "port": 5432},
+    category="production"
+)
+```
+
+###### `read(key: str) -> Dict[str, Any]`
+
+Read and decrypt a configuration entry.
+
+**Parameters:**
+- `key`: Configuration key to retrieve
+
+**Returns:** Dictionary with configuration
+
+**Raises:**
+- `ConfigurationNotFoundError`: If key does not exist
+- `ValueError`: If key is invalid
+
+**Example:**
+```python
+config = client.read("database")
+print(config['value'])
+```
+
+###### `update(key: str, value: Dict[str, Any], category: Optional[str] = None) -> Dict[str, Any]`
+
+Update an existing configuration entry.
+
+**Parameters:**
+- `key`: Configuration key to update
+- `value`: New configuration data
+- `category`: Optional new category
+
+**Returns:** Dictionary with updated configuration
+
+**Raises:**
+- `ConfigurationNotFoundError`: If key does not exist
+- `ValueError`: If parameters are invalid
+
+**Example:**
+```python
+updated = client.update("database", {"host": "db.example.com", "port": 5432})
+```
+
+###### `delete(key: str) -> Dict[str, str]`
+
+Delete a configuration entry permanently.
+
+**Parameters:**
+- `key`: Configuration key to delete
+
+**Returns:** Dictionary with success message
+
+**Raises:**
+- `ConfigurationNotFoundError`: If key does not exist
+- `ValueError`: If key is invalid
+
+**Example:**
+```python
+result = client.delete("database")
+print(result['message'])
+```
+
+###### `list_all(category: Optional[str] = None) -> List[Dict[str, Any]]`
+
+List all configurations with optional category filter.
+
+**Parameters:**
+- `category`: Optional category filter
+
+**Returns:** List of configuration dictionaries
+
+**Example:**
+```python
+configs = client.list_all(category="production")
+```
+
+##### Batch Operations
+
+###### `bulk_create(configs: List[Dict[str, Any]], ignore_errors: bool = False) -> List[Dict[str, Any]]`
+
+Create multiple configurations in batch.
+
+**Parameters:**
+- `configs`: List of configuration dictionaries
+- `ignore_errors`: Continue on errors and return partial results
+
+**Returns:** List of created configurations
+
+**Raises:**
+- `ValueError`: If configs format is invalid
+- `OpenSecureConfError`: If creation fails and ignore_errors is False
+
+**Example:**
+```python
+configs = [
+    {"key": "db1", "value": {"host": "localhost"}, "category": "prod"},
+    {"key": "db2", "value": {"host": "remote"}, "category": "prod"}
+]
+results = client.bulk_create(configs)
+```
+
+###### `bulk_read(keys: List[str], ignore_errors: bool = False) -> List[Dict[str, Any]]`
+
+Read multiple configurations in batch.
+
+**Parameters:**
+- `keys`: List of configuration keys
+- `ignore_errors`: Skip missing keys and return partial results
+
+**Returns:** List of configuration dictionaries
+
+**Example:**
+```python
+configs = client.bulk_read(["db1", "db2", "api"])
+```
+
+###### `bulk_delete(keys: List[str], ignore_errors: bool = False) -> Dict[str, Any]`
+
+Delete multiple configurations in batch.
+
+**Parameters:**
+- `keys`: List of configuration keys
+- `ignore_errors`: Continue on errors
+
+**Returns:** Dictionary with summary: `{"deleted": [...], "failed": [...]}`
+
+**Example:**
+```python
+result = client.bulk_delete(["temp1", "temp2", "temp3"])
+print(f"Deleted: {len(result['deleted'])}")
+```
+
+##### Utility Methods
+
+###### `exists(key: str) -> bool`
+
+Check if a configuration key exists.
+
+**Parameters:**
+- `key`: Configuration key to check
+
+**Returns:** `True` if key exists, `False` otherwise
+
+**Example:**
+```python
+if client.exists("database"):
+    config = client.read("database")
+```
+
+###### `get_or_default(key: str, default: Dict[str, Any]) -> Dict[str, Any]`
+
+Get configuration or return default if not found.
+
+**Parameters:**
+- `key`: Configuration key to retrieve
+- `default`: Default value to return if not found
+
+**Returns:** Configuration dictionary or default
+
+**Example:**
+```python
+config = client.get_or_default("optional", {"enabled": False})
+```
+
+###### `count(category: Optional[str] = None) -> int`
+
+Count configurations, optionally filtered by category.
+
+**Parameters:**
+- `category`: Optional category filter
+
+**Returns:** Number of configurations
+
+**Example:**
+```python
+total = client.count()
+prod_count = client.count(category="production")
+```
+
+###### `list_categories() -> List[str]`
+
+Get list of all unique categories.
+
+**Returns:** Sorted list of category names
+
+**Example:**
+```python
+categories = client.list_categories()
+print(f"Categories: {', '.join(categories)}")
+```
+
+##### Session Management
+
+###### `close()`
+
+Close the underlying HTTP session.
+
+**Example:**
+```python
+client.close()
+```
+
+###### Context Manager
+
+The client supports context manager protocol for automatic cleanup.
+
+**Example:**
+```python
+with OpenSecureConfClient(base_url="...", user_key="...") as client:
+    config = client.create("key", {"value": "data"})
+# Session automatically closed
+```
+
+## ⚠️ Error Handling
+
+### Exception Hierarchy
+
+```
+OpenSecureConfError (base exception)
+├── AuthenticationError          # Invalid or missing credentials
+├── ConfigurationNotFoundError   # Configuration key does not exist
+├── ConfigurationExistsError     # Configuration key already exists
+└── ClusterError                 # Cluster operation failed
+```
+
+### Handling Errors
+
+```python
+from opensecureconf_client import (
+    OpenSecureConfClient,
+    AuthenticationError,
+    ConfigurationNotFoundError,
+    ConfigurationExistsError,
+    ClusterError,
+    OpenSecureConfError
+)
+
+try:
+    config = client.create("mykey", {"data": "value"})
+except AuthenticationError:
+    print("Authentication failed - check your user_key and api_key")
+except ConfigurationExistsError:
+    print("Configuration already exists - use update() instead")
+    config = client.update("mykey", {"data": "new_value"})
+except ConfigurationNotFoundError:
+    print("Configuration not found")
+except ClusterError as e:
+    print(f"Cluster error: {e}")
+except OpenSecureConfError as e:
+    print(f"API error: {e}")
+except ConnectionError as e:
+    print(f"Connection error: {e}")
+```
+
+### Best Practices for Error Handling
+
+```python
+# 1. Use specific exceptions first
+try:
+    config = client.read("important_config")
+except ConfigurationNotFoundError:
+    # Create with defaults if not found
+    config = client.create("important_config", {"default": "value"})
+
+# 2. Use exists() to avoid exceptions
+if not client.exists("optional_config"):
+    client.create("optional_config", {"data": "value"})
+
+# 3. Use get_or_default() for optional configurations
+config = client.get_or_default("optional", {"enabled": False})
+
+# 4. Handle bulk operation failures
+result = client.bulk_delete(keys, ignore_errors=True)
+if result['failed']:
+    print(f"Some deletions failed: {result['failed']}")
+```
+
+## ⚙️ Configuration Options
+
+### Production Configuration
+
+```python
+from opensecureconf_client_enhanced import OpenSecureConfClient
+import os
+
+# Production-ready configuration
+client = OpenSecureConfClient(
+    base_url=os.getenv("OSC_URL"),
+    user_key=os.getenv("OSC_USER_KEY"),
+    api_key=os.getenv("OSC_API_KEY"),
+    timeout=60,                     # Longer timeout for production
+    verify_ssl=True,                # Always verify SSL in production
+    enable_retry=True,
+    max_retries=5,                  # More retries for reliability
+    backoff_factor=2.0,             # Aggressive backoff
+    pool_connections=50,            # Large pool for high traffic
+    pool_maxsize=100,
+    log_level="INFO"                # Moderate logging
+)
+```
+
+### Development Configuration
+
+```python
+# Development-friendly configuration
+client = OpenSecureConfClient(
+    base_url="http://localhost:9000",
+    user_key="dev-key-12345678",
+    api_key="dev-api-key",
+    timeout=30,
+    verify_ssl=False,               # Self-signed certs in dev
+    enable_retry=False,             # Fail fast in development
+    pool_connections=5,             # Smaller pool
+    pool_maxsize=10,
+    log_level="DEBUG"               # Verbose logging for debugging
+)
+```
+
+### Environment Variables
+
+Recommended environment variables:
+
+```bash
+# Required
+export OSC_URL="http://localhost:9000"
+export OSC_USER_KEY="your-secure-key-min-8-chars"
+
+# Optional
+export OSC_API_KEY="cluster-secret-key-123"
+export OSC_TIMEOUT="30"
+export OSC_VERIFY_SSL="true"
+export OSC_RETRY="true"
+export OSC_MAX_RETRIES="3"
+export OSC_BACKOFF_FACTOR="1.0"
+export OSC_POOL_CONNECTIONS="10"
+export OSC_POOL_MAXSIZE="20"
+export OSC_LOG_LEVEL="INFO"
+```
+
+## 💡 Best Practices
+
+### 1. Use Context Managers
+
+```python
+# ✅ Good: Automatic cleanup
+with OpenSecureConfClient(base_url="...", user_key="...") as client:
+    config = client.create("key", {"data": "value"})
+
+# ❌ Avoid: Manual cleanup required
+client = OpenSecureConfClient(base_url="...", user_key="...")
+config = client.create("key", {"data": "value"})
+client.close()  # Easy to forget
+```
+
+### 2. Check Existence Before Operations
+
+```python
+# ✅ Good: Avoid exceptions
+if not client.exists("config"):
+    client.create("config", {"data": "value"})
+
+# ❌ Avoid: Exception handling for flow control
+try:
+    client.create("config", {"data": "value"})
+except ConfigurationExistsError:
+    pass
+```
+
+### 3. Use Batch Operations for Multiple Items
+
+```python
+# ✅ Good: Single batch operation
+keys = ["config1", "config2", "config3"]
+configs = client.bulk_read(keys, ignore_errors=True)
+
+# ❌ Avoid: Multiple individual requests
+configs = []
+for key in keys:
+    try:
+        configs.append(client.read(key))
+    except:
+        pass
+```
+
+### 4. Enable Retry for Production
+
+```python
+# ✅ Good: Resilient to transient failures
+client = OpenSecureConfClient(
+    base_url="...",
+    user_key="...",
+    enable_retry=True,
+    max_retries=3
+)
+
+# ❌ Avoid: No retry, fails on transient errors
+client = OpenSecureConfClient(
+    base_url="...",
+    user_key="...",
+    enable_retry=False
+)
+```
+
+### 5. Use Structured Logging
+
+```python
+# ✅ Good: Enable logging for production monitoring
+client = OpenSecureConfClient(
+    base_url="...",
+    user_key="...",
+    log_level="INFO"
+)
+
+# ❌ Avoid: Silent failures in production
+client = OpenSecureConfClient(
+    base_url="...",
+    user_key="...",
+    log_level="ERROR"  # Misses important info
+)
+```
+
+### 6. Secure Credential Management
+
+```python
+# ✅ Good: Load from environment or secrets manager
+import os
+from opensecureconf_client import OpenSecureConfClient
+
+client = OpenSecureConfClient(
+    base_url=os.getenv("OSC_URL"),
+    user_key=os.getenv("OSC_USER_KEY"),
+    api_key=os.getenv("OSC_API_KEY")
+)
+
+# ❌ Avoid: Hardcoded credentials
+client = OpenSecureConfClient(
+    base_url="http://localhost:9000",
+    user_key="hardcoded-key-12345",  # Never do this!
+    api_key="hardcoded-api-key"
+)
+```
+
+### 7. Monitor Cluster Health
+
+```python
+# ✅ Good: Regular health checks
+if client.ping():
+    status = client.get_cluster_status()
+    if status['enabled']:
+        if status['healthy_nodes'] < status['total_nodes']:
+            logger.warning(f"Cluster degraded: {status['healthy_nodes']}/{status['total_nodes']}")
+
+# ❌ Avoid: No health monitoring
+config = client.read("config")  # Might fail silently in degraded cluster
+```
+
+## 🔨 Development
+
+### Setting Up Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/lordraw77/OpenSecureConf.git
+cd OpenSecureConf/client
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install in development mode with all dependencies
+pip install -e ".[dev]"
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=opensecureconf_client --cov-report=html
+
+# Run specific test file
+pytest tests/test_client.py
+
+# Run with verbose output
+pytest -v
+
+# Run with logging
+pytest -s
+```
+
+### Code Quality
+
+```bash
+# Format code
+black opensecureconf_client.py
+black tests/
+
+# Sort imports
+isort opensecureconf_client.py tests/
+
+# Lint code
+flake8 opensecureconf_client.py
+pylint opensecureconf_client.py
+
+# Type checking
+mypy opensecureconf_client.py
+
+# Security check
+bandit -r opensecureconf_client.py
+```
+
+### Building Distribution
+
+```bash
+# Build package
+python -m build
+
+# Check distribution
+twine check dist/*
+
+# Upload to TestPyPI
+twine upload --repository testpypi dist/*
+
+# Upload to PyPI
+twine upload dist/*
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please follow these guidelines:
+
+### Reporting Issues
+
+- Use the [GitHub issue tracker](https://github.com/lordraw77/OpenSecureConf/issues)
+- Include minimal reproducible example
+- Specify Python version and client version
+- Include relevant logs (with sensitive data removed)
+
+### Pull Requests
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure all tests pass (`pytest`)
+6. Format code (`black`, `isort`)
+7. Lint code (`flake8`, `pylint`)
+8. Commit your changes (`git commit -m 'Add amazing feature'`)
+9. Push to the branch (`git push origin feature/amazing-feature`)
+10. Open a Pull Request
+
+### Code Style
+
+- Follow [PEP 8](https://peps.python.org/pep-0008/)
+- Use type hints
+- Write docstrings for all public methods
+- Maintain test coverage above 90%
+- Add examples for new features
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🔗 Links
+
+- [OpenSecureConf Server](https://github.com/lordraw77/OpenSecureConf)
+- [PyPI Package](https://pypi.org/project/opensecureconf-client/)
+- [Issue Tracker](https://github.com/lordraw77/OpenSecureConf/issues)
+- [Documentation](https://github.com/lordraw77/OpenSecureConf/tree/main/docs)
+- [Changelog](https://github.com/lordraw77/OpenSecureConf/blob/main/CHANGELOG.md)
+
+## 📮 Support
+
+- 📧 Email: support@opensecureconf.dev
+- 💬 GitHub Discussions: [opensecureconf/discussions](https://github.com/lordraw77/OpenSecureConf/discussions)
+- 🐛 Bug Reports: [opensecureconf/issues](https://github.com/lordraw77/OpenSecureConf/issues)
+
+## 🙏 Acknowledgments
+
+- Built with [FastAPI](https://fastapi.tiangolo.com/)
+- Encryption powered by [cryptography](https://cryptography.io/)
+- HTTP client using [requests](https://requests.readthedocs.io/)
+
+---
+
+**Made with ❤️ by the OpenSecureConf Team**