Metadata-Version: 2.5
Name: identify-africa
Version: 0.1.1
Summary: Python SDK for the Identify Africa KYC and identity verification API
Author: magwach
License: MIT
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest-mock>=3.12; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# identify-africa

Python SDK for the [Identify Africa](https://identifyafrica.io) KYC and identity verification API. Provides typed, validated access to national ID, alien ID, driving license, vehicle plate, and phone intelligence verification.

## Installation

```bash
pip install identify-africa
```

## Usage

```python
from identify_africa import IdentifyAfricaClient, verify_national_id, NationalIdRequest

client = IdentifyAfricaClient(
    api_key="your_api_key",
    api_secret="your_api_secret",
)

result = verify_national_id(client, NationalIdRequest(idnumber="12345678"))

if result["success"]:
    print(result["data"]["first_name"])
else:
    print(result["message"], result["response_code"])
```

Responses are returned exactly as sent by the API, unmodified — including both success and error payloads.

## Configuration

| Parameter     | Type                          | Required | Default     | Description                                       |
| ------------- | ----------------------------- | -------- | ----------- | ------------------------------------------------- |
| `api_key`     | str                           | Yes      | —           | Your API key                                      |
| `api_secret`  | str                           | Yes      | —           | Your API secret                                   |
| `environment` | `"sandbox"` \| `"production"` | No       | `"sandbox"` | Which base URL to target                          |
| `timeout`     | float                         | No       | `10.0`      | Request timeout in seconds                        |
| `max_retries` | int                           | No       | `2`         | Max retry attempts on transient failures          |
| `retry_delay` | float                         | No       | `0.3`       | Base delay (seconds) for exponential backoff      |
| `logger`      | `Logger`                      | No       | —           | Optional logger for request/response/retry events |

Store your credentials in your own `.env` file (loaded with a tool like `python-dotenv`) — never commit them to source control:

API_KEY=your_api_key
API_SECRET=your_api_secret

### Logging

```python
import logging
from identify_africa import IdentifyAfricaClient

logger = logging.getLogger("identify_africa")
logging.basicConfig(level=logging.DEBUG)

client = IdentifyAfricaClient(
    api_key="...",
    api_secret="...",
    logger=logger,
)
```

Sensitive request fields (`idnumber`, `plate`, `number`) are automatically masked in log output (e.g. `****5678`). Response data is never logged.

## Available Functions

### `verify_national_id(client, NationalIdRequest(idnumber=...))`

Verifies a Kenyan National ID number (8 digits).

### `verify_alien_id(client, AlienIdRequest(idnumber=...))`

Verifies an Alien ID number for non-citizens.

### `verify_driving_license(client, DrivingLicenseRequest(idnumber=...))`

Looks up driving license details using a National ID number.

### `verify_vehicle_plate(client, VehiclePlateRequest(plate=...))`

Verifies vehicle registration details using a number plate.

### `get_phone_intel(client, PhoneIntelRequest(number=...))`

Retrieves phone intelligence — carrier, spam score, location, and validation details.

Each function validates required input client-side before sending the request, raising a `ValueError` if validation fails (some fields are also validated at construction time by the underlying `pydantic` request models).

## Response Shape

Every function returns a plain `dict` matching the API's response envelope:

```python
{
    "success": bool,
    "response_code": int,
    "message": str,
    "data": ...,        # shape depends on endpoint and success/failure
    "request_id": str,
}
```

Check `result["success"]` before relying on `result["data"]`'s shape.

## Error Codes

| Code | Meaning                                          | Retried automatically? |
| ---- | ------------------------------------------------ | ---------------------- |
| 200  | Success                                          | —                      |
| 401  | Unauthorized — invalid or missing credentials    | No                     |
| 402  | Low credit balance                               | No                     |
| 412  | Validation error (check `data` for field errors) | No                     |
| 424  | Upstream dependency failure                      | Yes                    |
| 502  | Upstream service unavailable                     | Yes                    |

## Development

```bash
pip install -e ".[dev]"
pytest
python -m build
```

Built with [httpx](https://www.python-httpx.org/) and [pydantic](https://docs.pydantic.dev/). Tests run with [pytest](https://pytest.org/).

## Release Process

This project follows [Semantic Versioning](https://semver.org/). CI runs tests and a build check on every push/PR to `main`.

Publishing to PyPI is automated via [Trusted Publishing (OIDC)](https://docs.pypi.org/trusted-publishers/) — pushing a version tag triggers the `publish.yml` workflow, which runs tests, builds, and publishes with no stored credentials:

```bash
# bump version in pyproject.toml
git add .
git commit -m "Release vX.Y.Z"
git tag vX.Y.Z
git push && git push --tags
```

## License

MIT
# identify-africa

Python SDK for the [Identify Africa](https://identifyafrica.io) KYC and identity verification API. Provides typed, validated access to national ID, alien ID, driving license, vehicle plate, and phone intelligence verification.

## Installation

```bash
pip install identify-africa
```

## Usage

```python
from identify_africa import IdentifyAfricaClient, verify_national_id, NationalIdRequest

client = IdentifyAfricaClient(
    api_key="your_api_key",
    api_secret="your_api_secret",
)

result = verify_national_id(client, NationalIdRequest(idnumber="12345678"))

if result["success"]:
    print(result["data"]["first_name"])
else:
    print(result["message"], result["response_code"])
```

Responses are returned exactly as sent by the API, unmodified — including both success and error payloads.

## Configuration

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `api_key` | str | Yes | — | Your API key |
| `api_secret` | str | Yes | — | Your API secret |
| `environment` | `"sandbox"` \| `"production"` | No | `"sandbox"` | Which base URL to target |
| `timeout` | float | No | `10.0` | Request timeout in seconds |
| `max_retries` | int | No | `2` | Max retry attempts on transient failures |
| `retry_delay` | float | No | `0.3` | Base delay (seconds) for exponential backoff |
| `logger` | `Logger` | No | — | Optional logger for request/response/retry events |

Store your credentials in your own `.env` file (loaded with a tool like `python-dotenv`) — never commit them to source control:

API_KEY=your_api_key
API_SECRET=your_api_secret


### Logging

```python
import logging
from identify_africa import IdentifyAfricaClient

logger = logging.getLogger("identify_africa")
logging.basicConfig(level=logging.DEBUG)

client = IdentifyAfricaClient(
    api_key="...",
    api_secret="...",
    logger=logger,
)
```

Sensitive request fields (`idnumber`, `plate`, `number`) are automatically masked in log output (e.g. `****5678`). Response data is never logged.

## Available Functions

### `verify_national_id(client, NationalIdRequest(idnumber=...))`
Verifies a Kenyan National ID number (8 digits).

### `verify_alien_id(client, AlienIdRequest(idnumber=...))`
Verifies an Alien ID number for non-citizens.

### `verify_driving_license(client, DrivingLicenseRequest(idnumber=...))`
Looks up driving license details using a National ID number.

### `verify_vehicle_plate(client, VehiclePlateRequest(plate=...))`
Verifies vehicle registration details using a number plate.

### `get_phone_intel(client, PhoneIntelRequest(number=...))`
Retrieves phone intelligence — carrier, spam score, location, and validation details.

Each function validates required input client-side before sending the request, raising a `ValueError` if validation fails (some fields are also validated at construction time by the underlying `pydantic` request models).

## Response Shape

Every function returns a plain `dict` matching the API's response envelope:

```python
{
    "success": bool,
    "response_code": int,
    "message": str,
    "data": ...,        # shape depends on endpoint and success/failure
    "request_id": str,
}
```

Check `result["success"]` before relying on `result["data"]`'s shape.

## Error Codes

| Code | Meaning | Retried automatically? |
|---|---|---|
| 200 | Success | — |
| 401 | Unauthorized — invalid or missing credentials | No |
| 402 | Low credit balance | No |
| 412 | Validation error (check `data` for field errors) | No |
| 424 | Upstream dependency failure | Yes |
| 502 | Upstream service unavailable | Yes |

## Development

```bash
pip install -e ".[dev]"
pytest
python -m build
```

Built with [httpx](https://www.python-httpx.org/) and [pydantic](https://docs.pydantic.dev/). Tests run with [pytest](https://pytest.org/).

## Release Process

This project follows [Semantic Versioning](https://semver.org/). CI runs tests and a build check on every push/PR to `main`.

Publishing to PyPI is automated via [Trusted Publishing (OIDC)](https://docs.pypi.org/trusted-publishers/) — pushing a version tag triggers the `publish.yml` workflow, which runs tests, builds, and publishes with no stored credentials:

```bash
# bump version in pyproject.toml
git add .
git commit -m "Release vX.Y.Z"
git tag vX.Y.Z
git push && git push --tags
```

## License

MIT