Source code for limitry.client.resources.track

"""Auto-generated operation classes.

This file is auto-generated by the operators generator.
Do not edit this file manually.
"""

from typing import TYPE_CHECKING, Any, Dict, List, Optional

from limitry.client.types import (
    TrackPostRequest,
    TrackPostResponse
)
from limitry.client.utils.pagination import PaginatedResponse

if TYPE_CHECKING:
    from limitry.client.client import Client




class Track:
    """Operations for track."""



    def __init__(self, client: "Client") -> None:
        """Initialize Track operations.

        Args:
            client: The Limitry client instance
        """
        self._client = client




    async def usage(
        self,
        request: TrackPostRequest
    ) -> TrackPostResponse:
        """Track usage with enforcement.

All-in-one endpoint for tracking usage with quota and rate limit enforcement.

**This is the recommended endpoint** for most use cases. It performs three operations in sequence:
1. **Rate Limit Check**: Validates against configured rate limits (fast, Redis-based)
2. **Quota Check**: Validates against configured quotas (database-based)
3. **Event Ingestion**: Records the event if all checks pass

**Response Codes:**
- `201 Created`: Event tracked successfully, all limits within bounds
- `429 Too Many Requests`: Rate limit or quota exceeded (check response body for details)

**Rate Limit Headers:**
The response includes standard rate limit headers:
- `X-RateLimit-Limit`: Maximum requests allowed
- `X-RateLimit-Remaining`: Requests remaining in current window
- `X-RateLimit-Reset`: Unix timestamp when window resets
- `Retry-After`: Seconds to wait before retrying (on 429 responses)

**Quota Headers (on quota exceeded):**
When a quota is exceeded, the response includes:
- `Retry-After`: Seconds to wait before retrying
- `X-Quota-Reset`: Unix timestamp when the quota period resets
- `X-Quota-Period`: Quota period (hour, day, week, month)
- `X-Quota-Metric`: Quota metric (total_tokens, total_events, total_cost_cents)

**Dimension Matching:**
Quotas and rate limits are matched based on dimensions extracted from:
- `customerId` → `customer_id`
- `eventType` → `event_type`
- `model` → `model`
- `provider` → `provider`
- `properties` → All string values are included as dimensions.

Args:
    request: TrackPostRequest object

Returns:
    TrackPostResponse: Event tracked successfully - all limits within bounds

Example::

    request = TrackPostRequest(
        customerId="customerid_123",
        eventType="example",
        model="example",
        provider="provider_123"
        # ... other properties
    )

    result = await client.track.usage(
        request
    )
    print(result)

Raises:
        APIError: Invalid request body
        AuthenticationError: Unauthorized - Invalid or missing API key
        APIError: Rate limit or quota exceeded - request was blocked
        NetworkError: If a network error occurs"""
        response = await self._client.request("POST", "/track", json=request.model_dump(mode='json', exclude_none=True))
        return TrackPostResponse(**response)