Metadata-Version: 2.4
Name: basalam-sdk
Version: 1.0.1
Summary: A comprehensive Python client library for interacting with Basalam API services
Project-URL: Homepage, https://github.com/basalam/python-sdk
Project-URL: Repository, https://github.com/basalam/python-sdk.git
Project-URL: Issues, https://github.com/basalam/python-sdk/issues
Author-email: Basalam Development Team <developers@basalam.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api,async,basalam,client,e-commerce,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: python-dateutil>=2.8.2
Provides-Extra: dev
Requires-Dist: black>=23.7.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.0.290; extra == 'dev'
Provides-Extra: lint
Requires-Dist: black>=23.7.0; extra == 'lint'
Requires-Dist: isort>=5.12.0; extra == 'lint'
Requires-Dist: mypy>=1.5.0; extra == 'lint'
Requires-Dist: ruff>=0.0.290; extra == 'lint'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
Requires-Dist: pytest-mock>=3.11.1; extra == 'test'
Requires-Dist: pytest>=7.4.0; extra == 'test'
Requires-Dist: respx>=0.20.0; extra == 'test'
Description-Content-Type: text/markdown

# Basalam Python SDK

[![Python Version](https://img.shields.io/pypi/pyversions/basalam-sdk)](https://pypi.org/project/basalam-sdk/)
[![PyPI Version](https://img.shields.io/pypi/v/basalam-sdk)](https://pypi.org/project/basalam-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A comprehensive Python SDK for interacting with Basalam API services. This SDK provides a clean, developer-friendly interface for all Basalam services with full async/sync support.

## Features

- **Full Async/Sync Support**: All operations support both synchronous and asynchronous patterns
- **Type Safety**: Built with Pydantic for robust type checking and validation  
- **Multiple Authentication Methods**: Support for client credentials, authorization code flow, and personal tokens
- **Comprehensive Service Coverage**: Access to all Basalam services including wallet, orders, chat, and more
- **Auto-retry Logic**: Built-in retry mechanisms for better reliability
- **Detailed Error Handling**: Specific error classes for different failure scenarios

## Installation

```bash
pip install basalam-sdk
```

## Quick Start

```python
from basalam_sdk import BasalamClient, PersonalToken
import asyncio

async def main():
    # Initialize with your credentials
    auth = PersonalToken(
        token="your-access-token",
        refresh_token="your-refresh-token"
    )
    client = BasalamClient(auth=auth)
    
    # Get products
    products = await client.get_products()
    print(f"Found {len(products)} products")
    
    # Get user balance
    balance = await client.get_balance(user_id=123)
    print(f"Balance: {balance}")

# Run async
asyncio.run(main())
```

## Authentication

The SDK supports three authentication methods:

### Personal Token
```python
from basalam_sdk import PersonalToken

auth = PersonalToken(
    token="your_access_token",
    refresh_token="your_refresh_token"
)
```

### Client Credentials (Server-to-Server)
```python
from basalam_sdk import ClientCredentials, Scope

auth = ClientCredentials(
    client_id="your-client-id",
    client_secret="your-client-secret",
    scopes=[Scope.CUSTOMER_CHAT_READ]
)
```

### Authorization Code (OAuth2 Flow)
```python
from basalam_sdk import AuthorizationCode, Scope

auth = AuthorizationCode(
    client_id="your-client-id",
    client_secret="your-client-secret",
    redirect_uri="https://your-app.com/callback",
    scopes=[Scope.CUSTOMER_ORDER_READ]
)

# Get authorization URL
auth_url = auth.get_authorization_url()
# After user authorization, exchange code for tokens
token_info = await auth.get_token(code="received_code")
```

## Available Services

### Core Service
Manage vendors, products, shipping methods, and user information.

```python
# Create a vendor
vendor = await client.create_vendor(
    user_id=123,
    request=CreateVendorSchema(
        title="My Store",
        summary="store123"
    )
)

# Create a product with images
product = await client.create_product(
    vendor_id=456,
    request=ProductRequestSchema(
        name="Sample Product",
        price=100000
    ),
    photo_files=[("photo1.jpg", photo_bytes)]
)
```

### Wallet Service
Handle user balances, transactions, and refunds.

```python
# Get balance
balance = await client.get_balance(user_id=123)

# Create expense
expense = await client.create_expense(
    user_id=123,
    request=SpendCreditRequest(
        amount=10000,
        reason_id=1
    )
)
```

### Order Service
Manage shopping baskets and payment processing.

```python
# Get active baskets
baskets = await client.get_baskets(refresh=True)

# Create payment
payment = await client.create_invoice_payment(
    invoice_id=789,
    request=CreatePaymentRequestModel(
        payment_method="credit_card"
    )
)
```

### Chat Service
Handle messaging and conversations.

```python
# Send message
message = await client.create_message(
    request=MessageRequest(
        chat_id=123,
        content="Hello!"
    )
)

# Get messages
messages = await client.get_messages(chat_id=123)
```

### Search Service
Search products with advanced filtering.

```python
# Search products
results = await client.search_products(
    request=ProductSearchModel(
        query="laptop",
        min_price=100000,
        max_price=500000
    )
)
```

### Additional Services
- **Order Processing**: Track orders and parcels
- **Upload**: Secure file uploads  
- **Webhook**: Real-time event notifications

## Sync/Async Usage

All methods support both patterns:

```python
# Async (recommended)
balance = await client.get_balance(user_id=123)

# Sync
balance = client.get_balance_sync(user_id=123)
```

## Documentation

For detailed documentation and examples, visit:
- [GitHub Repository](https://github.com/basalam/python-sdk)
- [Developers Documentation](https://developers.basalam.com/)

## License

MIT License - see [LICENSE](https://github.com/basalam/python-sdk/blob/main/LICENSE) for details.