Metadata-Version: 2.4
Name: payyd-python-sdk
Version: 0.1.11
Summary: Python SDK for GraphQL APIs backed by Postman collections.
Author: Payyd SDK Team
License: MIT
Requires-Python: >=3.9
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# payyd-python-sdk

Python SDK for Payyd Enterprise GraphQL APIs.

## Features

- One method per Postman call via `PayydEnterpriseClient`
- Generic GraphQL client (`GraphQLClient`) for custom operations
- Postman collection parser supports both `body.mode = graphql` and `body.mode = raw`
- Mandatory Payyd request signing in `PayydEnterpriseClient` (`payyd-requestid`, `x-nonce`, `x-api-key`, `x-sign`)
- Optional signing support in low-level `GraphQLClient`
- Generated model classes per operation (parsed from collection response samples)
- Structured error classes

## Installation

```bash
pip install -e .
```

For development dependencies:

```bash
pip install -e '.[dev]'
```

## Quick Start (Method-Per-Call SDK)

```python
from payyd_sdk import PayydEnterpriseClient

client = PayydEnterpriseClient(
    endpoint=PayydEnterpriseClient.SANDBOX_ENDPOINT,
    api_key="YOUR_PUBLIC_KEY",
    secret_key="YOUR_SECRET_KEY",
)

# 1) Get token
login = client.auth_get_token("email@domain.com", "your_password")
access_token = login.token.accessToken if login.token else None

# 2) Use token for next calls
if access_token:
    client.set_bearer_token(access_token)

# 3) Call any exposed method
balances = client.account_get_balances(currency_code="USD")
print(balances.balances)
```

## Available SDK Methods

Use `client.available_methods` to inspect methods loaded in the client.

Examples:

- `auth_get_token(...)`
- `account_get_balances(...)`
- `payin_hosted_create_transaction(...)`
- `payin_s2s_pay_transaction(...)`
- `payout_get_fx_rate(...)`
- `payout_create_transaction(...)`

Methods return parsed model classes and now prefer explicit args/input models instead of raw variable maps.
Examples:

- `auth_get_token(username, password)`
- `account_get_balances(currency_code=None)`
- `payin_hosted_create_transaction(PayinCreateTransactionInput(...))`
- `payin_hosted_cancel_transaction(PayinCancelTransactionInput(...))`
- `payin_hosted_get_transactions(PayinGetTransactionsQuery(...))`
- `payin_hosted_get_transaction_by_internal_ref(internal_ref)`
- `payin_hosted_get_transaction_by_reference(reference)`
- `payin_s2s_create_transaction(PayinCreateTransactionInput(...))`
- `payin_s2s_cancel_transaction(PayinCancelTransactionInput(...))`
- `payin_s2s_get_transactions(PayinGetTransactionsQuery(...))`
- `payin_s2s_get_transaction_by_internal_ref(internal_ref)`
- `payin_s2s_get_transaction_by_reference(reference)`
- `payin_s2s_get_payment_methods(country_iso_code3)`
- `payin_s2s_get_identification_types(country_iso_code3)`
- `payin_s2s_pay_transaction(PayinS2sPayTransactionInput(...))`
- `payout_create_transaction(PayoutCreateTransactionInput(...))`
- `payout_get_banks(PayoutGetBanksQuery(...))`
- `payout_get_fx_rate(PayoutGetFxRateQuery(...))`
- `payout_get_transaction(reference)`
- `payout_get_transactions(PayoutGetTransactionsQuery(...))`

`PayinS2sPayTransactionInput` uses nested models:
- `PayinS2sPayInput`
- `PayinPaymentMethodInput`
- `PayinSenderInput`
- `PayinSenderAddressInput`
- `PayinSenderIdentificationInput`
- `PayinSenderBankDetailsInput` (optional)

`PayoutCreateTransactionInput` uses nested model:
- `PayoutReceiverInput`

Country-specific validation for `payin_s2s_pay_transaction` is enforced using CSV-derived rules (required fields + regex by country).
Rule source module: `src/payyd_sdk/payin_country_rules.py`.
If a sender country has no entry in that module, the SDK applies only base model validation (no country-specific checks).
Rules are generated from CSV via `scripts/generate_payin_country_rules.py`.

## Generic GraphQL Client

```python
from payyd_sdk import GraphQLClient

client = GraphQLClient(
    endpoint="https://api.example.com/graphql",
    token="YOUR_BEARER_TOKEN",
)

result = client.execute_result("query Health { health }")
print(result.data)
```

## Build from Postman Collection

```python
from payyd_sdk import GraphQLClient

client = GraphQLClient.from_postman_collection(
    "./postman_collection.json",
    endpoint="https://sandbox-enterprisegateway.payyd.money/graphql",
)

print(client.operation_names)
```

## Raw GraphQL Result Access

`PayydEnterpriseClient` also exposes `call_raw(...)` if you need request metadata (`request_id`, status code, raw payload):

```python
raw = client.call_raw("account_get_balances")
print(raw.request_id, raw.status_code, raw.data)
```

## Error Handling

- `GraphQLRequestError`: HTTP/network/invalid JSON/invalid GraphQL wire format
- `GraphQLError`: GraphQL `errors` returned by API (with parsed errors list)
- `OperationNotFoundError`: unknown named operation
- `InvalidCollectionError`: invalid Postman collection format
- `SigningConfigurationError`: signing enabled without required keys

## Testing

```bash
pytest
```

Country rule coverage tests are included and data-driven against the generated `PAYIN_COUNTRY_RULES` table.
