meterflow 0.6.0__tar.gz → 0.7.0__tar.gz

{meterflow-0.6.0 → meterflow-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: meterflow
-Version: 0.6.0
+Version: 0.7.0
 Summary: Official Python SDK for MeterFlow — usage-based billing, credit management, and metering.
 Project-URL: Homepage, https://meter-flow.com
 Project-URL: Documentation, https://meter-flow.com/guide
@@ -264,10 +264,14 @@ while True:
     cursor = page["next_cursor"]
     if cursor is None:
         break
+
+# Another order: `sort` is "created_at" (the default) or "amount", `order` "desc" (the default) or "asc".
+largest_first = client.credits.transactions("customer_123", sort="amount", order="desc")
 ```
 
-> **The cursor is opaque.** Pass back exactly what `next_cursor` gave you; do not build one, and do
-> not read anything out of it. `limit` is 1–200 and defaults to 50.
+> **The cursor is opaque.** Pass back exactly what `next_cursor` gave you, with the same `sort` and `order`
+> (another order with it is a `ValidationError`); do not build one, and do not read anything out of it.
+> `limit` is 1–200 and defaults to 50.
 
 > **Amounts are decimal strings.** Balances and amounts come back as strings (`"3545.000000"`) to avoid floating-point drift on money-like values. Parse deliberately (`decimal.Decimal(...)`) when you need arithmetic. When *sending* an amount, a number or a numeric string are both accepted.
 
@@ -303,12 +307,13 @@ Record an event every time a customer does the thing you charge for. Events are
 **Record one event:**
 
 ```python
+
 client.usage.record({
     "event_name": "images.generated",
     "customer_external_id": "customer_123",
     "value": 1,                                   # optional — what the meter aggregates: 1 for counts, seconds/MB/etc. for sums
     "properties": {},                             # free-form context; {} when unused
-    "timestamp": "2026-09-30T10:00:00Z",          # optional — defaults to arrival time on the server
+    # "timestamp": leave it out — the API stamps arrival time; one more than 300 s old or 60 s ahead is refused (422)
 })
 ```
 
@@ -410,6 +415,7 @@ page = client.subscriptions.list()                              # whole project
 theirs = client.subscriptions.list(customer_id="customer_123")  # one customer
 more = client.subscriptions.list(limit=200, cursor=page["next_cursor"])
 behind = client.subscriptions.list(q="acme", status=["past_due", "paused"])  # ids containing "acme", in either status
+by_status = client.subscriptions.list(sort="status", order="asc")  # or "created_at" (default), "customer_external_id"
 
 for subscription in page["data"]:
     print(subscription["customer_external_id"], subscription["status"])
@@ -670,7 +676,7 @@ Every delivery is a flat JSON object (`Content-Type: application/json`) with two
 |---|---|---|
 | `usage.recorded` | a usage event is ingested (single or batch) | `customer_id`, `event_name`, `value`, `event_id` |
 | `credit.granted` | credits are granted | `customer_id`, `amount`, `balance_after`, `transaction_id` |
-| `credit.deducted` | credits are deducted | `customer_id`, `amount`, `balance_after`, `transaction_id` |
+| `credit.deducted` | credits are deducted: by a deduct call, or by a metered usage charge | `customer_id`, `amount`, `balance_after`, `transaction_id`, `transaction_type` (`deduct` or `usage`), `usage_event_id` (the billed event for `usage`, else null) |
 | `subscription.created` | a subscription is created | `customer_id`, `plan_id`, `subscription_id`, `status` |
 | `subscription.updated` | a subscription is updated | `customer_id`, `subscription_id`, `status` |
 | `limit.reached` | a customer first reaches a **hard** or **soft** limit's included units this billing period (once per meter per period; metered limits report through `credit.deducted` instead) | `customer_id`, `subscription_id`, `feature` (the meter's `event_name`), `meter_id`, `limit_type`, `included`, `used`, `period_start`, `period_end` |

{meterflow-0.6.0 → meterflow-0.7.0}/README.md

@@ -212,10 +212,14 @@ while True:
     cursor = page["next_cursor"]
     if cursor is None:
         break
+
+# Another order: `sort` is "created_at" (the default) or "amount", `order` "desc" (the default) or "asc".
+largest_first = client.credits.transactions("customer_123", sort="amount", order="desc")
 ```
 
-> **The cursor is opaque.** Pass back exactly what `next_cursor` gave you; do not build one, and do
-> not read anything out of it. `limit` is 1–200 and defaults to 50.
+> **The cursor is opaque.** Pass back exactly what `next_cursor` gave you, with the same `sort` and `order`
+> (another order with it is a `ValidationError`); do not build one, and do not read anything out of it.
+> `limit` is 1–200 and defaults to 50.
 
 > **Amounts are decimal strings.** Balances and amounts come back as strings (`"3545.000000"`) to avoid floating-point drift on money-like values. Parse deliberately (`decimal.Decimal(...)`) when you need arithmetic. When *sending* an amount, a number or a numeric string are both accepted.
 
@@ -251,12 +255,13 @@ Record an event every time a customer does the thing you charge for. Events are
 **Record one event:**
 
 ```python
+
 client.usage.record({
     "event_name": "images.generated",
     "customer_external_id": "customer_123",
     "value": 1,                                   # optional — what the meter aggregates: 1 for counts, seconds/MB/etc. for sums
     "properties": {},                             # free-form context; {} when unused
-    "timestamp": "2026-09-30T10:00:00Z",          # optional — defaults to arrival time on the server
+    # "timestamp": leave it out — the API stamps arrival time; one more than 300 s old or 60 s ahead is refused (422)
 })
 ```
 
@@ -358,6 +363,7 @@ page = client.subscriptions.list()                              # whole project
 theirs = client.subscriptions.list(customer_id="customer_123")  # one customer
 more = client.subscriptions.list(limit=200, cursor=page["next_cursor"])
 behind = client.subscriptions.list(q="acme", status=["past_due", "paused"])  # ids containing "acme", in either status
+by_status = client.subscriptions.list(sort="status", order="asc")  # or "created_at" (default), "customer_external_id"
 
 for subscription in page["data"]:
     print(subscription["customer_external_id"], subscription["status"])
@@ -618,7 +624,7 @@ Every delivery is a flat JSON object (`Content-Type: application/json`) with two
 |---|---|---|
 | `usage.recorded` | a usage event is ingested (single or batch) | `customer_id`, `event_name`, `value`, `event_id` |
 | `credit.granted` | credits are granted | `customer_id`, `amount`, `balance_after`, `transaction_id` |
-| `credit.deducted` | credits are deducted | `customer_id`, `amount`, `balance_after`, `transaction_id` |
+| `credit.deducted` | credits are deducted: by a deduct call, or by a metered usage charge | `customer_id`, `amount`, `balance_after`, `transaction_id`, `transaction_type` (`deduct` or `usage`), `usage_event_id` (the billed event for `usage`, else null) |
 | `subscription.created` | a subscription is created | `customer_id`, `plan_id`, `subscription_id`, `status` |
 | `subscription.updated` | a subscription is updated | `customer_id`, `subscription_id`, `status` |
 | `limit.reached` | a customer first reaches a **hard** or **soft** limit's included units this billing period (once per meter per period; metered limits report through `credit.deducted` instead) | `customer_id`, `subscription_id`, `feature` (the meter's `event_name`), `meter_id`, `limit_type`, `included`, `used`, `period_start`, `period_end` |

