Metadata-Version: 2.4
Name: janus-ledger
Version: 0.1.1
Summary: Python gRPC client for Janus
Requires-Python: >=3.11
Requires-Dist: grpcio>=1.60.0
Requires-Dist: protobuf>=4.25.0
Provides-Extra: dev
Requires-Dist: grpcio-tools>=1.60.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# janus-ledger

Python gRPC client for the Janus double-entry accounting engine.

## Install

```bash
pip install janus-ledger
```

## Quick Start

```python
from janus import Janus

ledger = Janus(server_url="your-janus-server:50051")

# Create an entity — every book belongs to an entity
entity = ledger.create_entity(external_id="org-1", name="Acme Corp")

# Create books
ledger.create_book(name="Cash", book_type="asset", currency="USD", entity_external_id="org-1")
ledger.create_book(name="Revenue", book_type="liability", currency="USD", entity_external_id="org-1")

entry = ledger.create_journal_entry(
    idempotency_key="sale-001",
    book_entries=[
        {"book": "cash", "debit": 10000},
        {"book": "revenue", "credit": 10000},
    ],
)

balance = ledger.get_balance("cash")
print(f"Cash balance: {balance.balance} {balance.currency}")
# => Cash balance: 10000 USD
```

## Configuration

| Parameter | Description |
|-----------|-------------|
| `server_url` | gRPC server address (e.g., `your-janus-server:50051`) |

## API Reference

### `Janus(server_url)`

Create a client connected to your Janus server.

### Entities

| Method | Description |
|--------|-------------|
| `create_entity(external_id, name, description?, metadata?)` | Create a new entity. Returns `Entity`. |
| `get_entity(external_id_or_id)` | Get an entity by external ID or UUID. Returns `Entity` or `None`. |
| `list_entities()` | List all entities. Returns `list[Entity]`. |

### Books

| Method | Description |
|--------|-------------|
| `create_book(name, book_type, currency, entity_external_id, metadata?)` | Create a new book. Returns `Book`. |
| `get_book(type_or_id)` | Get a book by type or ID. Returns `Book` or `None`. |
| `list_books(book_type?, limit?, offset?)` | List books with optional filters. Returns `list[Book]`. |

### Journal Entries

| Method | Description |
|--------|-------------|
| `create_journal_entry(idempotency_key, book_entries, ...)` | Create a journal entry. Returns `JournalEntry`. |
| `reverse_journal_entry(entry_id, idempotency_key, reason?)` | Reverse a journal entry. Returns `JournalEntry`. |
| `get_journal_entry(entry_id)` | Get a journal entry by ID. Returns `JournalEntry` or `None`. |
| `get_journal_entry_by_key(idempotency_key)` | Get by idempotency key. Returns `JournalEntry` or `None`. |

### Balances

| Method | Description |
|--------|-------------|
| `get_balance(book, as_of?)` | Get the balance of a book. Returns `BalanceResult`. |
| `get_balances(books, as_of?)` | Get balances for multiple books. Returns `list[BalanceResult]`. |

## License

MIT
