Basalam Python SDK

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

pip install basalam-sdk

Quick Start

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

from basalam_sdk import PersonalToken

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

Client Credentials (Server-to-Server)

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)

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.

# 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.

# 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.

# 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.

# 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.

# 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:

# 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
• Developers Documentation

License

MIT License - see LICENSE for details.