cheqi-sdk 0.1.0__tar.gz

cheqi_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: python -m pip install --upgrade build
+
+      - name: Build distribution artifacts
+        run: python -m build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

cheqi_sdk-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.env
+.venv/
+venv/
+*.so

cheqi_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: cheqi-sdk
+Version: 0.1.0
+Summary: Cheqi Python SDK for end-to-end encrypted receipt processing
+Author-email: Cheqi <support@cheqi.io>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.5
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Cheqi Python SDK
+
+Python SDK for end-to-end encrypted receipt and credit note processing via the Cheqi API.
+
+## Installation
+
+```bash
+pip install cheqi-sdk
+```
+
+Or with uv:
+
+```bash
+uv add cheqi-sdk
+```
+
+## Quick Start
+
+```python
+from cheqi import CheqiSDK, Environment
+from cheqi.models import (
+    IdentificationDetails,
+    CardDetails,
+    ReceiptTemplateRequest,
+    Product,
+    Tax,
+    UnitCode,
+    PaymentType,
+    CardProvider,
+)
+from decimal import Decimal
+
+# Initialize the SDK
+sdk = CheqiSDK(
+    environment=Environment.PRODUCTION,
+    api_key="sk_live_...",
+)
+
+# Build identification details
+identification = IdentificationDetails(
+    payment_type=PaymentType.CARD_PAYMENT,
+    card_details=CardDetails(
+        payment_account_reference="PAR123456",
+        card_provider=CardProvider.VISA,
+    ),
+)
+
+# Build a receipt request
+product = Product(
+    name="Laptop",
+    identifier="LAP-001",
+    quantity=1.0,
+    base_quantity=1.0,
+    unit_code=UnitCode.ONE,
+    unit_price=Decimal("1000.00"),
+    subtotal=Decimal("1000.00"),
+    total=Decimal("1210.00"),
+    taxes=[Tax(rate=21.0, type="VAT", taxable_amount=Decimal("1000.00"), amount=Decimal("210.00"))],
+)
+
+receipt_request = ReceiptTemplateRequest(
+    document_number="INV-2024-001",
+    currency="EUR",
+    receipt_subtotal=Decimal("1000.00"),
+    total_before_tax=Decimal("1000.00"),
+    total_tax_amount=Decimal("210.00"),
+    total_amount=Decimal("1210.00"),
+    products=[product],
+    taxes=[Tax(rate=21.0, type="VAT", taxable_amount=Decimal("1000.00"), amount=Decimal("210.00"))],
+)
+
+# Process the complete receipt (match -> template -> encrypt -> send)
+result = sdk.receipt_service.process_complete_receipt(
+    identification_details=identification,
+    receipt_request=receipt_request,
+)
+
+if result.success:
+    print(f"Receipt delivered! ID: {result.cheqi_receipt_id}")
+```
+
+## Chainable Model Building
+
+Models are immutable. Convenience methods return new instances:
+
+```python
+request = (
+    ReceiptTemplateRequest(document_number="INV-001", currency="EUR")
+    .add_product(product1)
+    .add_product(product2)
+    .add_tax(tax1)
+    .add_discount(discount1)
+)
+```
+
+## Authentication
+
+Two modes are supported:
+
+```python
+# API Key (for companies accessing their own data)
+sdk = CheqiSDK(
+    environment=Environment.PRODUCTION,
+    api_key="sk_live_...",
+)
+
+# OAuth2 Client Credentials (for third-party integrations)
+sdk = CheqiSDK(
+    environment=Environment.PRODUCTION,
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+)
+# Pass access_token to service methods
+```
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check src/ tests/
+uv run mypy src/
+```

cheqi_sdk-0.1.0/README.md

@@ -0,0 +1,123 @@
+# Cheqi Python SDK
+
+Python SDK for end-to-end encrypted receipt and credit note processing via the Cheqi API.
+
+## Installation
+
+```bash
+pip install cheqi-sdk
+```
+
+Or with uv:
+
+```bash
+uv add cheqi-sdk
+```
+
+## Quick Start
+
+```python
+from cheqi import CheqiSDK, Environment
+from cheqi.models import (
+    IdentificationDetails,
+    CardDetails,
+    ReceiptTemplateRequest,
+    Product,
+    Tax,
+    UnitCode,
+    PaymentType,
+    CardProvider,
+)
+from decimal import Decimal
+
+# Initialize the SDK
+sdk = CheqiSDK(
+    environment=Environment.PRODUCTION,
+    api_key="sk_live_...",
+)
+
+# Build identification details
+identification = IdentificationDetails(
+    payment_type=PaymentType.CARD_PAYMENT,
+    card_details=CardDetails(
+        payment_account_reference="PAR123456",
+        card_provider=CardProvider.VISA,
+    ),
+)
+
+# Build a receipt request
+product = Product(
+    name="Laptop",
+    identifier="LAP-001",
+    quantity=1.0,
+    base_quantity=1.0,
+    unit_code=UnitCode.ONE,
+    unit_price=Decimal("1000.00"),
+    subtotal=Decimal("1000.00"),
+    total=Decimal("1210.00"),
+    taxes=[Tax(rate=21.0, type="VAT", taxable_amount=Decimal("1000.00"), amount=Decimal("210.00"))],
+)
+
+receipt_request = ReceiptTemplateRequest(
+    document_number="INV-2024-001",
+    currency="EUR",
+    receipt_subtotal=Decimal("1000.00"),
+    total_before_tax=Decimal("1000.00"),
+    total_tax_amount=Decimal("210.00"),
+    total_amount=Decimal("1210.00"),
+    products=[product],
+    taxes=[Tax(rate=21.0, type="VAT", taxable_amount=Decimal("1000.00"), amount=Decimal("210.00"))],
+)
+
+# Process the complete receipt (match -> template -> encrypt -> send)
+result = sdk.receipt_service.process_complete_receipt(
+    identification_details=identification,
+    receipt_request=receipt_request,
+)
+
+if result.success:
+    print(f"Receipt delivered! ID: {result.cheqi_receipt_id}")
+```
+
+## Chainable Model Building
+
+Models are immutable. Convenience methods return new instances:
+
+```python
+request = (
+    ReceiptTemplateRequest(document_number="INV-001", currency="EUR")
+    .add_product(product1)
+    .add_product(product2)
+    .add_tax(tax1)
+    .add_discount(discount1)
+)
+```
+
+## Authentication
+
+Two modes are supported:
+
+```python
+# API Key (for companies accessing their own data)
+sdk = CheqiSDK(
+    environment=Environment.PRODUCTION,
+    api_key="sk_live_...",
+)
+
+# OAuth2 Client Credentials (for third-party integrations)
+sdk = CheqiSDK(
+    environment=Environment.PRODUCTION,
+    client_id="your_client_id",
+    client_secret="your_client_secret",
+)
+# Pass access_token to service methods
+```
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run pytest
+uv run ruff check src/ tests/
+uv run mypy src/
+```

