Metadata-Version: 2.4
Name: ng-fintech-utils
Version: 0.1.0
Summary: A lightweight utility package for Nigerian fintech data, bank codes, and USSD tools.
Author-email: "Caleb A." <calebageb9@gmail.com>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.34.0

# 🇳🇬 ng-fintech-utils (Python)

A lightweight Python wrapper for the **NG Fintech Utils API**. Easily fetch Nigerian bank codes, NUBAN/sorting codes, and USSD strings directly in your Python applications.

---

## 📦 Installation

You can install the package directly from PyPI using pip:

```bash
pip install ng_fintech_utils
```

---

## 🚀 Getting Started

The package provides a simple, synchronous client to interact with the fintech data.

### 1. Initialization

Import the client and initialize it. By default, it connects to the live production API. (You can also pass a custom `base_url` for local testing).

```python
from ng_fintech_utils.client import NG_FINTECH_UTILS

# Initialize the client
fintech = NG_FINTECH_UTILS()

# For local development against your Next.js server:
# fintech = NG_FINTECH_UTILS(base_url="http://localhost:3000/api")
```

### 2. Fetch All Banks

Retrieve a complete list of all supported commercial banks, their codes, and USSD strings.

```python
banks = fintech.get_banks()

for bank in banks:
    print(f"{bank['name']} - Code: {bank['code']} - USSD: {bank['ussd']}")
```

### 3. Fetch a Single Bank

You can look up a specific bank using its URL-friendly `slug` or its 3-digit `code`. This is great for resolving bank details dynamically during a checkout flow.

```python
# Lookup by 3-digit code
gtb = fintech.get_bank("058")
print(gtb['name'])  # Output: Guaranty Trust Bank

# Lookup by slug
access = fintech.get_bank("access-bank")
print(access['ussd'])  # Output: *901#
```

---

## 🛠️ Error Handling

The client will return `None` if a specific bank is not found, making it easy to write clean conditional checks:

```python
bank = fintech.get_bank("unknown-code")

if not bank:
    print("Bank not found. Please check the code.")
```

If the API is unreachable or rate-limited, the client will raise an `Exception` with the corresponding HTTP status code.

---

## 🔗 Ecosystem

This package is part of the broader **NG Fintech Utils** project. If you are a frontend developer, you can also query our free REST API directly without this wrapper.

See the [API Documentation](https://github.com/Sly611/ng-fintech-utils) for more details.

## 📄 License

MIT License
