Metadata-Version: 2.4
Name: pykolofinance
Version: 8.3.0
Summary: A utility package for kolomoni banking microservices
Author-email: Daniel Ale <danielale9291@gmail.com>
Description-Content-Type: text/markdown
Requires-Dist: cuid2>=2.0.1
Requires-Dist: django>=5.2.14
Requires-Dist: djangorestframework>=3.17.1
Requires-Dist: djangorestframework-simplejwt>=5.5.1
Requires-Dist: drf-spectacular>=0.29.0
Requires-Dist: faker>=40.18.0
Requires-Dist: opensearch-py>=3.2.0
Requires-Dist: redis>=7.4.0
Requires-Dist: requests>=2.34.1

# Pykolofinance

[![PyPI version](https://badge.fury.io/py/pykolofinance.svg)](https://pypi.org/project/pykolofinance/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

A comprehensive utility package for Kolomoni banking microservices, providing authentication, logging, KYC verification, permissions management, and common banking utilities built with Django and Django REST Framework.

## Features

- **Custom Authentication**: JWT-based authentication middleware for microservices
- **Audit Logging**: Comprehensive request/response logging to OpenSearch/Elasticsearch
- **KYC Integration**: Identity verification with multiple providers (Dojah, Mock)
- **Permissions System**: Flexible permission checking and management
- **Common Utilities**: Banking-specific helpers, serializers, and services
- **OpenAPI Documentation**: Auto-generated API docs with DRF Spectacular

## Installation

Install Pykolofinance using pip:

```bash
pip install pykolofinance
```

Or using poetry:

```bash
poetry add pykolofinance
```

## Quick Start

### 1. Add to Django Settings

Add `pykolofinance` to your `INSTALLED_APPS` and include the logging middleware:

```python
INSTALLED_APPS = [
    # ... other apps
    'pykolofinance',
]

MIDDLEWARE = [
    # ... other middleware
    'pykolofinance.audtilog.logger.APILoggerMiddleware',
    # ... other middleware
]
```

### 2. Configure Authentication

Update your `REST_FRAMEWORK` settings:

```python
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'pykolofinance.authentication.CustomJWTAuthentication',
        'rest_framework.authentication.BasicAuthentication',
        'rest_framework.authentication.SessionAuthentication',
    ),
    # ... other settings
}
```

### 3. Environment Variables

Set the required environment variables:

```bash
# For authentication service
AUTH_SERVICE_BASE_URL=https://your-auth-service-url

# For OpenSearch logging
PYKOLOFINANCE_OPENSEARCH_HOST=your-opensearch-host
PYKOLOFINANCE_OPENSEARCH_PORT=9200
PYKOLOFINANCE_OPENSEARCH_USERNAME=your-username
PYKOLOFINANCE_OPENSEARCH_PASSWORD=your-password
PYKOLOFINANCE_OPENSEARCH_INDEX_NAME=your-index-name

# Required Django settings
APP_NAME=your-app-name
ENVIRONMENT_INSTANCE=production
```

## Usage

### Authentication

The package provides a custom JWT authentication class that integrates with your authentication service:

```python
from pykolofinance.authentication import CustomJWTAuthentication

# Automatically configured when added to REST_FRAMEWORK settings
```

### Logging

Enable comprehensive API logging to OpenSearch with the `APILoggerMiddleware`:

#### 1. Add Middleware

Add the middleware to your Django `MIDDLEWARE` settings:

```python
MIDDLEWARE = [
    # ... other middleware
    'pykolofinance.audtilog.logger.APILoggerMiddleware',
    # ... other middleware
]
```

#### 2. Configure OpenSearch

Set the required OpenSearch environment variables:

```bash
PYKOLOFINANCE_OPENSEARCH_HOST=your-opensearch-host
PYKOLOFINANCE_OPENSEARCH_PORT=9200
PYKOLOFINANCE_OPENSEARCH_USERNAME=your-username
PYKOLOFINANCE_OPENSEARCH_PASSWORD=your-password
PYKOLOFINANCE_OPENSEARCH_INDEX_NAME=your-index-name
```

#### 3. Additional Settings

Configure logging behavior in your Django `settings.py`:

```python
# Logging exclusions
API_LOGGER_SKIP_URL_NAME = ['health_check', 'metrics']  # Skip specific endpoints
API_LOGGER_SKIP_NAMESPACE = ['admin']  # Skip entire apps
API_LOGGER_EXCLUDE_HTTP_METHODS = ['GET']  # Exclude methods (default: GET)
API_LOGGER_EXCLUDE_KEYS = ['password', 'token', 'access', 'refresh']  # Hide sensitive data

# Additional required settings
APP_NAME = 'your-app-name'
ENVIRONMENT_INSTANCE = 'production'  # or 'staging', 'development'
```

The middleware automatically logs all API requests and responses, including execution time, user information, and masked sensitive data.

#### Configuration Validation

The package includes a `get_opensearch_config()` function that validates all required OpenSearch settings are properly configured:

```python
from pykolofinance.audtilog.opensearch_logger import get_opensearch_config

# This function checks for required settings:
# - PYKOLOFINANCE_OPENSEARCH_HOST
# - PYKOLOFINANCE_OPENSEARCH_PORT
# - PYKOLOFINANCE_OPENSEARCH_USERNAME
# - PYKOLOFINANCE_OPENSEARCH_PASSWORD
# - PYKOLOFINANCE_OPENSEARCH_INDEX_NAME

config = get_opensearch_config()
```

### KYC Verification

Use the KYC service for identity verification:

```python
from pykolofinance.kyc.verifier import KYCVerifier

verifier = KYCVerifier()
result = verifier.verify_identity(user_data)
```

### Permissions

Implement permission checking:

```python
from pykolofinance.permissions.checker import PermissionChecker

checker = PermissionChecker()
if checker.has_permission(user, 'required_permission'):
    # Proceed with operation
```

## Configuration

### Required Environment Variables

- `AUTH_SERVICE_BASE_URL`: Base URL for the authentication service
- `PYKOLOFINANCE_OPENSEARCH_HOST`: OpenSearch host URL
- `PYKOLOFINANCE_OPENSEARCH_PORT`: OpenSearch port (default: 9200)
- `PYKOLOFINANCE_OPENSEARCH_USERNAME`: OpenSearch username
- `PYKOLOFINANCE_OPENSEARCH_PASSWORD`: OpenSearch password
- `PYKOLOFINANCE_OPENSEARCH_INDEX_NAME`: OpenSearch index name for logs

### Required Django Settings

Add these to your Django `settings.py`:

```python
APP_NAME = 'your-app-name'  # Required for logging
ENVIRONMENT_INSTANCE = 'production'  # or 'staging', 'development'
```

### Optional Settings

Configure logging behavior:

```python
# Logging exclusions
API_LOGGER_SKIP_URL_NAME = ['health_check', 'metrics']  # Skip specific endpoints
API_LOGGER_SKIP_NAMESPACE = ['admin']  # Skip entire apps
API_LOGGER_EXCLUDE_HTTP_METHODS = ['GET', 'PATCH']  # Exclude HTTP methods
API_LOGGER_EXCLUDE_KEYS = ['password', 'token', 'access', 'refresh']  # Hide sensitive data
```

## Dependencies

- Django >= 5.2.14
- Django REST Framework >= 3.17.1
- Django REST Framework Simple JWT >= 5.5.1
- DRF Spectacular >= 0.29.0
- OpenSearch Python >= 3.2.0
- Redis >= 7.4.0
- And more...

## Development

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/your-repo/pykolofinance.git
cd pykolofinance

# Install dependencies
pip install -e .
pip install -r requirements.txt

# Run tests
pytest
```

### Building

```bash
uv build
```

### Publishing

```bash
uv publish
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Support

For questions or issues, please open an issue on GitHub or contact the maintainers.
# Sensitive data will be replaced with "***FILTERED***".
----

= KYC

== 1. Verification

The service includes a KYC verification service. There are three verification types:

. BVN
. NIN
. BVN_SELFIE

We currently have two providers:

. MOCK
. DOJAH

By default, the provider is set to MOCK. To override the default value, set `PYKOLO_DEFAULT_IDENTITY_SERVICE` in your settings file to your preferred provider:

[source,python]
----
PYKOLO_DEFAULT_IDENTITY_SERVICE = "DOJAH"
----

Please note that when you switch the provider to DOJAH, you are required to set `DOJAH_API_URL`, `DOJAH_APP_ID`, and `DOJAH_API_KEY` in your settings.py file. Please note that the DOJAH API URL must be without a trailing slash `/`.

[source,python]
----
from pykolofinance.kyc.verifier import get_identity_data

identity_data = get_identity_data(identity_type, identity_number, image=None, user_id=None)
----

Note that an image is required while verifying BVN_SELFIE.





.Table Contributors
|===
|Name |Role |Email
|Daniel Ale |SA |d.ale@capitalsage.ng
|Isaiah Aimiton |BE |i.aimiton@capitalsage.ng
|===
[quote]
____
Happy Coding
____
