Metadata-Version: 2.4
Name: nell-scb-lib
Version: 1.1.2
Summary: Nellika SCB Payment Integration - Hardened C Module (Commercial License Required)
Home-page: https://nellika.co.th
Author: Danny G.
Author-email: "Danny G." <danny.g@nellika.co.th>
Maintainer: Nellika Consulting Services
Maintainer-email: Nellika Consulting Services <support@nellika.co.th>
License: Proprietary - Commercial License Required
Project-URL: Homepage, https://nellika.co.th
Keywords: scb,promptpay,qr,payment,thailand,banking,nellika
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: C
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: maintainer
Dynamic: requires-python

# nell-scb-lib

Python C extension for SCB (Siam Commercial Bank) payment integration with PromptPay QR code generation.

## ⚠️ IMPORTANT LICENSING INFORMATION

**This software is subject to commercial licensing terms and usage fees.**

- This library requires a valid commercial license for production use
- Usage telemetry data is collected and transmitted to Nellika Consulting Services Ltd.
- By installing and using this library, you agree to the collection and transmission of usage telemetry
- For licensing inquiries and pricing information, please contact: **sales@nellika.co.th**

**Copyright © 2024 Nellika Consulting Services Ltd. All rights reserved.**

---

## Overview

`nell-scb-lib` is a high-performance C extension module providing SCB payment integration for Python applications. It handles OAuth token management, QR code generation, and payment status checking through SCB's official API.

## Installation

```bash
pip install nell-scb-lib
```

**Supported Platforms:**
- Linux x86_64 (manylinux_2_31+)
- macOS ARM64 (Apple Silicon M1/M2/M3/M4)
- Python 3.9 through 3.14

## Telemetry & Privacy

This library collects the following telemetry data:
- License key usage and validation events
- API operation counts (QR creation, token refresh, payment checks)
- Error rates and types
- Library version and platform information
- **No sensitive data** (API keys, secrets, transaction details, or customer information) is collected

Telemetry helps us:
- Monitor license compliance
- Improve library stability and performance
- Provide better support to our customers

**By using this library, you consent to this data collection.**

For questions about data collection or to request data deletion, contact: privacy@nellika.co.th

---

## Quick Start

```python
import nell_scb_lib

# Create QR payment (database-driven, recommended)
result = nell_scb_lib.create_qr_by_bank_account(
    bank_account_id=1,
    amount=250.75,
    ref1="P00001",      # Invoice number (max 20 chars)
    ref2="CUST001",     # Customer code (max 12 chars)
    ref3="SCB"          # Optional reference
)

if result['status']['code'] == 1000:
    qr_image = result['data']['qrImage']  # Base64 PNG
    qr_raw = result['data']['qrRawData']  # PromptPay string
    print(f"QR created: {result['data']['transactionId']}")
```

## Environment Variables

Required for database-driven methods:

```bash
export PGDATABASE=your_database
export PGHOST=localhost
export PGPORT=5432
export PGUSER=odoo
export PGPASSWORD=your_password  # optional
```

## API Reference

### High-Level API (Recommended)

#### `create_qr_by_bank_account(bank_account_id, amount, ref1, ref2, ref3="SCB")`

Create SCB QR payment code using bank account ID. Automatically fetches configuration from database and manages token refresh.

**Parameters:**
- `bank_account_id` (str/int): Bank account ID from `res.partner.bank`
- `amount` (float): Payment amount in THB
- `ref1` (str): Reference 1, max 20 characters
- `ref2` (str): Reference 2, max 12 characters  
- `ref3` (str, optional): Reference 3, defaults to "SCB"

**Returns:** `dict` - SCB API response
```python
{
    "status": {"code": 1000, "description": "Success"},
    "data": {
        "qrRawData": "00020101021230...",
        "qrImage": "iVBORw0KGgoAAAANSUhEUgAA...",
        "transactionId": "..."
    }
}
```

**Example:**
```python
result = nell_scb_lib.create_qr_by_bank_account(
    bank_account_id=1,
    amount=250.75,
    ref1="P00001",
    ref2="CUST001"
)
```

---

### Mid-Level API

#### `create_qr_full(api_key, access_token, qr_create_url, biller_id, amount, ref1, ref2, ref3="SCB")`

Create SCB QR code with explicit parameters (requires manual token management).

**Parameters:**
- `api_key` (str): SCB API key
- `access_token` (str): Valid OAuth token
- `qr_create_url` (str): SCB QR endpoint URL
- `biller_id` (str): PromptPay biller ID
- `amount` (float): Payment amount in THB
- `ref1` (str): Reference 1, max 20 characters
- `ref2` (str): Reference 2, max 12 characters
- `ref3` (str, optional): Reference 3, defaults to "SCB"

