qbitflow 1.0.0__py3-none-any.whl

qbitflow/__init__.py

@@ -0,0 +1,37 @@
+
+"""
+QBitFlow Python SDK
+===================
+
+A Python SDK for QBitFlow - Next Generation Crypto Payment Processing.
+
+This SDK provides a simple and intuitive interface for:
+- Processing one-time cryptocurrency payments
+- Managing recurring subscriptions
+- Handling pay-as-you-go subscriptions
+- Managing customers and products
+- Tracking transaction statuses
+
+Basic Usage
+-----------
+>>> from qbitflow import QBitFlow
+>>> client = QBitFlow(api_key="your_api_key_here")
+>>> 
+>>> # Create a one-time payment session
+>>> response = client.one_time_payments.create_session(
+...     product_id=1,
+...     customer_uuid="customer-uuid-here"
+... )
+>>> print(response.link)  # Send this link to your customer
+
+For more examples, see the documentation at https://qbitflow.app/docs
+"""
+
+from .client import QBitFlow
+from . import dto
+from . import exceptions
+from .utils.duration import Duration
+
+__version__ = "1.0.0"
+__author__ = "QBitFlow"
+__all__ = ["QBitFlow", "dto", "exceptions", "Duration"]

qbitflow/client.py

@@ -0,0 +1,118 @@
+"""
+QBitFlow SDK main client.
+
+This module provides the main QBitFlow client class for interacting with the API.
+"""
+
+from typing import Optional
+
+from .requests.customer import CustomerRequests
+from .requests.product import ProductRequests
+from .requests.user import UserRequests
+from .requests.api_key import ApiKeyRequests
+from .requests.transaction.payment import PaymentRequests
+from .requests.transaction.subscription import SubscriptionRequests
+from .requests.transaction.payg import PayAsYouGoSubscriptionRequests
+from .requests.transaction.status import TransactionStatusRequests
+
+
+class QBitFlow:
+    """
+    Main client for interacting with the QBitFlow API.
+    
+    This class provides access to all QBitFlow API functionality through
+    organized request handlers for different resource types.
+    
+    Attributes:
+        api_key: API key used for authentication.
+        customers: Handler for customer-related operations.
+        products: Handler for product-related operations.
+        users: Handler for user-related operations.
+        api_keys: Handler for API key management.
+        transaction_status: Handler for checking transaction statuses.
+        one_time_payments: Handler for one-time payment operations.
+        subscriptions: Handler for recurring subscription operations.
+        pay_as_you_go: Handler for pay-as-you-go subscription operations.
+    
+    Example:
+        >>> from qbitflow import QBitFlow
+        >>> 
+        >>> # Initialize the client
+        >>> client = QBitFlow(api_key="your_api_key_here")
+        >>> 
+        >>> # Create a one-time payment
+        >>> response = client.one_time_payments.create_session(
+        ...     product_id=1,
+        ...     customer_uuid="customer-uuid",
+        ...     webhook_url="https://example.com/webhook"
+        ... )
+        >>> print(f"Payment link: {response.link}")
+        >>> 
+        >>> # Create a subscription
+        >>> from qbitflow import Duration
+        >>> response = client.subscriptions.create_session(
+        ...     product_id=1,
+        ...     frequency=Duration(value=1, unit="months"),
+        ...     customer_uuid="customer-uuid"
+        ... )
+        >>> print(f"Subscription link: {response.link}")
+        >>> 
+        >>> # Check transaction status
+        >>> from qbitflow.dto.transaction.status import TransactionType
+        >>> status = client.transaction_status.get(
+        ...     "transaction-uuid",
+        ...     TransactionType.ONE_TIME_PAYMENT
+        ... )
+        >>> print(f"Status: {status.status.value}")
+    """
+    
+    def __init__(
+        self,
+        api_key: str,
+        timeout: Optional[int] = None,
+        max_retries: Optional[int] = None
+    ):
+        """
+        Initialize the QBitFlow client.
+        
+        Args:
+            api_key: Your QBitFlow API key. Get this from your dashboard.
+            timeout: Optional request timeout in seconds (default: 30).
+            max_retries: Optional maximum retry attempts (default: 3).
+        
+        Raises:
+            ValueError: If api_key is empty or None.
+        
+        Example:
+            >>> # Basic initialization
+            >>> client = QBitFlow(api_key="your_api_key_here")
+            >>> 
+            >>> # With custom timeout and retries
+            >>> client = QBitFlow(
+            ...     api_key="your_api_key_here",
+            ...     timeout=60,
+            ...     max_retries=5
+            ... )
+        """
+        if not api_key:
+            raise ValueError("API key is required")
+        
+        self.api_key = api_key
+        self._timeout = timeout
+        self._max_retries = max_retries
+        
+        # Initialize request handlers
+        self.customers = CustomerRequests(api_key, timeout, max_retries)
+        self.products = ProductRequests(api_key, timeout, max_retries)
+        self.users = UserRequests(api_key, timeout, max_retries)
+        self.api_keys = ApiKeyRequests(api_key, timeout, max_retries)
+        
+        # Transaction-related handlers
+        self.transaction_status = TransactionStatusRequests(api_key, timeout, max_retries)
+        self.one_time_payments = PaymentRequests(api_key, timeout, max_retries)
+        self.subscriptions = SubscriptionRequests(api_key, timeout, max_retries)
+        self.pay_as_you_go = PayAsYouGoSubscriptionRequests(api_key, timeout, max_retries)
+    
+    def __repr__(self) -> str:
+        """Return a string representation of the client."""
+        return f"QBitFlow(api_key='***{self.api_key[-4:]}')"