{meterflow-0.6.0 → meterflow-0.7.0}/src/meterflow/__init__.py

@@ -7,6 +7,7 @@ client.credits.grant({"customer_external_id": "customer_123", "amount": 5000, "m
 """
 
 from ._entitlement_cache import EntitlementDefault, EntitlementFallbackContext
+from ._http import SortOrder
 from ._version import __version__
 from .client import AsyncMeterFlow, ClientOptions, MeterFlow
 from .errors import (
@@ -21,7 +22,9 @@ from .errors import (
     ValidationError,
     ValidationFieldError,
 )
+from .resources.credits import TransactionSort
 from .resources.entitlements import EntitlementCheck, EntitlementList
+from .resources.subscriptions import SubscriptionSort
 from .resources.usage import MAX_BATCH_EVENTS
 from .webhook import verify_webhook
 
@@ -45,5 +48,8 @@ __all__ = [
     "EntitlementList",
     "EntitlementDefault",
     "EntitlementFallbackContext",
+    "SortOrder",
+    "SubscriptionSort",
+    "TransactionSort",
     "verify_webhook",
 ]

{meterflow-0.6.0 → meterflow-0.7.0}/src/meterflow/_entitlement_cache.py

@@ -1,4 +1,4 @@
-"""The entitlement answers one client keeps, and the rules for falling back on them. Mirrors ``sdks/node/src/utils/entitlement-cache.ts``.
+"""The entitlement answers one client keeps, and the rules for falling back on them.
 
 Each answer is fresh for the ``max-age`` the API sends and kept past it as the fallback for an outage.
 Bounded, least recently used out first.
@@ -54,6 +54,13 @@ class CacheRead:
 
 @dataclass
 class _CachedAnswer:
+    """One stored answer.
+
+    customer_id: whose answer it is.
+    value: the answer itself.
+    fresh_until: the clock reading after which it is no longer fresh; it is still kept as a fallback.
+    """
+
     customer_id: str
     value: Any
     fresh_until: float
@@ -71,7 +78,9 @@ def max_age_seconds(header: str | None) -> int:
 
 
 def is_outage(error: BaseException) -> bool:
-    """Whether a failed call is MeterFlow being unreachable rather than an answer: no response at all, a 5xx after the retries, or a 429.
+    """Whether a failed call is MeterFlow being unreachable rather than an answer: no response, a 5xx after the retries, or a 429.
+
+    A 401, 403, 404 or 422 is an answer.
 
     error: what the call raised.
     """

{meterflow-0.6.0 → meterflow-0.7.0}/src/meterflow/_http.py

@@ -1,7 +1,6 @@
-"""The HTTP layer both clients share: URL/header building, error-body parsing, status → error mapping.
+"""The HTTP layer both clients share: headers, query parameters, reading error answers and choosing the error class.
 
-Only the *waiting* differs between sync and async, so the request loops live in ``client.py`` and
-everything they call lives here, once. Mirrors ``sdks/node/src/utils/http.ts``.
+Only the waiting differs between the sync and async clients, so their request loops live in ``client.py``.
 """
 
 from __future__ import annotations
@@ -11,7 +10,7 @@ import json
 import time
 from collections.abc import Sequence
 from dataclasses import dataclass, field
-from typing import Any
+from typing import Any, Literal
 from urllib.parse import quote
 
 import httpx
@@ -34,7 +33,7 @@ USER_AGENT = f"meterflow-python/{__version__}"
 
 QueryValue = str | int | float | bool | Sequence[str] | None
 
-# Indirections so tests can make the retry loop instantaneous without touching the clock.
+# Indirections, so tests can make the retry loop instant.
 _sleep = time.sleep
 
 
@@ -42,9 +41,21 @@ async def _async_sleep(seconds: float) -> None:
     await asyncio.sleep(seconds)
 
 
+# Which way a list is ordered: ``desc`` (each list's default) or ``asc``.
+SortOrder = Literal["asc", "desc"]
+
+
 @dataclass(frozen=True)
 class RequestSpec:
-    """One API call, described by a resource method and executed by a client."""
+    """One API call, described by a resource method and made by a client.
+
+    method: the HTTP method.
+    path: the endpoint, relative to the base URL.
+    body: the JSON body; None for none.
+    query: the query parameters; a None one is not sent.
+    idempotency_key: sent as the ``Idempotency-Key`` header.
+    timeout: this call's timeout in seconds; None for the client's.
+    """
 
     method: str
     path: str
@@ -55,11 +66,19 @@ class RequestSpec:
 
 
 def encode_path_segment(value: str) -> str:
-    """Customer ids are caller-chosen strings (emails, ``user/42``…) — they must never split the path."""
+    """A path segment, percent-encoded: a customer id is any string (an email, ``user/42``) and must never split the path.
+
+    value: the id to encode.
+    """
     return quote(value, safe="")
 
 
 def build_headers(api_key: str, spec: RequestSpec) -> dict[str, str]:
+    """The request's headers: the key, the SDK's User-Agent, JSON, and the idempotency key when there is one.
+
+    api_key: the client's key.
+    spec: the call.
+    """
     headers = {"Authorization": f"Bearer {api_key}", "User-Agent": USER_AGENT, "Accept": "application/json"}
     if spec.body is not None:
         headers["Content-Type"] = "application/json"
@@ -69,7 +88,10 @@ def build_headers(api_key: str, spec: RequestSpec) -> dict[str, str]:
 
 
 def build_params(query: dict[str, QueryValue]) -> dict[str, str | list[str]]:
-    """Unset (``None``) filters are simply not sent; booleans go as ``true``/``false`` like the Node SDK; a list repeats its key."""
+    """The query parameters as sent: a None one is left out, a boolean is ``true`` / ``false``, a list repeats its key.
+
+    query: the call's parameters.
+    """
     params: dict[str, str | list[str]] = {}
     for key, value in query.items():
         if value is None:
@@ -85,19 +107,24 @@ def build_params(query: dict[str, QueryValue]) -> dict[str, str | list[str]]:
 
 @dataclass(frozen=True)
 class ParsedError:
+    """An error answer's message, and the fields a 422 named."""
+
     message: str
     fields: list[ValidationFieldError]
 
 
 def _is_field_error(value: object) -> bool:
+    """Whether a value is one ``{field, message}`` entry of a 422's ``fields``.
+
+    value: one entry, as parsed.
+    """
     return isinstance(value, dict) and isinstance(value.get("field"), str) and isinstance(value.get("message"), str)
 
 
 def parse_error_body(response: httpx.Response) -> ParsedError:
-    """The API answers every error as ``{"error": {"code", "message", "fields"?}}`` (``app/api/src/exceptions.py``).
+    """Read an error answer, ``{"error": {"code", "message", "fields"?}}``; a bare ``{"detail"}`` or any other body still gives a message.
 
-    ``detail`` is FastAPI's default shape, kept as a fallback so an unexpected passthrough still
-    yields a readable message rather than a JSON blob.
+    response: the failed response.
     """
     try:
         payload = response.json()
@@ -124,6 +151,10 @@ def parse_error_body(response: httpx.Response) -> ParsedError:
 
 
 def map_response_error(response: httpx.Response) -> MeterFlowError:
+    """The error class for a failed response's status, carrying its message, request id and, for a 429, its ``Retry-After``.
+
+    response: the failed response.
+    """
     status = response.status_code
     parsed = parse_error_body(response)
     request_id = response.headers.get("x-request-id")
@@ -150,14 +181,21 @@ def map_response_error(response: httpx.Response) -> MeterFlowError:
 
 
 def decode_response(response: httpx.Response) -> Any:
-    """2xx → parsed JSON; ``204`` / an empty body → ``None`` (``subscriptions.delete``)."""
+    """A successful response's JSON body; None for a 204 or an empty body.
+
+    response: the successful response.
+    """
     if response.status_code == 204 or not response.content:
         return None
     return response.json()
 
 
 def request_kwargs(api_key: str, spec: RequestSpec) -> dict[str, Any]:
-    """Everything ``httpx.Client.request`` / ``AsyncClient.request`` needs beyond the method and path."""
+    """Everything ``httpx.Client.request`` / ``AsyncClient.request`` needs beyond the method and path.
+
+    api_key: the client's key.
+    spec: the call.
+    """
     kwargs: dict[str, Any] = {"headers": build_headers(api_key, spec), "params": build_params(spec.query)}
     if spec.body is not None:
         kwargs["content"] = json.dumps(spec.body).encode("utf-8")

{meterflow-0.6.0 → meterflow-0.7.0}/src/meterflow/_retry.py

@@ -1,9 +1,6 @@
-"""Retry policy shared by the sync and async clients.
+"""The retry policy both clients use: it decides how long to wait, and the client does the waiting.
 
-The policy only *decides* — how long to wait before attempt N+1, or that the caller should give up.
-The clients do the sleeping (``time.sleep`` vs ``asyncio.sleep``), so the backoff maths lives once.
-Mirrors the Node SDK: exponential base (1 s × factor^attempt, capped), ±25 % jitter, and a 429's
-``Retry-After`` taken verbatim instead of the computed delay.
+Exponential backoff (1 s × factor^attempt, capped) with ±25 % jitter; a 429 waits its ``Retry-After`` instead.
 """
 
 from __future__ import annotations
@@ -16,19 +13,34 @@ from .errors import MeterFlowError, RateLimitError
 
 @dataclass(frozen=True)
 class RetryPolicy:
+    """How many times a failed request is tried again, and the backoff between attempts.
+
+    retries: the attempts after the first.
+    factor: the backoff's growth per attempt.
+    jitter: whether each delay is spread by ±25 %.
+    max_delay_seconds: the longest computed delay.
+    """
+
     retries: int = 3
     factor: float = 2.0
     jitter: bool = True
     max_delay_seconds: float = 10.0
 
     def should_retry(self, error: BaseException) -> bool:
-        """API errors say for themselves whether a retry can help; anything else is a transport failure and can."""
+        """Whether a retry can help: an API error says so itself; anything else is a network failure, which can.
+
+        error: what the attempt raised.
+        """
         if isinstance(error, MeterFlowError):
             return error.retryable
         return True
 
     def delay_before_retry(self, attempt: int, error: BaseException) -> float | None:
-        """Seconds to wait before retrying ``attempt`` (0-based), or ``None`` when the caller must re-raise."""
+        """Seconds to wait before the next attempt, or ``None`` when the caller must re-raise.
+
+        attempt: the attempt that failed, from 0.
+        error: what it raised.
+        """
         is_last = attempt >= self.retries
         if is_last or not self.should_retry(error):
             return None

meterflow-0.7.0/src/meterflow/_version.py

@@ -0,0 +1,2 @@
+# The package's version: pyproject.toml reads it, and the User-Agent sends it. A release edits only this line.
+__version__ = "0.7.0"

{meterflow-0.6.0 → meterflow-0.7.0}/src/meterflow/client.py

@@ -1,9 +1,4 @@
-"""``MeterFlow`` (sync) and ``AsyncMeterFlow`` — same options, same resources, same errors.
-
-Resources describe a call as a ``RequestSpec``; the client executes it with retries. Everything that
-does not depend on *how* you wait lives in ``_http.py`` and ``_retry.py``, so the two clients are
-thin and cannot drift apart.
-"""
+"""``MeterFlow`` (sync) and ``AsyncMeterFlow``: the same options, resources and errors."""
 
 from __future__ import annotations
 
@@ -34,7 +29,16 @@ KEY_PREFIXES = ("mf_live_", "mf_test_")
 
 @dataclass(frozen=True)
 class ClientOptions:
-    """The resolved configuration — what the Node SDK exposes as ``client.options``."""
+    """The options in force, with every default filled in, as ``client.options``.
+
+    api_key: the client's key.
+    base_url: the API root, ending in ``/``.
+    timeout: one attempt's timeout, in seconds.
+    retries: the attempts after the first.
+    entitlements_cache: whether entitlement answers are reused.
+    entitlement_defaults: what ``check()`` answers per feature while MeterFlow is unreachable.
+    on_error: told when an entitlements call answers from a fallback.
+    """
 
     api_key: str
     base_url: str
@@ -46,6 +50,8 @@ class ClientOptions:
 
 
 class _BaseClient:
+    """What both clients share: the key check, the options, the retry policy and the entitlement cache."""
+
     def __init__(
         self,
         api_key: str,
@@ -68,20 +74,34 @@ class _BaseClient:
             on_error=on_error,
         )
         self._retry = RetryPolicy(retries=self.options.retries)
-        # Internal: the entitlement answers this client has read; None when ``entitlements_cache`` is False.
+        # The entitlement answers this client has read; None when ``entitlements_cache`` is False.
         self.entitlement_cache = EntitlementCache() if entitlements_cache else None
 
     def _kwargs(self, spec: RequestSpec) -> dict[str, Any]:
+        """The arguments ``httpx`` needs for a call.
+
+        spec: the call.
+        """
         return request_kwargs(self.options.api_key, spec)
 
 
 class MeterFlow(_BaseClient):
-    """Synchronous client.
-
-    ``transport`` injects an ``httpx`` transport (tests, proxies) — the Python counterpart of the
-    Node SDK's ``fetch`` option. Use it as a context manager or call ``close()`` to release connections.
-    ``entitlements_cache``, ``entitlement_defaults`` and ``on_error`` set how ``entitlements`` caches its
-    answers and what it answers while MeterFlow is unreachable (``resources/entitlements.py``).
+    """The MeterFlow client, synchronous: one per API key, with an attribute per resource.
+
+    Use it in a ``with`` block, or call ``close()``, to release its connections. Raises ``ValueError`` when the key is
+    neither ``mf_live_…`` nor ``mf_test_…``.
+
+    api_key: your secret API key: ``mf_live_…`` reads and writes live data, ``mf_test_…`` test data. Keep it on your server.
+    base_url: the API root, ``https://api.meter-flow.com/api/v1`` by default; change it only for another MeterFlow server.
+    timeout: how long one attempt may take, in seconds (30 by default).
+    retries: how many times a failed request is tried again (3 by default; 0 turns retries off). Only network errors,
+        429s and 5xx are retried.
+    transport: an ``httpx`` transport to send through, for tests or a proxy.
+    entitlements_cache: reuse ``entitlements.check()`` / ``get()`` answers for the ``max-age`` the API sends (15 s today).
+    entitlement_defaults: per feature, what ``check()`` answers while MeterFlow is unreachable and nothing is cached;
+        ``"*"`` covers every other feature.
+    on_error: called before an entitlements call answers from a fallback, with the error that caused it. What it raises
+        is ignored.
     """
 
     def __init__(
@@ -107,7 +127,7 @@ class MeterFlow(_BaseClient):
         self.webhooks = WebhooksResource(self)
 
     def request(self, spec: RequestSpec, on_headers: Callable[[httpx.Headers], None] | None = None) -> Any:
-        """Internal — used by resource classes; not part of the public API.
+        """Internal: used by the resources; not part of the public API.
 
         spec: the call.
         on_headers: given a successful response's headers; how the entitlements cache reads ``Cache-Control``.
@@ -128,6 +148,7 @@ class MeterFlow(_BaseClient):
         raise AssertionError("unreachable")  # pragma: no cover — `count()` never ends
 
     def close(self) -> None:
+        """Release the client's connections."""
         self._http.close()
 
     def __enter__(self) -> MeterFlow:
@@ -138,7 +159,23 @@ class MeterFlow(_BaseClient):
 
 
 class AsyncMeterFlow(_BaseClient):
-    """Asynchronous client — identical surface, every method awaitable. ``async with`` or ``aclose()``."""
+    """The MeterFlow client, asynchronous: the same resources as ``MeterFlow``, every method awaitable.
+
+    Use it in an ``async with`` block, or call ``aclose()``, to release its connections. Raises ``ValueError`` when the
+    key is neither ``mf_live_…`` nor ``mf_test_…``.
+
+    api_key: your secret API key: ``mf_live_…`` reads and writes live data, ``mf_test_…`` test data. Keep it on your server.
+    base_url: the API root, ``https://api.meter-flow.com/api/v1`` by default; change it only for another MeterFlow server.
+    timeout: how long one attempt may take, in seconds (30 by default).
+    retries: how many times a failed request is tried again (3 by default; 0 turns retries off). Only network errors,
+        429s and 5xx are retried.
+    transport: an ``httpx`` async transport to send through, for tests or a proxy.
+    entitlements_cache: reuse ``entitlements.check()`` / ``get()`` answers for the ``max-age`` the API sends (15 s today).
+    entitlement_defaults: per feature, what ``check()`` answers while MeterFlow is unreachable and nothing is cached;
+        ``"*"`` covers every other feature.
+    on_error: called before an entitlements call answers from a fallback, with the error that caused it. What it raises
+        is ignored.
+    """
 
     def __init__(
         self,
@@ -163,7 +200,7 @@ class AsyncMeterFlow(_BaseClient):
         self.webhooks = AsyncWebhooksResource(self)
 
     async def request(self, spec: RequestSpec, on_headers: Callable[[httpx.Headers], None] | None = None) -> Any:
-        """Internal — used by resource classes; not part of the public API.
+        """Internal: used by the resources; not part of the public API.
 
         spec: the call.
         on_headers: given a successful response's headers; how the entitlements cache reads ``Cache-Control``.
@@ -184,6 +221,7 @@ class AsyncMeterFlow(_BaseClient):
         raise AssertionError("unreachable")  # pragma: no cover — `count()` never ends
 
     async def aclose(self) -> None:
+        """Release the client's connections."""
         await self._http.aclose()
 
     async def __aenter__(self) -> AsyncMeterFlow:

{meterflow-0.6.0 → meterflow-0.7.0}/src/meterflow/errors.py

@@ -1,7 +1,7 @@
-"""Typed error hierarchy — one class per HTTP outcome, mirroring the Node SDK one-to-one.
+"""The errors the SDK raises: one class per HTTP outcome.
 
-Every error carries the API's ``X-Request-ID`` (``request_id``) so a support ticket can point at the
-exact request, plus ``status_code``, ``error_type`` and ``retryable`` for structured logging.
+Every error carries the API's ``X-Request-ID`` as ``request_id`` (quote it to support), with ``status_code``,
+``error_type`` and ``retryable``.
 """
 
 from __future__ import annotations
@@ -10,13 +10,26 @@ from typing import TypedDict
 
 
 class ValidationFieldError(TypedDict):
-    """One field the API rejected, as returned in a 422's ``error.fields``."""
+    """One field the API rejected, as returned in a 422's ``error.fields``.
+
+    field: the field's name in the request.
+    message: why it was refused.
+    """
 
     field: str
     message: str
 
 
 class MeterFlowError(Exception):
+    """Every error the SDK raises for an API answer; each HTTP outcome has its own subclass.
+
+    message: what went wrong, with the refused fields for a 422.
+    error_type: a stable name for the kind of error: ``auth_error``, ``not_found``, ``rate_limit`` and so on.
+    retryable: whether the SDK retries this kind of error (it already has, by the time you see it).
+    request_id: the API's ``X-Request-ID`` for the request; None when there was no answer.
+    status_code: the HTTP status; None when there was no answer.
+    """
+
     def __init__(
         self,
         message: str,
@@ -38,35 +51,35 @@ class MeterFlowError(Exception):
 
 
 class AuthError(MeterFlowError):
-    """401 / 403 — the key is missing, invalid, revoked or not allowed to do this."""
+    """401 / 403: the key is missing, invalid or revoked, or not allowed to do this."""
 
     def __init__(self, message: str, *, request_id: str | None = None, status_code: int = 401) -> None:
         super().__init__(message, "auth_error", retryable=False, request_id=request_id, status_code=status_code)
 
 
 class NotFoundError(MeterFlowError):
-    """404 — no such customer, plan, subscription… or an unknown feature key (a typo, not a plan)."""
+    """404: no such customer, plan, subscription or hold, or an unknown feature key (a typo, not a plan)."""
 
     def __init__(self, message: str, *, request_id: str | None = None) -> None:
         super().__init__(message, "not_found", retryable=False, request_id=request_id, status_code=404)
 
 
 class InsufficientCreditsError(MeterFlowError):
-    """402 — a deduction the balance cannot cover. A business outcome, not a failure: prompt a top-up."""
+    """402: a deduction or a hold the customer's available credits cannot cover. A business outcome: offer a top-up."""
 
     def __init__(self, message: str, *, request_id: str | None = None) -> None:
         super().__init__(message, "insufficient_credits", retryable=False, request_id=request_id, status_code=402)
 
 
 class ConflictError(MeterFlowError):
-    """409 — the write clashes with current state (e.g. the project is deactivated)."""
+    """409: the write clashes with the current state, for example a deactivated project or a hold already settled."""
 
     def __init__(self, message: str, *, request_id: str | None = None) -> None:
         super().__init__(message, "conflict", retryable=False, request_id=request_id, status_code=409)
 
 
 class ValidationError(MeterFlowError):
-    """422 — the API rejected the payload. ``fields`` holds the per-field detail (empty when none was sent)."""
+    """422: the API refused the request body or query; ``fields`` says which field and why (empty when it named none)."""
 
     def __init__(self, message: str, *, request_id: str | None = None, fields: list[ValidationFieldError] | None = None) -> None:
         super().__init__(message, "validation_error", retryable=False, request_id=request_id, status_code=422)
@@ -74,17 +87,14 @@ class ValidationError(MeterFlowError):
 
 
 class PayloadTooLargeError(MeterFlowError):
-    """413 — well-formed but too big; today only ``usage.record_batch`` above ``MAX_BATCH_EVENTS``.
-
-    Never retried: the same payload would be refused again. Split it at the call site.
-    """
+    """413: too large; today only ``usage.record_batch`` above ``MAX_BATCH_EVENTS`` events. Never retried: split the batch."""
 
     def __init__(self, message: str, *, request_id: str | None = None) -> None:
         super().__init__(message, "payload_too_large", retryable=False, request_id=request_id, status_code=413)
 
 
 class RateLimitError(MeterFlowError):
-    """429 — retried automatically after the server's ``Retry-After`` (seconds, exposed as ``retry_after``)."""
+    """429: too many requests. Retried automatically after the server's ``Retry-After``, in seconds, kept as ``retry_after``."""
 
     def __init__(self, message: str, *, retry_after: int | None = None, request_id: str | None = None) -> None:
         super().__init__(message, "rate_limit", retryable=True, request_id=request_id, status_code=429)
@@ -92,7 +102,7 @@ class RateLimitError(MeterFlowError):
 
 
 class ServerError(MeterFlowError):
-    """5xx — MeterFlow's side; retried automatically with backoff."""
+    """5xx: a failure on MeterFlow's side. Retried automatically, with backoff."""
 
     def __init__(self, message: str, *, request_id: str | None = None, status_code: int = 500) -> None:
         super().__init__(message, "server_error", retryable=True, request_id=request_id, status_code=status_code)

meterflow-0.7.0/src/meterflow/resources/__init__.py

@@ -0,0 +1 @@
+"""The client's seven resources, each in a sync and an async form sharing one set of request specs."""