Metadata-Version: 2.4
Name: helloledger
Version: 0.1.0
Summary: Official Python SDK for HelloLedger API
Author-email: HelloLedger <support@helloledger.ai>
License: MIT
Project-URL: Homepage, https://helloledger.ai
Project-URL: Documentation, https://docs.helloledger.ai
Project-URL: Repository, https://github.com/helloledger/helloledger-python
Project-URL: Issues, https://github.com/helloledger/helloledger-python/issues
Keywords: helloledger,accounting,finance,api,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# HelloLedger Python SDK

Official Python SDK for the HelloLedger API. This SDK enables developers to integrate HelloLedger programmatically using API keys.

## Installation

```bash
pip install helloledger
```

## Quick Start

```python
from helloledger import HelloLedger

# Initialize the client with your API credentials
client = HelloLedger(
    client_id="hl_live_abc123",
    secret_token="sk_live_xyz789",
    api_base="https://hlapi.azurewebsites.net"  # Optional, defaults to production
)

# List all companies accessible by your API key
companies = client.companies.list()

# Get a specific company
company = client.companies.get(company_id=123)

# List transactions for a company
transactions = client.transactions.list(company_id=123)

# Optional: Filter transactions by date
transactions = client.transactions.list(
    company_id=123,
    start_date="2025-01-01",
    end_date="2025-12-31"
)
```

## Authentication

The SDK uses HTTP Basic Authentication with your API key credentials. You need to:

1. Sign up for a HelloLedger account
2. Generate an API key (client_id + secret_token)
3. Initialize the client with your credentials

**Important**: Keep your `secret_token` secure and never commit it to version control.

## Error Handling

The SDK raises custom exceptions for different error scenarios:

```python
from helloledger import HelloLedger
from helloledger.exceptions import (
    AuthenticationError,
    PermissionError,
    NotFoundError,
    APIError
)

client = HelloLedger(client_id="...", secret_token="...")

try:
    company = client.companies.get(company_id=123)
except NotFoundError:
    print("Company not found or not accessible")
except PermissionError:
    print("Your API key doesn't have access to this company")
except AuthenticationError:
    print("Invalid API credentials")
except APIError as e:
    print(f"API error: {e.message} (Status: {e.status_code})")
```

## Available Methods (Phase 1 - MVP)

### Companies

- `client.companies.list()` - List all accessible companies
- `client.companies.get(company_id)` - Get a specific company

### Transactions

- `client.transactions.list(company_id, **kwargs)` - List transactions for a company
  - Optional parameters: `start_date`, `end_date`, `limit`, `offset`

## Context Manager

You can use the client as a context manager to ensure proper cleanup:

```python
with HelloLedger(client_id="...", secret_token="...") as client:
    companies = client.companies.list()
    # Client is automatically closed when exiting the context
```

## Requirements

- Python 3.8+
- httpx >= 0.24.0

## License

MIT

## Support

For issues, questions, or feature requests, please visit:
- Documentation: https://docs.helloledger.ai
- Issues: https://github.com/helloledger/helloledger-python/issues
