Metadata-Version: 2.4
Name: oilflow
Version: 0.1.0
Summary: Official Python SDK for the OilFlow Network compliance APIs.
Author-email: OilFlow Network <api@oilflow.us>
License: Apache-2.0
Project-URL: Homepage, https://oilflow.us/api-docs
Project-URL: Source, https://github.com/oilflow-network/sdk-python
Project-URL: OpenAPI, https://oilflow.us/openapi.yaml
Project-URL: Sandbox, https://oilflow.us/sandbox
Keywords: oilflow,compliance,kyc,sanctions,aml,regulatory,trade-finance,ucp-600,ubo
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31
Requires-Dist: typing-extensions>=4.0

# oilflow (Python SDK)

Official Python SDK for the [OilFlow Network](https://oilflow.us) compliance APIs.

- Regulatory Matrix (235 jurisdictions)
- KYC-as-API + UBO + multilingual Adverse Media
- Scam Cluster Intelligence Feed
- Webhooks with HMAC verification helper (raw / Slack / Teams formats)
- Regulator-ready reports (FATF Rec.10, FinCEN CDD, EU 6AMLD, FCA SYSC 18, MAS 626, OFSI)
- LC discrepancy detection (UCP 600)
- Customer watchlist sync
- Paginated audit log streaming

Built-in retry with jittered exponential backoff for 5xx + 429 responses (Retry-After respected). Python 3.9+.

## Install

```bash
pip install oilflow
```

## Quick start

```python
from oilflow import Client

client = Client()  # reads OILFLOW_API_KEY from env

result = client.kyc.screen(
    company_name="Acme Trading FZE",
    country="UAE",
    directors=["Jane Doe"],
)
print(result["verdict"])         # "pass" / "review" / "fail"
print(result["screening_run_id"])
```

### Regulatory check

```python
check = client.regulatory.check(
    country="Kenya",
    product="crude",
    listing_type="demand",
)
if not check["allowed"]:
    for blocker in check["blockers"]:
        print(blocker["reason"])
```

### Verify a webhook delivery

```python
from oilflow import verify_webhook_signature

@app.route("/webhooks/oilflow", methods=["POST"])
def webhook():
    raw = request.get_data()
    if not verify_webhook_signature(
        raw,
        request.headers.get("X-OilFlow-Signature"),
        OILFLOW_WEBHOOK_SECRET,
    ):
        abort(401)
    # process request.json
```

### Subscribe to webhook events

```python
sub = client.webhooks.create(
    url="https://your-app.example.com/webhooks/oilflow",
    events=["kyc.match_detected", "cluster.entity_added"],
    description="Compliance war-room",
)
# sub["secret"] is shown once; store it in your secret manager
```

For Slack/Teams native rendering, set `delivery_format="slack"` (URL must be a `hooks.slack.com` incoming webhook) or `"teams"` (`webhook.office.com`). OilFlow renders the payload as Block Kit / Adaptive Card on the server — no HMAC secret is issued.

### Stream the audit log

```python
for page in client.audit.pages(days=90):
    print(f"page: {page['count']} rows")
    # ship to your warehouse
```

## Configuration

```python
Client(
    api_key="oilflow_live_...",       # or OILFLOW_API_KEY env var
    base_url="https://oilflow.us",    # or OILFLOW_BASE_URL env var
    max_retries=5,
    base_retry_delay=0.25,
    timeout=30.0,
)
```

## Error handling

```python
from oilflow import OilFlowApiError

try:
    client.kyc.screen(company_name="...")
except OilFlowApiError as e:
    print(e.status_code, e.error_code, e.request_id)
```

`error_code` is a stable, branchable identifier (`auth_required`, `scope_denied`, `rate_limited`, `invalid_param`, etc.).

## Sandbox

Get a free sandbox key (7-day, 100 calls/day, read-only) without signup at <https://oilflow.us/sandbox>. Pass it as `api_key` to evaluate the API end-to-end before upgrading.

## Documentation

- Full API reference: <https://oilflow.us/api-docs>
- OpenAPI 3.1 spec: <https://oilflow.us/openapi.yaml>

## License

Apache-2.0.