**Returns:** `dict` - SCB API response

**Example:**
```python
# Step 1: Get access token
token_resp = nell_scb_lib.refresh_token(api_key, api_secret, token_url)
access_token = token_resp['data']['accessToken']

# Step 2: Create QR
result = nell_scb_lib.create_qr_full(
    api_key="your_api_key",
    access_token=access_token,
    qr_create_url="https://api.scb/...",
    biller_id="894547854396914",
    amount=100.50,
    ref1="P00001",
    ref2="TEST"
)
```

---

#### `refresh_token(api_key, api_secret, token_url)`

Refresh SCB OAuth access token.

**Parameters:**
- `api_key` (str): SCB API key
- `api_secret` (str): SCB API secret
- `token_url` (str): Token endpoint URL

**Returns:** `dict` - Token response
```python
{
    "status": {"code": 1000, "description": "Success"},
    "data": {
        "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
        "expiresIn": 1800,
        "tokenType": "Bearer"
    }
}
```

---

### Low-Level API

#### `create_qr(config_id, amount, reference, channel="ecomm")`

Create QR code using config ID from database (legacy method).

**Parameters:**
- `config_id` (str): SCB API configuration ID
- `amount` (float): Payment amount
- `reference` (str): Payment reference
- `channel` (str, optional): Payment channel, defaults to "ecomm"

**Returns:** `dict` - SCB API response

---

#### `check_payment(reference)`

Check SCB payment status by reference.

**Parameters:**
- `reference` (str): Payment reference to check

**Returns:** `dict` - Payment status
```python
{
    "status": {"code": 1000, "description": "Success"},
    "data": {
        "paymentStatus": "SUCCESS",
        "transactionId": "...",
        "amount": 100.50
    }
}
```

---

#### `version()`

Get module version string.

**Returns:** `str` - Version (e.g., "1.1.0")

---

## Database Schema Requirements

For database-driven methods, these tables are required:

**`res_partner_bank`:**
- Column: `scb_biller_id` (VARCHAR) - PromptPay biller ID

**`scb_api_config`:**
- Columns: `api_key`, `api_secret`, `environment`, `token_url`, `qr_create_url`, `payment_inquiry_url`
- Must have active configuration record

## Error Handling

All functions raise `RuntimeError` for failures:

```python
try:
    result = nell_scb_lib.create_qr_by_bank_account(
        bank_account_id=1,
        amount=250.75,
        ref1="P00001",
        ref2="CUST001"
    )
    
    if result['status']['code'] == 1000:
        # Success
        qr_data = result['data']
    else:
        # API error
        print(f"Error: {result['status']['description']}")
        
except RuntimeError as e:
    # System error
    print(f"Failed: {e}")
```

## Response Status Codes

- `1000`: Success
- `1001`: Invalid request
- `1002`: Authentication failed
- `1003`: Insufficient balance
- `1004`: Transaction not found
- `1005`: System error

**Always check the status code:**
```python
if result['status']['code'] == 1000:
    # Process successful response
    pass
else:
    # Handle error
    error_msg = result['status']['description']
```

## Best Practices

1. **Use High-Level API**: Prefer `create_qr_by_bank_account()` for automatic configuration management
2. **Validate References**: Keep ref1 ≤ 20 chars, ref2 ≤ 12 chars
3. **Check Status Codes**: Always verify `status.code == 1000` before using data
4. **Handle Errors**: Wrap API calls in try-except blocks
5. **Environment Setup**: Configure PostgreSQL environment variables before use

## Features

- ✅ Native C implementation for high performance
- ✅ Automatic OAuth token management
- ✅ Database-driven configuration
- ✅ PromptPay QR code generation
- ✅ Payment status checking
- ✅ Thread-safe operations
- ✅ Secure API communication (libcurl)
- ✅ Built-in license management
- ✅ Usage telemetry for compliance and support

## Support & Contact

- **Sales & Licensing**: sales@nellika.co.th
- **Technical Support**: support@nellika.co.th
- **Privacy Inquiries**: privacy@nellika.co.th
- **Website**: https://nellika.co.th

## Legal

**Copyright © 2024 Nellika Consulting Services Ltd. All rights reserved.**

This software is proprietary and confidential. Unauthorized copying, distribution, or use of this software, via any medium, is strictly prohibited without prior written permission from Nellika Consulting Services Ltd.

For licensing terms and conditions, please contact sales@nellika.co.th
