creduse 0.1.4

Python SDK for Creduse

Creduse SDK

A Python SDK for interacting with the Creduse credit management API. This SDK allows you to manage credits for end users with operations like adding, subtracting, and checking credit balances.

Installation

pip install creduse

Authentication

The SDK requires an API key for authentication. To get an API key, login to the Creduse dashboard and navigate to the API keys section.

You can provide the API key in two ways:

1. Pass it directly when initializing the client:

from creduse import CreduseClient

client = CreduseClient(api_key="your-api-key")

2. Set it as an environment variable:

export CREDUSE_API_KEY="your-api-key"

from creduse import CreduseClient

client = CreduseClient()  # Will use CREDUSE_API_KEY from environment

Usage

The SDK provides both synchronous and asynchronous clients for interacting with the Creduse API.

Synchronous Client

from creduse import CreduseClient
from uuid import UUID

# Initialize the client
client = CreduseClient(api_key="your-api-key")

# Add credits for an end user
end_user_id = UUID("12345678-1234-5678-1234-567812345678")
add_result = client.add(
    end_user_id=end_user_id,
    amount=100,            # Number of credits to add
    validity_days=31       # How long the credits are valid for (default: 31)
)

# Subtract credits from an end user
subtract_result = client.subtract(
    end_user_id=end_user_id,
    amount=50              # Number of credits to subtract
)

# Start a credit cycle for an end user
start_cycle_result = client.start_cycle(
    end_user_id=end_user_id,
    amount=1000,           # Number of credits for the cycle
    validity_days=31       # How long the cycle is valid for (default: 31)
)

# Stop a credit cycle for an end user
stop_cycle_result = client.stop_cycle(
    end_user_id=end_user_id
)

# Check the active balance for an end user
balance = client.get_balance(
    end_user_id=end_user_id
)
print(f"Current balance: {balance.active_balance}")

Asynchronous Client

import asyncio
from creduse import AsyncCreduseClient
from uuid import UUID

async def manage_credits():
    # Initialize the async client
    client = AsyncCreduseClient(api_key="your-api-key")
    
    # Add credits for an end user
    end_user_id = UUID("12345678-1234-5678-1234-567812345678")
    add_result = await client.add(
        end_user_id=end_user_id,
        amount=100,
        validity_days=31
    )
    
    # Subtract credits
    subtract_result = await client.subtract(
        end_user_id=end_user_id,
        amount=50
    )
    
    # Check balance
    balance = await client.get_balance(
        end_user_id=end_user_id
    )
    print(f"Current balance: {balance.active_balance}")

# Run the async function
asyncio.run(manage_credits())

API Reference

CreduseClient / AsyncCreduseClient

Both clients provide the same methods, with the async client using async/await syntax.

add(end_user_id, amount, validity_days=31)

Add credits to an end user's account.

• end_user_id: UUID4 - The unique identifier for the end user
• amount: int - The number of credits to add (must be positive)
• validity_days: int - How long the credits are valid for (must be positive)

Returns: AddCreditModel

subtract(end_user_id, amount)

Subtract credits from an end user's account.

• end_user_id: UUID4 - The unique identifier for the end user
• amount: int - The number of credits to subtract (must be positive)

Returns: SubtractCreditModel

start_cycle(end_user_id, amount, validity_days=31)

Start a new credit cycle for an end user.

• end_user_id: UUID4 - The unique identifier for the end user
• amount: int - The number of credits for the cycle (must be positive)
• validity_days: int - How long the cycle is valid for (must be positive)

Returns: StartCycleModel / CycleModelResponse

stop_cycle(end_user_id)

Stop an active credit cycle for an end user.

• end_user_id: UUID4 - The unique identifier for the end user

Returns: StopCycleModel / CycleModelResponse

get_balance(end_user_id)

Get the current active balance for an end user.

• end_user_id: UUID4 - The unique identifier for the end user

Returns: ActiveBalance

Error Handling

The SDK validates input parameters and will raise appropriate exceptions:

• ValueError: Raised when invalid parameters are provided (e.g., negative amounts)
• TypeError: Raised when parameters are of the wrong type

API errors will be propagated from the underlying HTTP client.

License

MIT License