meterflow 0.4.0__tar.gz → 0.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: meterflow
-Version: 0.4.0
+Version: 0.6.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
@@ -76,6 +76,7 @@ Track what your customers use, enforce credit balances, gate features, and manag
 - [Configuration](#configuration)
 - [Usage guide](#usage-guide)
   - [Credits](#credits)
+  - [Holding credits for a long job](#holding-credits-for-a-long-job)
   - [Usage events](#usage-events)
   - [Subscriptions](#subscriptions)
   - [Plans](#plans)
@@ -190,6 +191,9 @@ client = MeterFlow(
     timeout=30.0,                                   # optional — per-request timeout in seconds (default 30)
     retries=3,                                      # optional — automatic retries (default 3, 0 disables)
     transport=None,                                 # optional — an httpx transport (tests, proxies)
+    entitlements_cache=True,                        # optional — reuse entitlement answers for their max-age (default on)
+    entitlement_defaults={"*": "deny"},             # optional — what check() answers while MeterFlow is unreachable
+    on_error=None,                                  # optional — told when an entitlements call answers from a fallback
 )
 ```
 
@@ -215,7 +219,7 @@ txn = client.credits.grant({
 print(txn["balance_after"])  # "5000.000000"
 ```
 
-**Deduct** — remove credits. Raises `InsufficientCreditsError` (HTTP 402) if the balance can't cover it — the customer is never taken below zero:
+**Deduct** — remove credits. Raises `InsufficientCreditsError` (HTTP 402) if the available credits can't cover it (the balance less what [holds](#holding-credits-for-a-long-job) keep) — the customer is never taken below zero:
 
 ```python
 from meterflow import InsufficientCreditsError
@@ -238,6 +242,8 @@ bal = client.credits.balance("customer_123")
 bal["balance"]         # "3545.000000"  ← decimal string, see note below
 bal["total_granted"]   # "5250.000000"
 bal["total_consumed"]  # "1705.000000"
+bal["reserved"]        # "200.000000"   ← held by reservations, still in balance
+bal["available"]       # "3345.000000"  ← balance − reserved: what can be spent now
 bal["usage_draws_credits"]  # True | False | None
 ```
 
@@ -265,6 +271,31 @@ while True:
 
 > **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.
 
+### Holding credits for a long job
+
+A job that runs for minutes — a render, an agent run — should not find, at the end, that other spending took the credits it was counting on. **Reserve** them first: the balance stays where it is, but `available` drops, and every other spend (`credits.deduct()`, usage charged by a metered plan, a `check()` that would charge, another hold) is measured against `available`.
+
+```python
+hold = client.credits.reserve(
+    {"customer_external_id": "customer_123", "amount": 200, "ttl_seconds": 600, "description": "render #42"},
+    idempotency_key="render-42",
+)
+
+try:
+    used = render()                                                           # the long job
+    client.credits.confirm_reservation(hold["id"], {"amount": used.credits})  # take what it used; the rest is freed
+except Exception:
+    client.credits.release_reservation(hold["id"])                            # nothing taken
+    raise
+```
+
+`AsyncMeterFlow` has the same four methods, awaited.
+
+- **Reserve** raises `InsufficientCreditsError` (402) when `available` cannot cover the amount, and `ConflictError` (409) when held credits would pass the subscription's spend cap: a hold counts against the cap as it will when confirmed. `ttl_seconds` defaults to 300 and is at most 86,400 (a day).
+- **Confirm** writes one ordinary `deduct` to the ledger, with your hold's description and `metadata["reservation_id"]`, and fires the same webhooks a deduct does. Leave out `amount` to take the whole hold; more than the hold is a `ValidationError` (422). Whatever it does not take is freed.
+- **Release** frees the hold with nothing taken. A hold left alone expires at `expires_at` and frees itself: `reservation(id)` then answers `"status": "expired"`, a confirm raises `ConflictError` (409), and a release answers it as expired.
+- Confirming or releasing a hold that is already confirmed or released raises `ConflictError` (409). If a retry of a confirm meets a 409, `client.credits.reservation(hold["id"])` tells you whether the first attempt landed.
+
 ### Usage events
 
 Record an event every time a customer does the thing you charge for. Events are matched to a meter by `event_name` and processed asynchronously into totals (and, if the meter is metered on a plan, into credit deductions).
@@ -463,7 +494,7 @@ client.usage.record({"event_name": "images.generated", "customer_external_id": "
 - A **soft** limit answers `allowed: True` with `reason: "soft_limit_exceeded"` — let it through, nudge the upgrade.
 - A **metered** limit stays allowed while the customer's credits cover the overage; otherwise `insufficient_credits`.
 - `allowed: False` is a normal returned answer, never an exception. A feature key the project does not know at all is a `NotFoundError` — that is a typo, not a plan.
-- The answer carries `Cache-Control: private, max-age=15`; on hot paths cache it per customer for a few seconds rather than calling on every request.
+- The SDK reuses an answer for the `Cache-Control: max-age` it came with (15 s today), per customer, feature and `quantity` — `allowed: False` included. See [When MeterFlow can't be reached](#when-meterflow-cant-be-reached).
 
 **All of them at once** — for a settings or pricing screen:
 
@@ -478,6 +509,31 @@ Each metered row answers for the **next** unit, exactly as `check()` would, so i
 
 Prefer to be told rather than to ask? Subscribe a webhook to `limit.reached` (see below).
 
+#### When MeterFlow can't be reached
+
+A MeterFlow blip should never take your product down with it. Three things keep `check()` answering, on `MeterFlow` and `AsyncMeterFlow` alike:
+
+- **The cache.** Answers from `check()` and `get()` are reused for the `max-age` the API sends (15 s), per client, up to 1,000 of them. A response without `Cache-Control` is never cached. A successful `usage.record()`, `usage.record_batch()`, `credits.grant()`, `credits.deduct()`, `credits.reserve()`, `confirm_reservation()` or `release_reservation()` makes that customer's answers stale, so the next `check()` asks again. `entitlements_cache=False` turns the cache off.
+- **The last answer.** When the API cannot be reached — a network error, a timeout, a 5xx or a 429, once the retries are spent — a call returns its last answer for that customer and feature, past its age, with `"stale": True`.
+- **Your defaults.** With no earlier answer, `check()` returns your `entitlement_defaults` entry for the feature, else its `"*"` entry: `{"feature", "feature_type": None, "allowed", "reason": "offline_default"}`. With neither, it raises as before. `get()` has no default: a whole plan cannot be guessed.
+
+```python
+from meterflow import EntitlementFallbackContext, MeterFlow
+
+def warn(error: Exception, context: EntitlementFallbackContext) -> None:
+    log.warning("meterflow fallback %s for %s / %s: %s", context.fallback, context.customer_id, context.feature, error)
+
+client = MeterFlow(
+    api_key=os.environ["METERFLOW_API_KEY"],
+    timeout=2.0,  # a gate on your hot path should give up fast
+    retries=1,
+    entitlement_defaults={"images.generated": "allow", "*": "deny"},
+    on_error=warn,
+)
+```
+
+A 401, 403, 404 or 422 is an answer, not an outage: it is raised, never replaced by a fallback. `on_error` is called before a fallback is used; anything it raises is ignored. `check()` returns an `EntitlementCheck` and `get()` an `EntitlementList` (both exported from `meterflow`): the API's types, widened for `stale` and `offline_default`.
+
 ### The balance portal — a page you don't have to build
 
 Mint a short-lived link to a MeterFlow-hosted page showing **one** customer's balance and ledger.

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

@@ -24,6 +24,7 @@ Track what your customers use, enforce credit balances, gate features, and manag
 - [Configuration](#configuration)
 - [Usage guide](#usage-guide)
   - [Credits](#credits)
+  - [Holding credits for a long job](#holding-credits-for-a-long-job)
   - [Usage events](#usage-events)
   - [Subscriptions](#subscriptions)
   - [Plans](#plans)
@@ -138,6 +139,9 @@ client = MeterFlow(
     timeout=30.0,                                   # optional — per-request timeout in seconds (default 30)
     retries=3,                                      # optional — automatic retries (default 3, 0 disables)
     transport=None,                                 # optional — an httpx transport (tests, proxies)
+    entitlements_cache=True,                        # optional — reuse entitlement answers for their max-age (default on)
+    entitlement_defaults={"*": "deny"},             # optional — what check() answers while MeterFlow is unreachable
+    on_error=None,                                  # optional — told when an entitlements call answers from a fallback
 )
 ```
 
@@ -163,7 +167,7 @@ txn = client.credits.grant({
 print(txn["balance_after"])  # "5000.000000"
 ```
 
-**Deduct** — remove credits. Raises `InsufficientCreditsError` (HTTP 402) if the balance can't cover it — the customer is never taken below zero:
+**Deduct** — remove credits. Raises `InsufficientCreditsError` (HTTP 402) if the available credits can't cover it (the balance less what [holds](#holding-credits-for-a-long-job) keep) — the customer is never taken below zero:
 
 ```python
 from meterflow import InsufficientCreditsError
@@ -186,6 +190,8 @@ bal = client.credits.balance("customer_123")
 bal["balance"]         # "3545.000000"  ← decimal string, see note below
 bal["total_granted"]   # "5250.000000"
 bal["total_consumed"]  # "1705.000000"
+bal["reserved"]        # "200.000000"   ← held by reservations, still in balance
+bal["available"]       # "3345.000000"  ← balance − reserved: what can be spent now
 bal["usage_draws_credits"]  # True | False | None
 ```
 
@@ -213,6 +219,31 @@ while True:
 
 > **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.
 
+### Holding credits for a long job
+
+A job that runs for minutes — a render, an agent run — should not find, at the end, that other spending took the credits it was counting on. **Reserve** them first: the balance stays where it is, but `available` drops, and every other spend (`credits.deduct()`, usage charged by a metered plan, a `check()` that would charge, another hold) is measured against `available`.
+
+```python
+hold = client.credits.reserve(
+    {"customer_external_id": "customer_123", "amount": 200, "ttl_seconds": 600, "description": "render #42"},
+    idempotency_key="render-42",
+)
+
+try:
+    used = render()                                                           # the long job
+    client.credits.confirm_reservation(hold["id"], {"amount": used.credits})  # take what it used; the rest is freed
+except Exception:
+    client.credits.release_reservation(hold["id"])                            # nothing taken
+    raise
+```
+
+`AsyncMeterFlow` has the same four methods, awaited.
+
+- **Reserve** raises `InsufficientCreditsError` (402) when `available` cannot cover the amount, and `ConflictError` (409) when held credits would pass the subscription's spend cap: a hold counts against the cap as it will when confirmed. `ttl_seconds` defaults to 300 and is at most 86,400 (a day).
+- **Confirm** writes one ordinary `deduct` to the ledger, with your hold's description and `metadata["reservation_id"]`, and fires the same webhooks a deduct does. Leave out `amount` to take the whole hold; more than the hold is a `ValidationError` (422). Whatever it does not take is freed.
+- **Release** frees the hold with nothing taken. A hold left alone expires at `expires_at` and frees itself: `reservation(id)` then answers `"status": "expired"`, a confirm raises `ConflictError` (409), and a release answers it as expired.
+- Confirming or releasing a hold that is already confirmed or released raises `ConflictError` (409). If a retry of a confirm meets a 409, `client.credits.reservation(hold["id"])` tells you whether the first attempt landed.
+
 ### Usage events
 
 Record an event every time a customer does the thing you charge for. Events are matched to a meter by `event_name` and processed asynchronously into totals (and, if the meter is metered on a plan, into credit deductions).
@@ -411,7 +442,7 @@ client.usage.record({"event_name": "images.generated", "customer_external_id": "
 - A **soft** limit answers `allowed: True` with `reason: "soft_limit_exceeded"` — let it through, nudge the upgrade.
 - A **metered** limit stays allowed while the customer's credits cover the overage; otherwise `insufficient_credits`.
 - `allowed: False` is a normal returned answer, never an exception. A feature key the project does not know at all is a `NotFoundError` — that is a typo, not a plan.
-- The answer carries `Cache-Control: private, max-age=15`; on hot paths cache it per customer for a few seconds rather than calling on every request.
+- The SDK reuses an answer for the `Cache-Control: max-age` it came with (15 s today), per customer, feature and `quantity` — `allowed: False` included. See [When MeterFlow can't be reached](#when-meterflow-cant-be-reached).
 
 **All of them at once** — for a settings or pricing screen:
 
@@ -426,6 +457,31 @@ Each metered row answers for the **next** unit, exactly as `check()` would, so i
 
 Prefer to be told rather than to ask? Subscribe a webhook to `limit.reached` (see below).
 
+#### When MeterFlow can't be reached
+
+A MeterFlow blip should never take your product down with it. Three things keep `check()` answering, on `MeterFlow` and `AsyncMeterFlow` alike:
+
+- **The cache.** Answers from `check()` and `get()` are reused for the `max-age` the API sends (15 s), per client, up to 1,000 of them. A response without `Cache-Control` is never cached. A successful `usage.record()`, `usage.record_batch()`, `credits.grant()`, `credits.deduct()`, `credits.reserve()`, `confirm_reservation()` or `release_reservation()` makes that customer's answers stale, so the next `check()` asks again. `entitlements_cache=False` turns the cache off.
+- **The last answer.** When the API cannot be reached — a network error, a timeout, a 5xx or a 429, once the retries are spent — a call returns its last answer for that customer and feature, past its age, with `"stale": True`.
+- **Your defaults.** With no earlier answer, `check()` returns your `entitlement_defaults` entry for the feature, else its `"*"` entry: `{"feature", "feature_type": None, "allowed", "reason": "offline_default"}`. With neither, it raises as before. `get()` has no default: a whole plan cannot be guessed.
+
+```python
+from meterflow import EntitlementFallbackContext, MeterFlow
+
+def warn(error: Exception, context: EntitlementFallbackContext) -> None:
+    log.warning("meterflow fallback %s for %s / %s: %s", context.fallback, context.customer_id, context.feature, error)
+
+client = MeterFlow(
+    api_key=os.environ["METERFLOW_API_KEY"],
+    timeout=2.0,  # a gate on your hot path should give up fast
+    retries=1,
+    entitlement_defaults={"images.generated": "allow", "*": "deny"},
+    on_error=warn,
+)
+```
+
+A 401, 403, 404 or 422 is an answer, not an outage: it is raised, never replaced by a fallback. `on_error` is called before a fallback is used; anything it raises is ignored. `check()` returns an `EntitlementCheck` and `get()` an `EntitlementList` (both exported from `meterflow`): the API's types, widened for `stale` and `offline_default`.
+
 ### The balance portal — a page you don't have to build
 
 Mint a short-lived link to a MeterFlow-hosted page showing **one** customer's balance and ledger.

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

@@ -6,6 +6,7 @@ client = MeterFlow(api_key="mf_live_...")
 client.credits.grant({"customer_external_id": "customer_123", "amount": 5000, "metadata": {}})
 """
 
+from ._entitlement_cache import EntitlementDefault, EntitlementFallbackContext
 from ._version import __version__
 from .client import AsyncMeterFlow, ClientOptions, MeterFlow
 from .errors import (
@@ -20,6 +21,7 @@ from .errors import (
     ValidationError,
     ValidationFieldError,
 )
+from .resources.entitlements import EntitlementCheck, EntitlementList
 from .resources.usage import MAX_BATCH_EVENTS
 from .webhook import verify_webhook
 
@@ -39,5 +41,9 @@ __all__ = [
     "RateLimitError",
     "ServerError",
     "MAX_BATCH_EVENTS",
+    "EntitlementCheck",
+    "EntitlementList",
+    "EntitlementDefault",
+    "EntitlementFallbackContext",
     "verify_webhook",
 ]

meterflow-0.6.0/src/meterflow/_entitlement_cache.py

@@ -0,0 +1,134 @@
+"""The entitlement answers one client keeps, and the rules for falling back on them. Mirrors ``sdks/node/src/utils/entitlement-cache.ts``.
+
+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.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from collections import OrderedDict
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from .errors import MeterFlowError, RateLimitError, ServerError
+
+# How many answers one client keeps; the least recently used goes first past it.
+MAX_CACHED_ENTITLEMENTS = 1_000
+
+EntitlementDefault = Literal["allow", "deny"]
+
+# The clock answers are aged by; an indirection so tests can step it.
+_now = time.monotonic
+
+_MAX_AGE = re.compile(r"\bmax-age=(\d+)", re.IGNORECASE)
+_NO_STORE = re.compile(r"\bno-(store|cache)\b", re.IGNORECASE)
+
+
+@dataclass(frozen=True)
+class EntitlementFallbackContext:
+    """Which call fell back, and to what, as ``on_error`` is told.
+
+    customer_id: the customer the call was for.
+    feature: the feature checked; None for ``entitlements.get()``.
+    fallback: ``stale``, the last answer past its ``max-age``; ``default``, the configured ``entitlement_defaults`` entry.
+    """
+
+    customer_id: str
+    feature: str | None
+    fallback: Literal["stale", "default"]
+
+
+OnEntitlementError = Callable[[Exception, EntitlementFallbackContext], None]
+
+
+@dataclass(frozen=True)
+class CacheRead:
+    """An answer found in the cache, and whether it is still fresh."""
+
+    value: Any
+    fresh: bool
+
+
+@dataclass
+class _CachedAnswer:
+    customer_id: str
+    value: Any
+    fresh_until: float
+
+
+def max_age_seconds(header: str | None) -> int:
+    """The seconds a response may be reused for: its ``max-age``; 0 when absent, ``no-store`` / ``no-cache``, or naming none.
+
+    header: the response's ``Cache-Control`` value, or None.
+    """
+    if not header or _NO_STORE.search(header):
+        return 0
+    match = _MAX_AGE.search(header)
+    return int(match.group(1)) if match else 0
+
+
+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.
+
+    error: what the call raised.
+    """
+    if not isinstance(error, MeterFlowError):
+        return True
+    return isinstance(error, ServerError | RateLimitError)
+
+
+class EntitlementCache:
+    """The entitlement answers one client has read, each fresh for the API's ``max-age`` and kept past it as an outage fallback."""
+
+    def __init__(self) -> None:
+        self._answers: OrderedDict[str, _CachedAnswer] = OrderedDict()
+
+    def read(self, key: str) -> CacheRead | None:
+        """The answer stored under ``key``, with whether it is still fresh; None when there is none.
+
+        key: the call's cache key.
+        """
+        cached = self._answers.get(key)
+        if cached is None:
+            return None
+        self._answers.move_to_end(key)
+        return CacheRead(cached.value, _now() < cached.fresh_until)
+
+    def write(self, key: str, customer_id: str, value: Any, seconds: int) -> None:
+        """Keep an answer for ``seconds``; nothing is kept when that is 0.
+
+        key: the call's cache key.
+        customer_id: whose answer it is, so a write for them can expire it.
+        value: the answer.
+        seconds: how long it stays fresh.
+        """
+        if seconds <= 0:
+            return
+        self._answers[key] = _CachedAnswer(customer_id, value, _now() + seconds)
+        self._answers.move_to_end(key)
+        if len(self._answers) > MAX_CACHED_ENTITLEMENTS:
+            self._answers.popitem(last=False)
+
+    def invalidate(self, customer_id: str) -> None:
+        """Make every answer for a customer stale, after a write that changed what they may do. They stay as an outage fallback.
+
+        customer_id: the customer written for.
+        """
+        for cached in self._answers.values():
+            if cached.customer_id == customer_id:
+                cached.fresh_until = 0.0
+
+
+def expire_entitlements(cache: EntitlementCache | None, customer_ids: list[str]) -> None:
+    """Make the cached answers of every customer a successful write touched stale; nothing when the cache is off.
+
+    cache: the client's cache, or None.
+    customer_ids: the customers written for, repeats allowed.
+    """
+    if cache is None:
+        return
+    for customer_id in set(customer_ids):
+        cache.invalidate(customer_id)

{meterflow-0.4.0 → meterflow-0.6.0}/src/meterflow/_version.py

@@ -1,3 +1,3 @@
 # The one place the version lives. pyproject.toml reads it (hatch dynamic version) and the
 # User-Agent header reports it, so a release bump edits this file and nothing else.
-__version__ = "0.4.0"
+__version__ = "0.6.0"

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

@@ -7,13 +7,15 @@ thin and cannot drift apart.
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
 from itertools import count
 from types import TracebackType
 from typing import Any
 
 import httpx
 
+from ._entitlement_cache import EntitlementCache, EntitlementDefault, OnEntitlementError
 from ._http import RequestSpec, _async_sleep, _sleep, decode_response, map_response_error, request_kwargs
 from ._retry import RetryPolicy
 from .resources.credits import AsyncCreditsResource, CreditsResource
@@ -38,10 +40,22 @@ class ClientOptions:
     base_url: str
     timeout: float
     retries: int
+    entitlements_cache: bool = True
+    entitlement_defaults: Mapping[str, EntitlementDefault] = field(default_factory=dict)
+    on_error: OnEntitlementError | None = None
 
 
 class _BaseClient:
-    def __init__(self, api_key: str, base_url: str | None, timeout: float | None, retries: int | None) -> None:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str | None,
+        timeout: float | None,
+        retries: int | None,
+        entitlements_cache: bool,
+        entitlement_defaults: Mapping[str, EntitlementDefault] | None,
+        on_error: OnEntitlementError | None,
+    ) -> None:
         if not api_key.startswith(KEY_PREFIXES):
             raise ValueError("api_key must start with mf_live_ or mf_test_")
         self.options = ClientOptions(
@@ -49,8 +63,13 @@ class _BaseClient:
             base_url=(base_url or DEFAULT_BASE_URL).rstrip("/") + "/",
             timeout=DEFAULT_TIMEOUT_SECONDS if timeout is None else timeout,
             retries=DEFAULT_RETRIES if retries is None else retries,
+            entitlements_cache=entitlements_cache,
+            entitlement_defaults=dict(entitlement_defaults or {}),
+            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.
+        self.entitlement_cache = EntitlementCache() if entitlements_cache else None
 
     def _kwargs(self, spec: RequestSpec) -> dict[str, Any]:
         return request_kwargs(self.options.api_key, spec)
@@ -61,6 +80,8 @@ class MeterFlow(_BaseClient):
 
     ``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``).
     """
 
     def __init__(
@@ -71,8 +92,11 @@ class MeterFlow(_BaseClient):
         timeout: float | None = None,
         retries: int | None = None,
         transport: httpx.BaseTransport | None = None,
+        entitlements_cache: bool = True,
+        entitlement_defaults: Mapping[str, EntitlementDefault] | None = None,
+        on_error: OnEntitlementError | None = None,
     ) -> None:
-        super().__init__(api_key, base_url, timeout, retries)
+        super().__init__(api_key, base_url, timeout, retries, entitlements_cache, entitlement_defaults, on_error)
         self._http = httpx.Client(base_url=self.options.base_url, timeout=self.options.timeout, transport=transport)
         self.credits = CreditsResource(self)
         self.usage = UsageResource(self)
@@ -82,13 +106,19 @@ class MeterFlow(_BaseClient):
         self.entitlements = EntitlementsResource(self)
         self.webhooks = WebhooksResource(self)
 
-    def request(self, spec: RequestSpec) -> Any:
-        """Internal — used by resource classes; not part of the public API."""
+    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.
+
+        spec: the call.
+        on_headers: given a successful response's headers; how the entitlements cache reads ``Cache-Control``.
+        """
         for attempt in count():
             try:
                 response = self._http.request(spec.method, spec.path, **self._kwargs(spec))
                 if response.is_error:
                     raise map_response_error(response)
+                if on_headers is not None:
+                    on_headers(response.headers)
                 return decode_response(response)
             except Exception as error:
                 delay = self._retry.delay_before_retry(attempt, error)
@@ -118,8 +148,11 @@ class AsyncMeterFlow(_BaseClient):
         timeout: float | None = None,
         retries: int | None = None,
         transport: httpx.AsyncBaseTransport | None = None,
+        entitlements_cache: bool = True,
+        entitlement_defaults: Mapping[str, EntitlementDefault] | None = None,
+        on_error: OnEntitlementError | None = None,
     ) -> None:
-        super().__init__(api_key, base_url, timeout, retries)
+        super().__init__(api_key, base_url, timeout, retries, entitlements_cache, entitlement_defaults, on_error)
         self._http = httpx.AsyncClient(base_url=self.options.base_url, timeout=self.options.timeout, transport=transport)
         self.credits = AsyncCreditsResource(self)
         self.usage = AsyncUsageResource(self)
@@ -129,13 +162,19 @@ class AsyncMeterFlow(_BaseClient):
         self.entitlements = AsyncEntitlementsResource(self)
         self.webhooks = AsyncWebhooksResource(self)
 
-    async def request(self, spec: RequestSpec) -> Any:
-        """Internal — used by resource classes; not part of the public API."""
+    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.
+
+        spec: the call.
+        on_headers: given a successful response's headers; how the entitlements cache reads ``Cache-Control``.
+        """
         for attempt in count():
             try:
                 response = await self._http.request(spec.method, spec.path, **self._kwargs(spec))
                 if response.is_error:
                     raise map_response_error(response)
+                if on_headers is not None:
+                    on_headers(response.headers)
                 return decode_response(response)
             except Exception as error:
                 delay = self._retry.delay_before_retry(attempt, error)

meterflow-0.6.0/src/meterflow/resources/credits.py

@@ -0,0 +1,215 @@
+"""Credits — an append-only ledger per customer: grant up, deduct down, never edited in place; holds set credits aside."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .._entitlement_cache import expire_entitlements
+from .._http import RequestSpec, encode_path_segment
+from ..types import (
+    CreditBalanceResponse,
+    CreditDeductRequest,
+    CreditGrantRequest,
+    CreditReservationConfirmRequest,
+    CreditReservationRequest,
+    CreditReservationResponse,
+    CreditTransactionPage,
+    CreditTransactionResponse,
+)
+
+if TYPE_CHECKING:
+    from ..client import AsyncMeterFlow, MeterFlow
+
+
+def grant_spec(body: CreditGrantRequest, idempotency_key: str | None) -> RequestSpec:
+    return RequestSpec("POST", "credits/grant", body=body, idempotency_key=idempotency_key)
+
+
+def deduct_spec(body: CreditDeductRequest, idempotency_key: str | None) -> RequestSpec:
+    return RequestSpec("POST", "credits/deduct", body=body, idempotency_key=idempotency_key)
+
+
+def reserve_spec(body: CreditReservationRequest, idempotency_key: str | None) -> RequestSpec:
+    return RequestSpec("POST", "credits/reservations", body=body, idempotency_key=idempotency_key)
+
+
+def confirm_reservation_spec(reservation_id: str, body: CreditReservationConfirmRequest | None) -> RequestSpec:
+    return RequestSpec("POST", f"credits/reservations/{encode_path_segment(reservation_id)}/confirm", body=body or {})
+
+
+def release_reservation_spec(reservation_id: str) -> RequestSpec:
+    return RequestSpec("POST", f"credits/reservations/{encode_path_segment(reservation_id)}/release")
+
+
+def reservation_spec(reservation_id: str) -> RequestSpec:
+    return RequestSpec("GET", f"credits/reservations/{encode_path_segment(reservation_id)}")
+
+
+def balance_spec(customer_id: str) -> RequestSpec:
+    return RequestSpec("GET", f"credits/{encode_path_segment(customer_id)}/balance")
+
+
+def transactions_spec(customer_id: str, limit: int | None, cursor: str | None) -> RequestSpec:
+    return RequestSpec("GET", f"credits/{encode_path_segment(customer_id)}/transactions", query={"limit": limit, "cursor": cursor})
+
+
+class CreditsResource:
+    def __init__(self, client: MeterFlow) -> None:
+        self._client = client
+
+    def grant(self, body: CreditGrantRequest, *, idempotency_key: str | None = None) -> CreditTransactionResponse:
+        """Add credits (plan renewals, top-ups, goodwill). Returns the ledger line. The customer's cached entitlement answers go stale."""
+        result: CreditTransactionResponse = self._client.request(grant_spec(body, idempotency_key))
+        expire_entitlements(self._client.entitlement_cache, [body["customer_external_id"]])
+        return result
+
+    def deduct(self, body: CreditDeductRequest, *, idempotency_key: str | None = None) -> CreditTransactionResponse:
+        """Remove credits. Raises ``InsufficientCreditsError`` (402) rather than take the customer below zero.
+
+        The customer's cached entitlement answers go stale.
+        """
+        result: CreditTransactionResponse = self._client.request(deduct_spec(body, idempotency_key))
+        expire_entitlements(self._client.entitlement_cache, [body["customer_external_id"]])
+        return result
+
+    def reserve(self, body: CreditReservationRequest, *, idempotency_key: str | None = None) -> CreditReservationResponse:
+        """Hold credits until confirmed, released or ``ttl_seconds`` (default 300) runs out; the balance stays, ``available`` drops.
+
+        Raises ``InsufficientCreditsError`` (402) when the available credits cannot cover it. The customer's cached entitlement
+        answers go stale.
+
+        body: the customer, the amount, how long to hold it, a description and metadata.
+        idempotency_key: makes a retried hold the same hold.
+        """
+        result: CreditReservationResponse = self._client.request(reserve_spec(body, idempotency_key))
+        expire_entitlements(self._client.entitlement_cache, [body["customer_external_id"]])
+        return result
+
+    def confirm_reservation(self, reservation_id: str, body: CreditReservationConfirmRequest | None = None) -> CreditReservationResponse:
+        """Take some or all of a hold from the balance, as one ``deduct`` ledger row, and free the rest.
+
+        Raises ``ConflictError`` (409) unless it is still held, ``ValidationError`` (422) above the amount held. The customer's
+        cached entitlement answers go stale.
+
+        reservation_id: the hold's ``id``.
+        body: ``amount`` to take; the whole hold when left out.
+        """
+        result: CreditReservationResponse = self._client.request(confirm_reservation_spec(reservation_id, body))
+        expire_entitlements(self._client.entitlement_cache, [result["customer_external_id"]])
+        return result
+
+    def release_reservation(self, reservation_id: str) -> CreditReservationResponse:
+        """Free a hold with nothing taken; an expired hold answers ``status: "expired"``, a settled one raises ``ConflictError`` (409).
+
+        The customer's cached entitlement answers go stale.
+
+        reservation_id: the hold's ``id``.
+        """
+        result: CreditReservationResponse = self._client.request(release_reservation_spec(reservation_id))
+        expire_entitlements(self._client.entitlement_cache, [result["customer_external_id"]])
+        return result
+
+    def reservation(self, reservation_id: str) -> CreditReservationResponse:
+        """One hold and how it ended: ``held``, ``confirmed``, ``released``, or ``expired`` once held past ``expires_at``.
+
+        reservation_id: the hold's ``id``.
+        """
+        result: CreditReservationResponse = self._client.request(reservation_spec(reservation_id))
+        return result
+
+    def balance(self, customer_id: str) -> CreditBalanceResponse:
+        """The customer's current position — amounts are decimal strings."""
+        result: CreditBalanceResponse = self._client.request(balance_spec(customer_id))
+        return result
+
+    def transactions(self, customer_id: str, *, limit: int | None = None, cursor: str | None = None) -> CreditTransactionPage:
+        """One page of the ledger, newest first.
+
+        The ledger grows with every charge, so it is read a page at a time: ``data`` holds the rows
+        and ``next_cursor`` the mark for the page after this one (``None`` on the last). Pass it
+        back as ``cursor`` unchanged — it is opaque, and nothing but this API reads it.
+        """
+        result: CreditTransactionPage = self._client.request(transactions_spec(customer_id, limit, cursor))
+        return result
+
+
+class AsyncCreditsResource:
+    def __init__(self, client: AsyncMeterFlow) -> None:
+        self._client = client
+
+    async def grant(self, body: CreditGrantRequest, *, idempotency_key: str | None = None) -> CreditTransactionResponse:
+        """Add credits (plan renewals, top-ups, goodwill). Returns the ledger line. The customer's cached entitlement answers go stale."""
+        result: CreditTransactionResponse = await self._client.request(grant_spec(body, idempotency_key))
+        expire_entitlements(self._client.entitlement_cache, [body["customer_external_id"]])
+        return result
+
+    async def deduct(self, body: CreditDeductRequest, *, idempotency_key: str | None = None) -> CreditTransactionResponse:
+        """Remove credits. Raises ``InsufficientCreditsError`` (402) rather than take the customer below zero.
+
+        The customer's cached entitlement answers go stale.
+        """
+        result: CreditTransactionResponse = await self._client.request(deduct_spec(body, idempotency_key))
+        expire_entitlements(self._client.entitlement_cache, [body["customer_external_id"]])
+        return result
+
+    async def reserve(self, body: CreditReservationRequest, *, idempotency_key: str | None = None) -> CreditReservationResponse:
+        """Hold credits until confirmed, released or ``ttl_seconds`` (default 300) runs out; the balance stays, ``available`` drops.
+
+        Raises ``InsufficientCreditsError`` (402) when the available credits cannot cover it. The customer's cached entitlement
+        answers go stale.
+
+        body: the customer, the amount, how long to hold it, a description and metadata.
+        idempotency_key: makes a retried hold the same hold.
+        """
+        result: CreditReservationResponse = await self._client.request(reserve_spec(body, idempotency_key))
+        expire_entitlements(self._client.entitlement_cache, [body["customer_external_id"]])
+        return result
+
+    async def confirm_reservation(
+        self, reservation_id: str, body: CreditReservationConfirmRequest | None = None
+    ) -> CreditReservationResponse:
+        """Take some or all of a hold from the balance, as one ``deduct`` ledger row, and free the rest.
+
+        Raises ``ConflictError`` (409) unless it is still held, ``ValidationError`` (422) above the amount held. The customer's
+        cached entitlement answers go stale.
+
+        reservation_id: the hold's ``id``.
+        body: ``amount`` to take; the whole hold when left out.
+        """
+        result: CreditReservationResponse = await self._client.request(confirm_reservation_spec(reservation_id, body))
+        expire_entitlements(self._client.entitlement_cache, [result["customer_external_id"]])
+        return result
+
+    async def release_reservation(self, reservation_id: str) -> CreditReservationResponse:
+        """Free a hold with nothing taken; an expired hold answers ``status: "expired"``, a settled one raises ``ConflictError`` (409).
+
+        The customer's cached entitlement answers go stale.
+
+        reservation_id: the hold's ``id``.
+        """
+        result: CreditReservationResponse = await self._client.request(release_reservation_spec(reservation_id))
+        expire_entitlements(self._client.entitlement_cache, [result["customer_external_id"]])
+        return result
+
+    async def reservation(self, reservation_id: str) -> CreditReservationResponse:
+        """One hold and how it ended: ``held``, ``confirmed``, ``released``, or ``expired`` once held past ``expires_at``.
+
+        reservation_id: the hold's ``id``.
+        """
+        result: CreditReservationResponse = await self._client.request(reservation_spec(reservation_id))
+        return result
+
+    async def balance(self, customer_id: str) -> CreditBalanceResponse:
+        """The customer's current position — amounts are decimal strings."""
+        result: CreditBalanceResponse = await self._client.request(balance_spec(customer_id))
+        return result
+
+    async def transactions(self, customer_id: str, *, limit: int | None = None, cursor: str | None = None) -> CreditTransactionPage:
+        """One page of the ledger, newest first.
+
+        The ledger grows with every charge, so it is read a page at a time: ``data`` holds the rows
+        and ``next_cursor`` the mark for the page after this one (``None`` on the last). Pass it
+        back as ``cursor`` unchanged — it is opaque, and nothing but this API reads it.
+        """
+        result: CreditTransactionPage = await self._client.request(transactions_spec(customer_id, limit, cursor))
+        return result

meterflow-0.6.0/src/meterflow/resources/entitlements.py

@@ -0,0 +1,223 @@
+"""Entitlements — ask BEFORE doing the work.
+
+``check()`` is where a hard limit says no; recording usage afterwards never blocks, so an app that
+skips this call gets no enforcement at all — only an honest ledger.
+
+``allowed: False`` is a normal answer, not an error: the call returns and ``reason`` says why
+(``no_subscription``, ``not_in_plan``, ``hard_limit_reached``, ``insufficient_credits``). A feature
+key the project does not know at all is a 404 → ``NotFoundError``, because that is a typo, not a plan.
+
+Answers are reused for the ``Cache-Control: max-age`` the API sends (15 s), per customer, feature and
+quantity, unless ``entitlements_cache=False``. A usage record, grant or deduct for a customer makes
+their answers stale. While MeterFlow is unreachable, a call returns its last answer with
+``stale: True``, or else ``check()`` returns the ``entitlement_defaults`` entry for the feature.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Literal, TypedDict
+
+import httpx
+
+from .._entitlement_cache import CacheRead, EntitlementFallbackContext, is_outage, max_age_seconds
+from .._http import RequestSpec, encode_path_segment
+from ..types import EntitlementReason, EntitlementsResponse, FeatureType
+
+if TYPE_CHECKING:
+    from ..client import AsyncMeterFlow, MeterFlow, _BaseClient
+
+
+class _EntitlementCheckRequired(TypedDict):
+    feature: str
+    feature_type: FeatureType | None
+    allowed: bool
+
+
+class EntitlementCheck(_EntitlementCheckRequired, total=False):
+    """What ``check()`` returns: the API's ``EntitlementResponse``, or a fallback while MeterFlow is unreachable.
+
+    ``stale: True`` marks the last answer reused past its ``max-age``; ``reason: "offline_default"`` marks
+    your ``entitlement_defaults`` entry, which knows nothing of the plan, so its ``feature_type`` is None.
+    The other keys are ``EntitlementResponse``'s, repeated because a generated type cannot be widened.
+    """
+
+    reason: EntitlementReason | Literal["offline_default"] | None
+    limit_type: str | None
+    included: int | None
+    used: str | None
+    remaining: str | None
+    period_start: str | None
+    period_end: str | None
+    stale: bool
+
+
+class EntitlementList(EntitlementsResponse, total=False):
+    """What ``get()`` returns: the API's answer, with ``stale: True`` when it is the last one reused during an outage."""
+
+    stale: bool
+
+
+def get_spec(customer_id: str) -> RequestSpec:
+    return RequestSpec("GET", f"entitlements/{encode_path_segment(customer_id)}")
+
+
+def check_spec(customer_id: str, feature: str, quantity: int | None) -> RequestSpec:
+    return RequestSpec("GET", f"entitlements/{encode_path_segment(customer_id)}/check", query={"feature": feature, "quantity": quantity})
+
+
+def _get_key(customer_id: str) -> str:
+    return f"get\0{customer_id}"
+
+
+def _check_key(customer_id: str, feature: str, quantity: int | None) -> str:
+    return f"check\0{customer_id}\0{feature}\0{quantity or 1}"
+
+
+class _Answer:
+    """One entitlements call's cache handling, shared by the sync and async resources, which only differ in how they wait.
+
+    client: the client whose cache and options apply.
+    key: the call's cache key.
+    customer_id: the customer the call is for.
+    feature: the feature checked; None for ``get()``, which has no default.
+    """
+
+    def __init__(self, client: _BaseClient, key: str, customer_id: str, feature: str | None) -> None:
+        self._client = client
+        self._key = key
+        self._customer_id = customer_id
+        self._feature = feature
+        self._max_age = 0
+        self.cached: CacheRead | None = client.entitlement_cache.read(key) if client.entitlement_cache is not None else None
+
+    def read_headers(self, headers: httpx.Headers) -> None:
+        """Note the response's ``max-age``.
+
+        headers: the successful response's headers.
+        """
+        self._max_age = max_age_seconds(headers.get("cache-control"))
+
+    def keep(self, value: Any) -> Any:
+        """Store a fresh answer for its ``max-age``, and return it.
+
+        value: the API's answer.
+        """
+        if self._client.entitlement_cache is not None:
+            self._client.entitlement_cache.write(self._key, self._customer_id, value, self._max_age)
+        return value
+
+    def fallback(self, error: Exception) -> Any:
+        """The answer for a failed call: the last one marked stale, else the feature's default.
+
+        Re-raises ``error`` when it was an answer rather than an outage, or when there is nothing to fall back on.
+
+        error: what the call raised.
+        """
+        if not is_outage(error):
+            raise error
+        if self.cached is not None:
+            self._tell(error, "stale")
+            return {**self.cached.value, "stale": True}
+        default = None if self._feature is None else self._offline_default(self._feature)
+        if default is None:
+            raise error
+        self._tell(error, "default")
+        return default
+
+    def _offline_default(self, feature: str) -> EntitlementCheck | None:
+        """The configured answer for a feature: its own entry, else ``"*"``; None when neither is set.
+
+        feature: the feature checked.
+        """
+        defaults = self._client.options.entitlement_defaults
+        setting = defaults.get(feature, defaults.get("*"))
+        if setting is None:
+            return None
+        return {"feature": feature, "feature_type": None, "allowed": setting == "allow", "reason": "offline_default"}
+
+    def _tell(self, error: Exception, fallback: Literal["stale", "default"]) -> None:
+        """Hand the error and the fallback to ``on_error``, ignoring anything it raises: it is the caller's code.
+
+        error: what the call raised.
+        fallback: what the call answers with instead.
+        """
+        on_error: Callable[[Exception, EntitlementFallbackContext], None] | None = self._client.options.on_error
+        if on_error is None:
+            return
+        try:
+            on_error(error, EntitlementFallbackContext(self._customer_id, self._feature, fallback))
+        except Exception:  # noqa: S110 — the hook is the caller's; its failure must not undo the fallback
+            pass
+
+
+class EntitlementsResource:
+    def __init__(self, client: MeterFlow) -> None:
+        self._client = client
+
+    def get(self, customer_id: str) -> EntitlementList:
+        """Every feature on the customer's plan, with this period's usage; a metered row answers for the next unit, as ``check()`` would.
+
+        Empty ``entitlements`` without a subscription.
+        customer_id: the customer asked about.
+        """
+        return self._answer(_Answer(self._client, _get_key(customer_id), customer_id, None), get_spec(customer_id))  # type: ignore[no-any-return]
+
+    def check(self, customer_id: str, feature: str, *, quantity: int | None = None) -> EntitlementCheck:
+        """May this customer use ``feature`` (``quantity`` more units of it — "may they do 5 more?") right now?
+
+        customer_id: the customer asked about.
+        feature: a meter's event name or a plan feature key.
+        quantity: how many more units the app is about to use; 1 on the server when None.
+        """
+        answer = _Answer(self._client, _check_key(customer_id, feature, quantity), customer_id, feature)
+        return self._answer(answer, check_spec(customer_id, feature, quantity))  # type: ignore[no-any-return]
+
+    def _answer(self, answer: _Answer, spec: RequestSpec) -> Any:
+        """Return the fresh cached answer, else the API's, else a fallback.
+
+        answer: the call's cache handling.
+        spec: the request to make when nothing fresh is cached.
+        """
+        if answer.cached is not None and answer.cached.fresh:
+            return answer.cached.value
+        try:
+            return answer.keep(self._client.request(spec, answer.read_headers))
+        except Exception as error:
+            return answer.fallback(error)
+
+
+class AsyncEntitlementsResource:
+    def __init__(self, client: AsyncMeterFlow) -> None:
+        self._client = client
+
+    async def get(self, customer_id: str) -> EntitlementList:
+        """Every feature on the customer's plan, with this period's usage; a metered row answers for the next unit, as ``check()`` would.
+
+        Empty ``entitlements`` without a subscription.
+        customer_id: the customer asked about.
+        """
+        return await self._answer(_Answer(self._client, _get_key(customer_id), customer_id, None), get_spec(customer_id))  # type: ignore[no-any-return]
+
+    async def check(self, customer_id: str, feature: str, *, quantity: int | None = None) -> EntitlementCheck:
+        """May this customer use ``feature`` (``quantity`` more units of it — "may they do 5 more?") right now?
+
+        customer_id: the customer asked about.
+        feature: a meter's event name or a plan feature key.
+        quantity: how many more units the app is about to use; 1 on the server when None.
+        """
+        answer = _Answer(self._client, _check_key(customer_id, feature, quantity), customer_id, feature)
+        return await self._answer(answer, check_spec(customer_id, feature, quantity))  # type: ignore[no-any-return]
+
+    async def _answer(self, answer: _Answer, spec: RequestSpec) -> Any:
+        """Return the fresh cached answer, else the API's, else a fallback.
+
+        answer: the call's cache handling.
+        spec: the request to make when nothing fresh is cached.
+        """
+        if answer.cached is not None and answer.cached.fresh:
+            return answer.cached.value
+        try:
+            return answer.keep(await self._client.request(spec, answer.read_headers))
+        except Exception as error:
+            return answer.fallback(error)

{meterflow-0.4.0 → meterflow-0.6.0}/src/meterflow/resources/usage.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
+from .._entitlement_cache import expire_entitlements
 from .._http import RequestSpec, encode_path_segment
 from ..errors import PayloadTooLargeError
 from ..types import UsageEventRequest, UsageEventResponse, UsageSummaryResponse
@@ -42,13 +43,18 @@ class UsageResource:
         self._client = client
 
     def record(self, body: UsageEventRequest, *, idempotency_key: str | None = None) -> UsageEventResponse:
-        """Record one event. Returns immediately (``processed: False``); totals materialise moments later."""
+        """Record one event. Returns immediately (``processed: False``); totals materialise moments later.
+
+        The customer's cached entitlement answers go stale.
+        """
         result: UsageEventResponse = self._client.request(record_spec(body, idempotency_key))
+        expire_entitlements(self._client.entitlement_cache, [body["customer_external_id"]])
         return result
 
     def record_batch(self, events: list[UsageEventRequest], *, idempotency_key: str | None = None) -> list[UsageEventResponse]:
         """Record up to ``MAX_BATCH_EVENTS`` events in one request. A larger list is refused locally, never sent."""
         result: list[UsageEventResponse] = self._client.request(record_batch_spec(events, idempotency_key))
+        expire_entitlements(self._client.entitlement_cache, [event["customer_external_id"] for event in events])
         return result
 
     def event(self, event_id: str) -> UsageEventResponse:
@@ -74,13 +80,18 @@ class AsyncUsageResource:
         self._client = client
 
     async def record(self, body: UsageEventRequest, *, idempotency_key: str | None = None) -> UsageEventResponse:
-        """Record one event. Returns immediately (``processed: False``); totals materialise moments later."""
+        """Record one event. Returns immediately (``processed: False``); totals materialise moments later.
+
+        The customer's cached entitlement answers go stale.
+        """
         result: UsageEventResponse = await self._client.request(record_spec(body, idempotency_key))
+        expire_entitlements(self._client.entitlement_cache, [body["customer_external_id"]])
         return result
 
     async def record_batch(self, events: list[UsageEventRequest], *, idempotency_key: str | None = None) -> list[UsageEventResponse]:
         """Record up to ``MAX_BATCH_EVENTS`` events in one request. A larger list is refused locally, never sent."""
         result: list[UsageEventResponse] = await self._client.request(record_batch_spec(events, idempotency_key))
+        expire_entitlements(self._client.entitlement_cache, [event["customer_external_id"] for event in events])
         return result
 
     async def event(self, event_id: str) -> UsageEventResponse:

{meterflow-0.4.0 → meterflow-0.6.0}/src/meterflow/types.py

@@ -17,6 +17,8 @@ EntitlementReason = Literal[
 
 FeatureType = Literal["boolean", "metered"]
 
+ReservationStatus = Literal["held", "confirmed", "released", "expired"]
+
 SubscriptionStatus = Literal["active", "trialing", "past_due", "paused", "canceled", "expired"]
 
 
@@ -31,6 +33,8 @@ class CreditBalanceResponse(TypedDict):
     version: int
     created_at: str
     updated_at: str
+    reserved: str
+    available: str
     usage_draws_credits: bool | None
 
 
@@ -56,6 +60,45 @@ class CreditGrantRequest(_CreditGrantRequestRequired, total=False):
     metadata: dict[str, Any]
 
 
+class CreditReservationConfirmRequest(TypedDict, total=False):
+    """Settle a hold: take some or all of it from the balance, and free the rest."""
+
+    amount: float | str | None
+
+
+class _CreditReservationRequestRequired(TypedDict):
+    customer_external_id: str
+    amount: float | str
+
+
+class CreditReservationRequest(_CreditReservationRequestRequired, total=False):
+    """Hold part of a customer's balance for a while, so other spending cannot take it first."""
+
+    ttl_seconds: int
+    description: str | None
+    idempotency_key: str | None
+    metadata: dict[str, Any]
+
+
+class CreditReservationResponse(TypedDict):
+    """A hold on part of a customer's balance, and how it ended."""
+
+    id: str
+    project_id: str
+    environment: str
+    customer_external_id: str
+    amount: str
+    status: ReservationStatus
+    expires_at: str
+    description: str | None
+    metadata_: dict[str, Any]
+    idempotency_key: str | None
+    confirmed_amount: str | None
+    transaction_id: str | None
+    created_at: str
+    settled_at: str | None
+
+
 class _CreditTransactionPageRequired(TypedDict):
     data: list[CreditTransactionResponse]
 
@@ -327,6 +370,9 @@ __all__ = [
     "CreditBalanceResponse",
     "CreditDeductRequest",
     "CreditGrantRequest",
+    "CreditReservationConfirmRequest",
+    "CreditReservationRequest",
+    "CreditReservationResponse",
     "CreditTransactionPage",
     "CreditTransactionResponse",
     "EntitlementReason",
@@ -337,6 +383,7 @@ __all__ = [
     "PlanResponse",
     "PortalLinkRequest",
     "PortalLinkResponse",
+    "ReservationStatus",
     "SubscriptionCreateRequest",
     "SubscriptionPage",
     "SubscriptionResponse",

meterflow-0.4.0/src/meterflow/resources/credits.py

@@ -1,87 +0,0 @@
-"""Credits — an append-only ledger per customer: grant up, deduct down, never edited in place."""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-from .._http import RequestSpec, encode_path_segment
-from ..types import CreditBalanceResponse, CreditDeductRequest, CreditGrantRequest, CreditTransactionPage, CreditTransactionResponse
-
-if TYPE_CHECKING:
-    from ..client import AsyncMeterFlow, MeterFlow
-
-
-def grant_spec(body: CreditGrantRequest, idempotency_key: str | None) -> RequestSpec:
-    return RequestSpec("POST", "credits/grant", body=body, idempotency_key=idempotency_key)
-
-
-def deduct_spec(body: CreditDeductRequest, idempotency_key: str | None) -> RequestSpec:
-    return RequestSpec("POST", "credits/deduct", body=body, idempotency_key=idempotency_key)
-
-
-def balance_spec(customer_id: str) -> RequestSpec:
-    return RequestSpec("GET", f"credits/{encode_path_segment(customer_id)}/balance")
-
-
-def transactions_spec(customer_id: str, limit: int | None, cursor: str | None) -> RequestSpec:
-    return RequestSpec("GET", f"credits/{encode_path_segment(customer_id)}/transactions", query={"limit": limit, "cursor": cursor})
-
-
-class CreditsResource:
-    def __init__(self, client: MeterFlow) -> None:
-        self._client = client
-
-    def grant(self, body: CreditGrantRequest, *, idempotency_key: str | None = None) -> CreditTransactionResponse:
-        """Add credits (plan renewals, top-ups, goodwill). Returns the ledger line."""
-        result: CreditTransactionResponse = self._client.request(grant_spec(body, idempotency_key))
-        return result
-
-    def deduct(self, body: CreditDeductRequest, *, idempotency_key: str | None = None) -> CreditTransactionResponse:
-        """Remove credits. Raises ``InsufficientCreditsError`` (402) rather than take the customer below zero."""
-        result: CreditTransactionResponse = self._client.request(deduct_spec(body, idempotency_key))
-        return result
-
-    def balance(self, customer_id: str) -> CreditBalanceResponse:
-        """The customer's current position — amounts are decimal strings."""
-        result: CreditBalanceResponse = self._client.request(balance_spec(customer_id))
-        return result
-
-    def transactions(self, customer_id: str, *, limit: int | None = None, cursor: str | None = None) -> CreditTransactionPage:
-        """One page of the ledger, newest first.
-
-        The ledger grows with every charge, so it is read a page at a time: ``data`` holds the rows
-        and ``next_cursor`` the mark for the page after this one (``None`` on the last). Pass it
-        back as ``cursor`` unchanged — it is opaque, and nothing but this API reads it.
-        """
-        result: CreditTransactionPage = self._client.request(transactions_spec(customer_id, limit, cursor))
-        return result
-
-
-class AsyncCreditsResource:
-    def __init__(self, client: AsyncMeterFlow) -> None:
-        self._client = client
-
-    async def grant(self, body: CreditGrantRequest, *, idempotency_key: str | None = None) -> CreditTransactionResponse:
-        """Add credits (plan renewals, top-ups, goodwill). Returns the ledger line."""
-        result: CreditTransactionResponse = await self._client.request(grant_spec(body, idempotency_key))
-        return result
-
-    async def deduct(self, body: CreditDeductRequest, *, idempotency_key: str | None = None) -> CreditTransactionResponse:
-        """Remove credits. Raises ``InsufficientCreditsError`` (402) rather than take the customer below zero."""
-        result: CreditTransactionResponse = await self._client.request(deduct_spec(body, idempotency_key))
-        return result
-
-    async def balance(self, customer_id: str) -> CreditBalanceResponse:
-        """The customer's current position — amounts are decimal strings."""
-        result: CreditBalanceResponse = await self._client.request(balance_spec(customer_id))
-        return result
-
-    async def transactions(self, customer_id: str, *, limit: int | None = None, cursor: str | None = None) -> CreditTransactionPage:
-        """One page of the ledger, newest first.
-
-        The ledger grows with every charge, so it is read a page at a time: ``data`` holds the rows
-        and ``next_cursor`` the mark for the page after this one (``None`` on the last). Pass it
-        back as ``cursor`` unchanged — it is opaque, and nothing but this API reads it.
-        """
-        result: CreditTransactionPage = await self._client.request(transactions_spec(customer_id, limit, cursor))
-        return result

meterflow-0.4.0/src/meterflow/resources/entitlements.py

@@ -1,66 +0,0 @@
-"""Entitlements — ask BEFORE doing the work.
-
-``check()`` is where a hard limit says no; recording usage afterwards never blocks, so an app that
-skips this call gets no enforcement at all — only an honest ledger.
-
-``allowed: False`` is a normal answer, not an error: the call returns and ``reason`` says why
-(``no_subscription``, ``not_in_plan``, ``hard_limit_reached``, ``insufficient_credits``). A feature
-key the project does not know at all is a 404 → ``NotFoundError``, because that is a typo, not a plan.
-
-Both calls return ``Cache-Control: private, max-age=15`` — cache per customer for a few seconds on
-hot paths rather than calling on every request.
-"""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-from .._http import RequestSpec, encode_path_segment
-from ..types import EntitlementResponse, EntitlementsResponse
-
-if TYPE_CHECKING:
-    from ..client import AsyncMeterFlow, MeterFlow
-
-
-def get_spec(customer_id: str) -> RequestSpec:
-    return RequestSpec("GET", f"entitlements/{encode_path_segment(customer_id)}")
-
-
-def check_spec(customer_id: str, feature: str, quantity: int | None) -> RequestSpec:
-    return RequestSpec("GET", f"entitlements/{encode_path_segment(customer_id)}/check", query={"feature": feature, "quantity": quantity})
-
-
-class EntitlementsResource:
-    def __init__(self, client: MeterFlow) -> None:
-        self._client = client
-
-    def get(self, customer_id: str) -> EntitlementsResponse:
-        """Every feature on the customer's plan, with this period's usage; a metered row answers for the next unit, as ``check()`` would.
-
-        Empty ``entitlements`` without a subscription.
-        """
-        result: EntitlementsResponse = self._client.request(get_spec(customer_id))
-        return result
-
-    def check(self, customer_id: str, feature: str, *, quantity: int | None = None) -> EntitlementResponse:
-        """May this customer use ``feature`` (``quantity`` more units of it — "may they do 5 more?") right now?"""
-        result: EntitlementResponse = self._client.request(check_spec(customer_id, feature, quantity))
-        return result
-
-
-class AsyncEntitlementsResource:
-    def __init__(self, client: AsyncMeterFlow) -> None:
-        self._client = client
-
-    async def get(self, customer_id: str) -> EntitlementsResponse:
-        """Every feature on the customer's plan, with this period's usage; a metered row answers for the next unit, as ``check()`` would.
-
-        Empty ``entitlements`` without a subscription.
-        """
-        result: EntitlementsResponse = await self._client.request(get_spec(customer_id))
-        return result
-
-    async def check(self, customer_id: str, feature: str, *, quantity: int | None = None) -> EntitlementResponse:
-        """May this customer use ``feature`` (``quantity`` more units of it — "may they do 5 more?") right now?"""
-        result: EntitlementResponse = await self._client.request(check_spec(customer_id, feature, quantity))
-        return result