cheqi_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cheqi-sdk"
+version = "0.1.0"
+description = "Cheqi Python SDK for end-to-end encrypted receipt processing"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+    { name = "Cheqi", email = "support@cheqi.io" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.5",
+    "cryptography>=42.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-httpx>=0.30",
+    "pytest-cov>=4.0",
+    "mypy>=1.0",
+    "ruff>=0.4",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cheqi"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true
+plugins = ["pydantic.mypy"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

cheqi_sdk-0.1.0/src/cheqi/__init__.py

@@ -0,0 +1,26 @@
+"""Cheqi Python SDK for end-to-end encrypted receipt processing."""
+
+from cheqi.config import CheqiSDKConfig, Environment
+from cheqi.exceptions import (
+    CheqiApiError,
+    CheqiSDKError,
+    CreditNoteProcessingError,
+    DecryptionError,
+    EncryptionError,
+    ErrorCodes,
+    ReceiptProcessingError,
+)
+from cheqi.sdk import CheqiSDK
+
+__all__ = [
+    "CheqiSDK",
+    "CheqiSDKConfig",
+    "Environment",
+    "CheqiSDKError",
+    "CheqiApiError",
+    "EncryptionError",
+    "DecryptionError",
+    "ReceiptProcessingError",
+    "CreditNoteProcessingError",
+    "ErrorCodes",
+]

cheqi_sdk-0.1.0/src/cheqi/config.py

@@ -0,0 +1,104 @@
+"""SDK configuration and environment definitions."""
+
+from __future__ import annotations
+
+import logging
+from enum import Enum
+from typing import Optional
+
+logger = logging.getLogger("cheqi.config")
+
+
+class Environment(str, Enum):
+    """Predefined Cheqi API environments."""
+
+    SANDBOX = "https://sandbox.api.cheqi.io"
+    PRODUCTION = "https://api.cheqi.io"
+
+    @property
+    def base_url(self) -> str:
+        return self.value
+
+
+class CheqiSDKConfig:
+    """Immutable SDK configuration.
+
+    Supports two authentication modes:
+    - API key: Bearer token (starts with sk_live_ or sk_test_)
+    - OAuth2: Client credentials (client_id + client_secret)
+    """
+
+    def __init__(
+        self,
+        *,
+        environment: Optional[Environment] = None,
+        custom_api_endpoint: Optional[str] = None,
+        api_key: Optional[str] = None,
+        client_id: Optional[str] = None,
+        client_secret: Optional[str] = None,
+        private_key: Optional[str] = None,
+        timeout_seconds: int = 30,
+        max_retries: int = 3,
+    ) -> None:
+        # Resolve API endpoint
+        if custom_api_endpoint:
+            self._api_endpoint = custom_api_endpoint
+        elif environment:
+            self._api_endpoint = environment.base_url
+        else:
+            raise ValueError("Either 'environment' or 'custom_api_endpoint' must be provided")
+
+        self._api_key = api_key
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._private_key = private_key
+
+        if timeout_seconds <= 0:
+            raise ValueError(f"Timeout must be positive, got: {timeout_seconds}")
+        self._timeout_seconds = timeout_seconds
+
+        if max_retries < 0:
+            raise ValueError(f"Max retries cannot be negative, got: {max_retries}")
+        self._max_retries = max_retries
+
+        # Warn if no auth configured
+        has_api_key = bool(api_key and api_key.strip())
+        has_credentials = bool(client_id and client_id.strip() and client_secret and client_secret.strip())
+
+        if not has_api_key and not has_credentials:
+            logger.warning("No authentication configured. API calls will fail unless access tokens are provided.")
+
+        if has_api_key and not self._is_valid_api_key_format(api_key):  # type: ignore[arg-type]
+            logger.warning("API key does not match expected format (sk_live_* or sk_test_*)")
+
+    @staticmethod
+    def _is_valid_api_key_format(key: str) -> bool:
+        return key.startswith("sk_live_") or key.startswith("sk_test_")
+
+    @property
+    def api_endpoint(self) -> str:
+        return self._api_endpoint
+
+    @property
+    def api_key(self) -> Optional[str]:
+        return self._api_key
+
+    @property
+    def client_id(self) -> Optional[str]:
+        return self._client_id
+
+    @property
+    def client_secret(self) -> Optional[str]:
+        return self._client_secret
+
+    @property
+    def private_key(self) -> Optional[str]:
+        return self._private_key
+
+    @property
+    def timeout_seconds(self) -> int:
+        return self._timeout_seconds
+
+    @property
+    def max_retries(self) -> int:
+        return self._max_retries

cheqi_sdk-0.1.0/src/cheqi/exceptions.py

@@ -0,0 +1,82 @@
+"""Exception hierarchy for the Cheqi SDK."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class ErrorCodes:
+    """Standard error codes used across the SDK."""
+
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+    AUTHENTICATION_FAILED = "AUTHENTICATION_FAILED"
+    AUTHORIZATION_FAILED = "AUTHORIZATION_FAILED"
+    CUSTOMER_NOT_FOUND = "CUSTOMER_NOT_FOUND"
+    RECEIPT_NOT_FOUND = "RECEIPT_NOT_FOUND"
+    ENCRYPTION_ERROR = "ENCRYPTION_ERROR"
+    DECRYPTION_ERROR = "DECRYPTION_ERROR"
+    NETWORK_ERROR = "NETWORK_ERROR"
+    RATE_LIMITED = "RATE_LIMITED"
+    SERVER_ERROR = "SERVER_ERROR"
+    INVALID_RESPONSE = "INVALID_RESPONSE"
+
+
+class CheqiSDKError(Exception):
+    """Base exception for all Cheqi SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        error_code: str = ErrorCodes.UNKNOWN_ERROR,
+        http_status_code: int = 0,
+        correlation_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.error_code = error_code
+        self.http_status_code = http_status_code
+        self.correlation_id = correlation_id
+
+
+class CheqiApiError(CheqiSDKError):
+    """Exception for HTTP/API communication errors."""
+
+    def __init__(
+        self,
+        message: str,
+        error_code: str = ErrorCodes.UNKNOWN_ERROR,
+        http_status_code: int = 0,
+        correlation_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message, error_code, http_status_code, correlation_id)
+
+    @property
+    def is_retryable(self) -> bool:
+        """Whether this error can be retried."""
+        return self.http_status_code in (408, 429) or 500 <= self.http_status_code < 600
+
+
+class EncryptionError(CheqiSDKError):
+    """Exception for encryption failures."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, ErrorCodes.ENCRYPTION_ERROR)
+
+
+class DecryptionError(CheqiSDKError):
+    """Exception for decryption failures."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, ErrorCodes.DECRYPTION_ERROR)
+
+
+class ReceiptProcessingError(CheqiSDKError):
+    """Exception for receipt processing failures."""
+
+    pass
+
+
+class CreditNoteProcessingError(CheqiSDKError):
+    """Exception for credit note processing failures."""
+
+    pass