qbitflow/config.py

@@ -0,0 +1,55 @@
+
+"""
+Configuration module for QBitFlow SDK.
+
+This module contains configuration settings for the SDK including API base URLs
+and other global settings.
+"""
+
+from typing import Optional
+import os
+
+# Default base URL for QBitFlow API
+# Can be overridden by setting QBITFLOW_BASE_URL environment variable
+BASE_URL: str = os.getenv("QBITFLOW_BASE_URL", "https://api.qbitflow.app/v1")
+
+# API version
+API_VERSION: str = "v1"
+
+# Request timeout in seconds
+DEFAULT_TIMEOUT: int = 30
+
+# Maximum retry attempts for failed requests
+MAX_RETRIES: int = 3
+
+
+def set_base_url(url: str) -> None:
+    """
+    Set the base URL for API requests.
+    
+    This is useful for testing or when using a different API endpoint.
+    
+    Args:
+        url: The base URL to use for all API requests.
+        
+    Example:
+        >>> from qbitflow import config
+        >>> config.set_base_url("http://localhost:3001")
+    """
+    global BASE_URL
+    BASE_URL = url
+
+
+def get_base_url() -> str:
+    """
+    Get the current base URL for API requests.
+    
+    Returns:
+        The current base URL.
+        
+    Example:
+        >>> from qbitflow import config
+        >>> print(config.get_base_url())
+        https://api.qbitflow.app
+    """
+    return BASE_URL

qbitflow/dto/__init__.py

@@ -0,0 +1,32 @@
+
+"""
+Data Transfer Objects (DTOs) for QBitFlow SDK.
+
+This package contains all the data models used throughout the SDK for
+representing API requests and responses.
+"""
+
+from .base_model import BaseModel
+from . import transaction
+from .customer import Customer, CreateCustomerDto, UpdateCustomerDto
+from .product import Product, CreateProductDto, UpdateProductDto
+from .user import User, UserRole, CreateUserDto, UpdateUserDto
+from .api_key import ApiKey, CreateApiKeyDto, CreatedKeyResponse
+
+__all__ = [
+    "BaseModel",
+    "transaction",
+    "Customer",
+    "CreateCustomerDto",
+    "UpdateCustomerDto",
+    "Product",
+    "CreateProductDto",
+    "UpdateProductDto",
+    "User",
+    "UserRole",
+    "CreateUserDto",
+    "UpdateUserDto",
+    "ApiKey",
+    "CreateApiKeyDto",
+    "CreatedKeyResponse",
+]

qbitflow/dto/api_key.py

