# API Reference

This section contains the complete API documentation for zae-limiter, auto-generated from source code docstrings.

## Overview

The main components of the API are:

| Component | Description |
|-----------|-------------|
| [`RateLimiter`](limiter.md#zae_limiter.limiter.RateLimiter) | Async rate limiter client |
| [`SyncRateLimiter`](limiter.md#zae_limiter.limiter.SyncRateLimiter) | Synchronous rate limiter client |
| [`Repository`](repository.md) | DynamoDB data access and infrastructure management |
| [`RepositoryProtocol`](repository.md#repositoryprotocol) | Protocol for pluggable backends |
| [`Limit`](models.md#zae_limiter.models.Limit) | Rate limit configuration |
| [`StackOptions`](models.md#zae_limiter.models.StackOptions) | Infrastructure deployment configuration |
| [`CacheStats`](models.md#zae_limiter.config_cache.CacheStats) | Cache performance statistics |
| [`RateLimitExceeded`](exceptions.md#zae_limiter.exceptions.RateLimitExceeded) | Exception when limit is exceeded |

## Quick Reference

### Creating a Limiter

```python
from zae_limiter import RateLimiter, SyncRateLimiter

# Async
limiter = RateLimiter(
    name="limiter",
    region="us-east-1",
)

# Sync
limiter = SyncRateLimiter(
    name="limiter",
    region="us-east-1",
)
```

### Defining Limits

```python
from zae_limiter import Limit

# Factory methods
Limit.per_second("rps", 10)
Limit.per_minute("rpm", 100)
Limit.per_hour("rph", 1000)
Limit.per_day("rpd", 10000)

# With burst capacity
Limit.per_minute("tpm", 10_000, burst=15_000)

# Custom period
Limit.custom("requests", capacity=50, refill_amount=50, refill_period_seconds=30)
```

### Acquiring Limits

```python
from zae_limiter import RateLimiter, Limit, RateLimitExceeded

limiter = RateLimiter(name="limiter")

try:
    async with limiter.acquire(
        entity_id="user-123",
        resource="api",
        limits=[Limit.per_minute("rpm", 100)],
        consume={"rpm": 1},
    ) as lease:
        # Do work
        await lease.adjust(rpm=5)  # Adjust if needed
except RateLimitExceeded as e:
    print(f"Retry after: {e.retry_after_seconds}s")
```

### Handling Exceptions

```python
from zae_limiter import RateLimitExceeded, RateLimiterUnavailable

try:
    async with limiter.acquire(
        entity_id="user-123",
        resource="gpt-4",
        limits=[Limit.per_minute("rpm", 100)],
        consume={"rpm": 1},
    ):
        pass
except RateLimitExceeded as e:
    # Rate limit exceeded
    print(e.retry_after_seconds)
    print(e.violations)
    print(e.as_dict())
except RateLimiterUnavailable as e:
    # DynamoDB unavailable
    print(f"Service unavailable: {e}")
```

## Module Structure

```
zae_limiter/
├── __init__.py            # Public API exports
├── limiter.py             # RateLimiter, SyncRateLimiter
├── models.py              # Limit, Entity, LimitStatus, BucketState, StackOptions, ...
├── exceptions.py          # RateLimitExceeded, RateLimiterUnavailable, ...
├── repository.py          # Repository (DynamoDB operations)
├── repository_protocol.py # RepositoryProtocol (backend abstraction)
├── lease.py               # Lease, SyncLease context managers
├── config_cache.py        # Client-side config caching with TTL
├── bucket.py              # Token bucket algorithm
├── schema.py              # DynamoDB key builders
├── naming.py              # Resource name validation
├── local.py               # LocalStack management commands
├── cli.py                 # CLI commands
└── infra/
    ├── stack_manager.py   # StackManager (CloudFormation operations)
    ├── lambda_builder.py  # Lambda deployment package builder
    ├── discovery.py       # Multi-stack discovery and listing
    └── cfn_template.yaml  # CloudFormation template
```

## Public Exports

The following are exported from `zae_limiter`:

```python
from zae_limiter import (
    # Version
    __version__,

    # Main classes
    RateLimiter,
    SyncRateLimiter,
    Repository,
    RepositoryProtocol,
    Lease,
    SyncLease,
    StackManager,

    # Models
    Limit,
    LimiterInfo,
    LimitName,
    Entity,
    LimitStatus,
    BucketState,
    UsageSnapshot,
    UsageSummary,
    ResourceCapacity,
    EntityCapacity,
    StackOptions,
    BackendCapabilities,
    Status,
    CacheStats,

    # Audit
    AuditEvent,
    AuditAction,

    # Enums
    OnUnavailable,

    # Exceptions - Base
    ZAELimiterError,

    # Exceptions - Categories
    RateLimitError,
    InfrastructureError,
    EntityError,
    VersionError,

    # Exceptions - Rate Limit
    RateLimitExceeded,

    # Exceptions - Entity
    EntityNotFoundError,
    EntityExistsError,

    # Exceptions - Infrastructure
    RateLimiterUnavailable,
    StackCreationError,
    StackAlreadyExistsError,
    InfrastructureNotFoundError,

    # Exceptions - Version
    VersionMismatchError,
    IncompatibleSchemaError,

    # Exceptions - Validation
    ValidationError,
    InvalidIdentifierError,
    InvalidNameError,
)
```

## Detailed Documentation

- [RateLimiter](limiter.md) - Main rate limiter classes
- [Repository](repository.md) - Data access and infrastructure management
- [Models](models.md) - Data models and configuration
- [Exceptions](exceptions.md) - Exception types and handling
