meterflow 0.4.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: meterflow
-Version: 0.4.0
+Version: 0.5.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
@@ -190,6 +190,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
 )
 ```
 
@@ -463,7 +466,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 +481,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()` or `credits.deduct()` 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.5.0}/README.md

@@ -138,6 +138,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
 )
 ```
 
@@ -411,7 +414,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 +429,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()` or `credits.deduct()` 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.5.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.5.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.5.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.5.0"

{meterflow-0.4.0 → meterflow-0.5.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.4.0 → meterflow-0.5.0}/src/meterflow/resources/credits.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 ..types import CreditBalanceResponse, CreditDeductRequest, CreditGrantRequest, CreditTransactionPage, CreditTransactionResponse
 
@@ -32,13 +33,18 @@ class CreditsResource:
         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."""
+        """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."""
+        """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 balance(self, customer_id: str) -> CreditBalanceResponse:
@@ -62,13 +68,18 @@ class AsyncCreditsResource:
         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."""
+        """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."""
+        """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 balance(self, customer_id: str) -> CreditBalanceResponse:

meterflow-0.5.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.5.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/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