@@ -0,0 +1,91 @@
+
+"""
+API key-related data models.
+
+This module contains data models for API key management operations.
+"""
+
+from datetime import datetime
+from typing import Optional
+from pydantic import Field
+
+from .base_model import BaseModel
+from .user import UserRole
+
+
+class ApiKey(BaseModel):
+    """
+    Represents an API key in the QBitFlow system.
+    
+    API keys are used to authenticate requests to the QBitFlow API.
+    
+    Attributes:
+        id: Unique identifier for the API key.
+        name: Descriptive name for the API key.
+        organization_id: ID of the organization this key belongs to.
+        user_id: ID of the user who created this key.
+        created_at: Timestamp when the key was created.
+        expires_at: Optional expiration timestamp.
+        role: Role associated with this API key.
+        test: Whether this is a test mode API key.
+    
+    Example:
+        >>> api_key = client.api_keys.get(1)
+        >>> print(f"{api_key.name} - Test: {api_key.test}")
+    """
+    
+    id: int = Field(..., description="Unique identifier for the API key")
+    name: str = Field(..., description="Descriptive name for the API key")
+    organization_id: int = Field(..., description="Organization ID")
+    user_id: int = Field(..., description="User ID who created the key")
+    created_at: datetime = Field(..., description="Creation timestamp")
+    expires_at: Optional[datetime] = Field(default=None, description="Expiration timestamp")
+    role: UserRole = Field(..., description="Role associated with the key")
+    test: bool = Field(..., description="Whether this is a test mode key")
+
+
+class CreateApiKeyDto(BaseModel):
+    """
+    Data transfer object for creating a new API key.
+    
+    Attributes:
+        name: Descriptive name for the API key (required).
+        user_id: ID of the user creating the key (required).
+        expires_at: Optional expiration timestamp.
+        role: Role to associate with the key (required).
+        test: Whether this should be a test mode key (required).
+    
+    Example:
+        >>> new_key = CreateApiKeyDto(
+        ...     name="Production API Key",
+        ...     user_id=1,
+        ...     role=UserRole.ADMIN,
+        ...     test=False
+        ... )
+        >>> api_key = client.api_keys.create(new_key)
+    """
+    
+    name: str = Field(..., min_length=1, description="Descriptive name for the API key")
+    user_id: int = Field(..., gt=0, description="User ID creating the key")
+    expires_at: Optional[datetime] = Field(default=None, description="Expiration timestamp")
+    test: bool = Field(..., description="Whether this is a test mode key")
+
+
+class CreatedKeyResponse(BaseModel):
+    """
+        Response when a new API key is created.
+        
+        This contains the actual API key value which is only shown once during creation.
+        
+        Attributes:
+            data: The created API key information.
+            key: The actual API key value (only shown once).
+        
+        Example:
+            >>> response = client.api_keys.create(new_key_dto)
+            >>> print(f"Save this key: {response.key}")
+            >>> print(f"Key ID: {response.data.id}")
+        """
+    
+    data: ApiKey = Field(..., description="Created API key information")
+    key: str = Field(..., description="The actual API key value (only shown once)")

qbitflow/dto/base_model.py

@@ -0,0 +1,44 @@
+
+"""
+Base model for all DTOs in QBitFlow SDK.
+
+This module provides a base Pydantic model with common configuration
+for automatic camelCase/snake_case conversion.
+"""
+
+from pydantic import BaseModel as PydanticBaseModel, ConfigDict
+from qbitflow.utils.helpers import snake_to_camel_case
+
+
+class BaseModel(PydanticBaseModel):
+    """
+    Base model with common configuration for all DTOs.
+    
+    This model automatically handles conversion between Python's snake_case
+    convention and the API's camelCase convention.
+    
+    Features:
+        - Automatic camelCase to snake_case conversion for incoming data
+        - Automatic snake_case to camelCase conversion for outgoing data
+        - Support for both naming conventions when loading data
+    """
+    
+    model_config = ConfigDict(
+        populate_by_name=True,  # Allow both camelCase and snake_case
+        alias_generator=snake_to_camel_case,  # Generate camelCase aliases
+        use_enum_values=True,  # Use enum values instead of enum objects
+    )
+    
+    def model_dump(self, *args, **kwargs):
+        """
+        Serialize the model to a dictionary with camelCase keys.
+        
+        Args:
+            *args: Positional arguments to pass to parent method.
+            **kwargs: Keyword arguments to pass to parent method.
+            
+        Returns:
+            Dictionary representation of the model with camelCase keys.
+        """
+        kwargs['by_alias'] = True
+        return super().model_dump(*args, **kwargs)

qbitflow/dto/customer.py

@@ -0,0 +1,106 @@
+
+"""
+Customer-related data models.
+
+This module contains data models for customer management operations.
+"""
+
+from datetime import datetime
+from typing import Optional
+from pydantic import Field, EmailStr
+
+from .base_model import BaseModel
+
+
+class Customer(BaseModel):
+    """
+    Represents a customer in the QBitFlow system.
+    
+    Customers are individuals or entities that make payments through your platform.
+    Each customer has a unique UUID and contact information.
+    
+    Attributes:
+        uuid: Unique identifier for the customer.
+        name: Customer's first name.
+        last_name: Customer's last name.
+        email: Customer's email address.
+        phone_number: Optional phone number.
+        address: Optional physical address.
+        reference: Optional external reference ID for your records.
+        created_at: Timestamp when the customer was created.
+    
+    Example:
+        >>> customer = client.customers.get("customer-uuid")
+        >>> print(f"{customer.name} {customer.last_name}")
+        >>> print(f"Email: {customer.email}")
+    """
+    
+    uuid: str = Field(..., description="Unique identifier for the customer")
+    name: str = Field(..., description="Customer's first name")
+    last_name: str = Field(..., description="Customer's last name")
+    email: EmailStr = Field(..., description="Customer's email address")
+    phone_number: Optional[str] = Field(default=None, description="Customer's phone number")
+    address: Optional[str] = Field(default=None, description="Customer's physical address")
+    reference: Optional[str] = Field(default=None, description="External reference ID")
+    created_at: datetime = Field(..., description="Creation timestamp")
+
+
+class CreateCustomerDto(BaseModel):
+    """
+    Data transfer object for creating a new customer.
+    
+    Use this model to provide customer information when creating a new customer.
+    
+    Attributes:
+        name: Customer's first name (required).
+        last_name: Customer's last name (required).
+        email: Customer's email address (required).
+        phone_number: Optional phone number.
+        address: Optional physical address.
+        reference: Optional external reference ID for your records.
+    
+    Example:
+        >>> new_customer = CreateCustomerDto(
+        ...     name="John",
+        ...     last_name="Doe",
+        ...     email="john@example.com",
+        ...     phone_number="+1234567890",
+        ...     reference="CRM-12345"
+        ... )
+        >>> customer = client.customers.create(new_customer)
+    """
+    
+    name: str = Field(..., min_length=1, description="Customer's first name")
+    last_name: str = Field(..., min_length=1, description="Customer's last name")
+    email: EmailStr = Field(..., description="Customer's email address")
+    phone_number: Optional[str] = Field(default=None, description="Customer's phone number")
+    address: Optional[str] = Field(default=None, description="Customer's physical address")
+    reference: Optional[str] = Field(default=None, description="External reference ID")
+
+
+class UpdateCustomerDto(BaseModel):
+    """
+    Data transfer object for updating an existing customer.
+    
+    All fields are optional - only provide the fields you want to update.
+    
+    Attributes:
+        name: New first name.
+        last_name: New last name.
+        email: New email address.
+        phone_number: New phone number.
+        address: New physical address.
+    
+    Example:
+        >>> update_data = UpdateCustomerDto(
+        ...     email="newemail@example.com",
+        ...     phone_number="+9876543210"
+        ... )
+        >>> customer = client.customers.update("customer-uuid", update_data)
+    """
+    
+    name: Optional[str] = Field(..., min_length=1, description="Customer's first name")
+    last_name: Optional[str] = Field(..., min_length=1, description="Customer's last name")
+    email: Optional[EmailStr] = Field(..., description="Customer's email address")
+    phone_number: Optional[str] = Field(default=None, description="Customer's phone number")
+    address: Optional[str] = Field(default=None, description="Customer's physical address")

qbitflow/dto/product.py

@@ -0,0 +1,108 @@
+
+"""
+Product-related data models.
+
+This module contains data models for product management operations.
+"""
+
+from datetime import datetime
+from typing import Optional
+from pydantic import Field, field_validator
+
+from .base_model import BaseModel
+
+
+class Product(BaseModel):
+    """
+    Represents a product in the QBitFlow system.
+    
+    Products are items or services that customers can purchase through
+    one-time payments or subscriptions.
+    
+    Attributes:
+        id: Unique identifier for the product.
+        name: Product name.
+        description: Product description.
+        price: Price in USD.
+        reference: Optional external reference ID for your records.
+        created_at: Timestamp when the product was created.
+        is_active: Whether the product is currently active.
+    
+    Example:
+        >>> product = client.products.get(1)
+        >>> print(f"{product.name}: ${product.price}")
+        >>> print(f"Active: {product.is_active}")
+    """
+    
+    id: int = Field(..., description="Unique identifier for the product")
+    name: str = Field(..., description="Product name")
+    description: str = Field(..., description="Product description")
+    price: float = Field(..., ge=0, description="Price in USD")
+    reference: Optional[str] = Field(default=None, description="External reference ID")
+    created_at: datetime = Field(..., description="Creation timestamp")
+    is_active: bool = Field(..., description="Whether the product is active")
+
+
+class CreateProductDto(BaseModel):
+    """
+    Data transfer object for creating a new product.
+    
+    Attributes:
+        name: Product name (required).
+        description: Product description (required).
+        price: Price in USD (required, must be non-negative).
+        reference: Optional external reference ID for your records.
+    
+    Example:
+        >>> new_product = CreateProductDto(
+        ...     name="Premium Subscription",
+        ...     description="Access to all premium features",
+        ...     price=29.99,
+        ...     reference="PROD-PREMIUM"
+        ... )
+        >>> product = client.products.create(new_product)
+    """
+    
+    name: str = Field(..., min_length=1, description="Product name")
+    description: str = Field(..., min_length=1, description="Product description")
+    price: float = Field(..., ge=0, description="Price in USD")
+    reference: Optional[str] = Field(default=None, description="External reference ID")
+    
+    @field_validator('price')
+    @classmethod
+    def validate_price(cls, v: float) -> float:
+        """Validate that price is non-negative."""
+        if v < 0:
+            raise ValueError("Price must be non-negative")
+        return v
+
+
+class UpdateProductDto(BaseModel):
+    """
+    Data transfer object for updating an existing product.
+    
+    Attributes:
+        name: New product name (required).
+        description: New product description (required).
+        price: New price in USD (required, must be non-negative).
+    
+    Example:
+        >>> update_data = UpdateProductDto(
+        ...     name="Premium Plus Subscription",
+        ...     description="Updated description",
+        ...     price=39.99
+        ... )
+        >>> product = client.products.update(1, update_data)
+    """
+    
+    name: str = Field(..., min_length=1, description="Product name")
+    description: str = Field(..., min_length=1, description="Product description")
+    price: float = Field(..., ge=0, description="Price in USD")
+    
+    @field_validator('price')
+    @classmethod
+    def validate_price(cls, v: float) -> float:
+        """Validate that price is non-negative."""
+        if v < 0:
+            raise ValueError("Price must be non-negative")
+        return v

qbitflow/dto/transaction/__init__.py

@@ -0,0 +1,50 @@
+
+"""
+Transaction-related data models.
+
+This package contains data models for payment transactions, subscriptions,
+and related operations.
+"""
+
+from .currency import Currency
+from .payment import Payment, CombinedPayment
+from .session import (
+    Session,
+    SubscriptionOptions,
+    CreateSessionDto,
+    CreateSubscriptionOptions,
+    LinkResponse,
+    StatusLinkResponse,
+    SessionWebhookResponse,
+)
+from .status import (
+    TransactionType,
+    TransactionStatusValue,
+    TransactionStatus,
+    StatusResponseError,
+)
+from .subscription import (
+    Subscription,
+    SubscriptionStatus,
+    PayAsYouGoSubscription,
+)
+
+__all__ = [
+    "Currency",
+    "Payment",
+    "CombinedPayment",
+    "Session",
+    "SubscriptionOptions",
+    "CreateSessionDto",
+    "CreateSubscriptionOptions",
+    "LinkResponse",
+    "StatusLinkResponse",
+    "SessionWebhookResponse",
+    "TransactionType",
+    "TransactionStatusValue",
+    "TransactionStatus",
+    "StatusResponseError",
+    "Subscription",
+    "SubscriptionStatus",
+    "PayAsYouGoSubscription",
+]

qbitflow/dto/transaction/currency.py

@@ -0,0 +1,44 @@
+
+"""
+Currency-related data models.
+
+This module contains data models for cryptocurrency information.
+"""
+
+from typing import Optional
+from pydantic import Field
+
+from qbitflow.dto.base_model import BaseModel
+
+
+class Currency(BaseModel):
+    """
+    Represents a cryptocurrency that can be used for payments.
+    
+    Currencies define the supported cryptocurrencies that customers can use
+    to complete payments.
+    
+    Attributes:
+        id: Unique identifier for the currency.
+        name: Currency name (e.g., "Bitcoin", "Ethereum").
+        symbol: Currency symbol (e.g., "BTC", "ETH").
+        decimals: Number of decimal places for this currency.
+        address: Smart contract address or blockchain identifier.
+        main_currency_id: ID of the main currency if this is a variant.
+        main_currency: Reference to the main currency object if applicable.
+        test: Whether this is a test mode currency.
+    
+    Example:
+        >>> session = client.one_time_payments.get_session("session-uuid")
+        >>> for currency in session.available_currencies:
+        ...     print(f"{currency.name} ({currency.symbol})")
+    """
+    
+    id: int = Field(..., description="Unique identifier for the currency")
+    name: str = Field(..., description="Currency name")
+    symbol: str = Field(..., description="Currency symbol")
+    decimals: int = Field(..., ge=0, description="Number of decimal places")
+    address: str = Field(..., description="Smart contract address or blockchain identifier")
+    main_currency_id: Optional[int] = Field(default=None, description="ID of main currency if variant")
+    main_currency: Optional["Currency"] = Field(default=None, description="Main currency reference")
+    test: bool = Field(..., description="Whether this is a test mode currency")