meterflow 0.3.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: meterflow
-Version: 0.3.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
@@ -59,6 +59,10 @@ Official Python SDK for [MeterFlow](https://meter-flow.com) — usage-based bill
 
 Track what your customers use, enforce credit balances, gate features, and manage subscriptions with a few lines of code. Fully typed, sync **and** async, one dependency (`httpx`).
 
+- **Flat $29, never a percentage of your revenue.** MeterFlow's [plans](https://meter-flow.com/pricing) follow how many usage events you send, not what your customers pay you.
+- **Works next to any payment provider.** MeterFlow never moves money: your provider charges your customers, and this SDK records their usage, keeps their credit balances and asks whether they may go on. Paddle, Polar, Lemon Squeezy, Chargebee and Razorpay connect from the dashboard; anything else calls `credits.grant` when a payment lands.
+- **Test and live by key prefix.** An `mf_test_` key reads and writes test data, an `mf_live_` key live data — the same code, two worlds that never mix.
+
 ---
 
 ## Contents
@@ -186,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
 )
 ```
 
@@ -234,8 +241,11 @@ 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["usage_draws_credits"]  # True | False | None
 ```
 
+`usage_draws_credits` says whether the customer's plan charges usage to this balance: `True` when a metered limit carries a rate, `False` when the plan never does (the balance then moves only through your own `credits.deduct`), `None` without an active or trialing subscription.
+
 **Transactions** — the history, newest first, **a page at a time**:
 
 ```python
@@ -371,6 +381,7 @@ print(sub["status"])  # "trialing" if the plan has trial days, else "active"
 page = client.subscriptions.list()                              # whole project (in your key's environment)
 theirs = client.subscriptions.list(customer_id="customer_123")  # one customer
 more = client.subscriptions.list(limit=200, cursor=page["next_cursor"])
+behind = client.subscriptions.list(q="acme", status=["past_due", "paused"])  # ids containing "acme", in either status
 
 for subscription in page["data"]:
     print(subscription["customer_external_id"], subscription["status"])
@@ -421,13 +432,17 @@ receipts[0]["event_type"]     # "usage.recorded"
 receipts[0]["status"]         # "pending" | "retrying" | "success" | "failed"
 receipts[0]["response_code"]  # what your server answered — 200, 500, or None if it never answered
 receipts[0]["attempts"]       # how many times we have tried
-receipts[0]["next_retry_at"]  # when we will try again, or None
 receipts[0]["payload"]        # exactly what we sent
+
+page = client.webhooks.delivery_page(endpoint_id, limit=200)                  # the same rows, a page at a time
+older = client.webhooks.delivery_page(endpoint_id, cursor=page["next_cursor"])  # None on the last page
 ```
 
+A delivery is tried up to five times: at once, then after 30 s, 5 min, 30 min and 2 h, each later try scheduled through the queue, where it survives a worker restart. `attempts` counts the tries; the receipt shows `pending` before the first try and `retrying` between tries.
+
 Typical use: answering "did that event reach my endpoint?" from your own tooling instead of opening the dashboard — and reading `response_body` when the answer is no.
 
-Two things to know. The list is capped at the **most recent 100** attempts per endpoint; it is a debugging surface, not an export. And it follows your key: a `mf_test_*` key reads test receipts, a `mf_live_*` key live ones, while the endpoint list itself is shared by both worlds, because an endpoint is configuration and receives events from each.
+Two things to know. `deliveries()` returns the **most recent 100** attempts per endpoint; `delivery_page()` reads further back, one page at a time. And both follow your key: a `mf_test_*` key reads test receipts, a `mf_live_*` key live ones, while the endpoint list itself is shared by both worlds, because an endpoint is configuration and receives events from each.
 
 > This is not the same as [verifying webhooks](#verifying-webhooks) below. That proves a request your server just received really came from us; this reads what we sent.
 
@@ -451,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:
 
@@ -462,8 +477,35 @@ result["entitlements"]
 #  {"feature": "images.generated", "feature_type": "metered", "used": "120", "included": 500, "remaining": "380", ...}]
 ```
 
+Each metered row answers for the **next** unit, exactly as `check()` would, so its `allowed` and `reason` match the gate. Reading the list fires no webhook; only `check()` announces `balance.exhausted`.
+
 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.
@@ -502,6 +544,8 @@ client.credits.deduct(
 
 Every write method accepts the keyword: `credits.grant/deduct`, `usage.record/record_batch`, `subscriptions.create/update`. Use a key that identifies the *business operation* (order ID, job ID) — not a random value per attempt, which would defeat the purpose.
 
+MeterFlow remembers a key for 24 hours; after that the same key starts a new operation, so a retry must come within the day (a late subscription retry meets the one-per-customer rule instead of replaying).
+
 **A key is bound to the body you first used it with.** MeterFlow stores a fingerprint of the request alongside the key, so a retry only replays when it is genuinely the same request. Reuse the key with a *different* body and the call is refused with `ConflictError` (409) instead of quietly handing back the original record:
 
 ```python
@@ -604,7 +648,7 @@ Every delivery is a flat JSON object (`Content-Type: application/json`) with two
 | `limit.reached` | a customer first reaches a **hard** or **soft** limit's included units this billing period (once per meter per period; metered limits report through `credit.deducted` instead) | `customer_id`, `subscription_id`, `feature` (the meter's `event_name`), `meter_id`, `limit_type`, `included`, `used`, `period_start`, `period_end` |
 | `balance.low` | a spend takes a customer's balance **down through** this endpoint's `low_balance_threshold` — a crossing, so it fires once and not again while they stay below. Raised by both doors that spend: `credits.deduct` and a metered usage charge. **Both crossing events follow from the endpoint's `low_balance_threshold`: set one and the API adds them, clear it and the API removes them — so a line is the only thing to configure.** | `customer_id`, `balance`, `threshold`, `suggested_topup` (the subscription's `topup_amount`, `null` when unset), `transaction_id` |
 | `balance.exhausted` | a balance reaches zero, **or** a request is refused for want of credits (a deduction returning 402, or `entitlements.check` answering `insufficient_credits`). Unlike `balance.low` this repeats: every refused request is its own blocked request | `customer_id`, `balance`, `reason` (`balance_zero` / `insufficient_credits`), `requested_amount` and `feature` where they apply, `transaction_id` on the zero case |
-| `subscription.renewed` | a billing period opens — either a paid period rolling forward or a **trial converting** to its first paid period, told apart by `reason` (the renewer emits no `subscription.updated` for either) | `customer_id`, `subscription_id`, `plan_id`, `status`, `reason` (`period_renewed` / `trial_converted`), `current_period_start`, `current_period_end`, `credits_granted` |
+| `subscription.renewed` | a billing period opens — a paid period rolling forward, a **trial converting** to its first paid period, or a canceled subscription **reactivated** after its period lapsed, told apart by `reason` (the renewer emits no `subscription.updated` for the first two) | `customer_id`, `subscription_id`, `plan_id`, `status`, `reason` (`period_renewed` / `trial_converted` / `period_reactivated`), `current_period_start`, `current_period_end`, `credits_granted` |
 | `subscription.canceled` | a subscription's status becomes canceled — fired **alongside** `subscription.updated`, once, on the call that actually cancels | `customer_id`, `subscription_id`, `plan_id`, `canceled_at` |
 | `balance.topped_up` | a grant takes a customer's balance **up through** this endpoint's `low_balance_threshold` — the upward mirror of `balance.low`, on the same per-endpoint line, so the endpoint told "low" is the one told "recovered". Subscribed together with `balance.low` by setting the threshold, never on its own | `customer_id`, `balance`, `threshold`, `amount`, `transaction_id` |
 | `cap.reached` | a customer's credit spending reaches their subscription's `spend_cap` for the period — once per subscription per period, whether they landed on the cap or were refused by it. A refusal that still leaves headroom is not a reach and does not fire | `customer_id`, `subscription_id`, `cap`, `spent`, `period_start`, `period_end` |

{meterflow-0.3.0 → meterflow-0.5.0}/README.md

@@ -7,6 +7,10 @@ Official Python SDK for [MeterFlow](https://meter-flow.com) — usage-based bill
 
 Track what your customers use, enforce credit balances, gate features, and manage subscriptions with a few lines of code. Fully typed, sync **and** async, one dependency (`httpx`).
 
+- **Flat $29, never a percentage of your revenue.** MeterFlow's [plans](https://meter-flow.com/pricing) follow how many usage events you send, not what your customers pay you.
+- **Works next to any payment provider.** MeterFlow never moves money: your provider charges your customers, and this SDK records their usage, keeps their credit balances and asks whether they may go on. Paddle, Polar, Lemon Squeezy, Chargebee and Razorpay connect from the dashboard; anything else calls `credits.grant` when a payment lands.
+- **Test and live by key prefix.** An `mf_test_` key reads and writes test data, an `mf_live_` key live data — the same code, two worlds that never mix.
+
 ---
 
 ## Contents
@@ -134,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
 )
 ```
 
@@ -182,8 +189,11 @@ 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["usage_draws_credits"]  # True | False | None
 ```
 
+`usage_draws_credits` says whether the customer's plan charges usage to this balance: `True` when a metered limit carries a rate, `False` when the plan never does (the balance then moves only through your own `credits.deduct`), `None` without an active or trialing subscription.
+
 **Transactions** — the history, newest first, **a page at a time**:
 
 ```python
@@ -319,6 +329,7 @@ print(sub["status"])  # "trialing" if the plan has trial days, else "active"
 page = client.subscriptions.list()                              # whole project (in your key's environment)
 theirs = client.subscriptions.list(customer_id="customer_123")  # one customer
 more = client.subscriptions.list(limit=200, cursor=page["next_cursor"])
+behind = client.subscriptions.list(q="acme", status=["past_due", "paused"])  # ids containing "acme", in either status
 
 for subscription in page["data"]:
     print(subscription["customer_external_id"], subscription["status"])
@@ -369,13 +380,17 @@ receipts[0]["event_type"]     # "usage.recorded"
 receipts[0]["status"]         # "pending" | "retrying" | "success" | "failed"
 receipts[0]["response_code"]  # what your server answered — 200, 500, or None if it never answered
 receipts[0]["attempts"]       # how many times we have tried
-receipts[0]["next_retry_at"]  # when we will try again, or None
 receipts[0]["payload"]        # exactly what we sent
+
+page = client.webhooks.delivery_page(endpoint_id, limit=200)                  # the same rows, a page at a time
+older = client.webhooks.delivery_page(endpoint_id, cursor=page["next_cursor"])  # None on the last page
 ```
 
+A delivery is tried up to five times: at once, then after 30 s, 5 min, 30 min and 2 h, each later try scheduled through the queue, where it survives a worker restart. `attempts` counts the tries; the receipt shows `pending` before the first try and `retrying` between tries.
+
 Typical use: answering "did that event reach my endpoint?" from your own tooling instead of opening the dashboard — and reading `response_body` when the answer is no.
 
-Two things to know. The list is capped at the **most recent 100** attempts per endpoint; it is a debugging surface, not an export. And it follows your key: a `mf_test_*` key reads test receipts, a `mf_live_*` key live ones, while the endpoint list itself is shared by both worlds, because an endpoint is configuration and receives events from each.
+Two things to know. `deliveries()` returns the **most recent 100** attempts per endpoint; `delivery_page()` reads further back, one page at a time. And both follow your key: a `mf_test_*` key reads test receipts, a `mf_live_*` key live ones, while the endpoint list itself is shared by both worlds, because an endpoint is configuration and receives events from each.
 
 > This is not the same as [verifying webhooks](#verifying-webhooks) below. That proves a request your server just received really came from us; this reads what we sent.
 
@@ -399,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:
 
@@ -410,8 +425,35 @@ result["entitlements"]
 #  {"feature": "images.generated", "feature_type": "metered", "used": "120", "included": 500, "remaining": "380", ...}]
 ```
 
+Each metered row answers for the **next** unit, exactly as `check()` would, so its `allowed` and `reason` match the gate. Reading the list fires no webhook; only `check()` announces `balance.exhausted`.
+
 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.
@@ -450,6 +492,8 @@ client.credits.deduct(
 
 Every write method accepts the keyword: `credits.grant/deduct`, `usage.record/record_batch`, `subscriptions.create/update`. Use a key that identifies the *business operation* (order ID, job ID) — not a random value per attempt, which would defeat the purpose.
 
+MeterFlow remembers a key for 24 hours; after that the same key starts a new operation, so a retry must come within the day (a late subscription retry meets the one-per-customer rule instead of replaying).
+
 **A key is bound to the body you first used it with.** MeterFlow stores a fingerprint of the request alongside the key, so a retry only replays when it is genuinely the same request. Reuse the key with a *different* body and the call is refused with `ConflictError` (409) instead of quietly handing back the original record:
 
 ```python
@@ -552,7 +596,7 @@ Every delivery is a flat JSON object (`Content-Type: application/json`) with two
 | `limit.reached` | a customer first reaches a **hard** or **soft** limit's included units this billing period (once per meter per period; metered limits report through `credit.deducted` instead) | `customer_id`, `subscription_id`, `feature` (the meter's `event_name`), `meter_id`, `limit_type`, `included`, `used`, `period_start`, `period_end` |
 | `balance.low` | a spend takes a customer's balance **down through** this endpoint's `low_balance_threshold` — a crossing, so it fires once and not again while they stay below. Raised by both doors that spend: `credits.deduct` and a metered usage charge. **Both crossing events follow from the endpoint's `low_balance_threshold`: set one and the API adds them, clear it and the API removes them — so a line is the only thing to configure.** | `customer_id`, `balance`, `threshold`, `suggested_topup` (the subscription's `topup_amount`, `null` when unset), `transaction_id` |
 | `balance.exhausted` | a balance reaches zero, **or** a request is refused for want of credits (a deduction returning 402, or `entitlements.check` answering `insufficient_credits`). Unlike `balance.low` this repeats: every refused request is its own blocked request | `customer_id`, `balance`, `reason` (`balance_zero` / `insufficient_credits`), `requested_amount` and `feature` where they apply, `transaction_id` on the zero case |
-| `subscription.renewed` | a billing period opens — either a paid period rolling forward or a **trial converting** to its first paid period, told apart by `reason` (the renewer emits no `subscription.updated` for either) | `customer_id`, `subscription_id`, `plan_id`, `status`, `reason` (`period_renewed` / `trial_converted`), `current_period_start`, `current_period_end`, `credits_granted` |
+| `subscription.renewed` | a billing period opens — a paid period rolling forward, a **trial converting** to its first paid period, or a canceled subscription **reactivated** after its period lapsed, told apart by `reason` (the renewer emits no `subscription.updated` for the first two) | `customer_id`, `subscription_id`, `plan_id`, `status`, `reason` (`period_renewed` / `trial_converted` / `period_reactivated`), `current_period_start`, `current_period_end`, `credits_granted` |
 | `subscription.canceled` | a subscription's status becomes canceled — fired **alongside** `subscription.updated`, once, on the call that actually cancels | `customer_id`, `subscription_id`, `plan_id`, `canceled_at` |
 | `balance.topped_up` | a grant takes a customer's balance **up through** this endpoint's `low_balance_threshold` — the upward mirror of `balance.low`, on the same per-endpoint line, so the endpoint told "low" is the one told "recovered". Subscribed together with `balance.low` by setting the threshold, never on its own | `customer_id`, `balance`, `threshold`, `amount`, `transaction_id` |
 | `cap.reached` | a customer's credit spending reaches their subscription's `spend_cap` for the period — once per subscription per period, whether they landed on the cap or were refused by it. A refusal that still leaves headroom is not a reach and does not fire | `customer_id`, `subscription_id`, `cap`, `spent`, `period_start`, `period_end` |

{meterflow-0.3.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.3.0 → meterflow-0.5.0}/src/meterflow/_http.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import asyncio
 import json
 import time
+from collections.abc import Sequence
 from dataclasses import dataclass, field
 from typing import Any
 from urllib.parse import quote
@@ -31,7 +32,7 @@ from .errors import (
 
 USER_AGENT = f"meterflow-python/{__version__}"
 
-QueryValue = str | int | float | bool | None
+QueryValue = str | int | float | bool | Sequence[str] | None
 
 # Indirections so tests can make the retry loop instantaneous without touching the clock.
 _sleep = time.sleep
@@ -67,13 +68,18 @@ def build_headers(api_key: str, spec: RequestSpec) -> dict[str, str]:
     return headers
 
 
-def build_params(query: dict[str, QueryValue]) -> dict[str, str]:
-    """Unset (``None``) filters are simply not sent; booleans go as ``true``/``false`` like the Node SDK."""
-    params: dict[str, str] = {}
+def build_params(query: dict[str, QueryValue]) -> dict[str, str | list[str]]:
+    """Unset (``None``) filters are simply not sent; booleans go as ``true``/``false`` like the Node SDK; a list repeats its key."""
+    params: dict[str, str | list[str]] = {}
     for key, value in query.items():
         if value is None:
             continue
-        params[key] = ("true" if value else "false") if isinstance(value, bool) else str(value)
+        if isinstance(value, bool):
+            params[key] = "true" if value else "false"
+        elif isinstance(value, str | int | float):
+            params[key] = str(value)
+        else:
+            params[key] = [str(item) for item in value]
     return params
 
 

{meterflow-0.3.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.3.0"
+__version__ = "0.5.0"

{meterflow-0.3.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.3.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.3.0 → meterflow-0.5.0}/src/meterflow/resources/subscriptions.py

@@ -2,10 +2,11 @@
 
 from __future__ import annotations
 
+from collections.abc import Sequence
 from typing import TYPE_CHECKING
 
 from .._http import RequestSpec, encode_path_segment
-from ..types import SubscriptionCreateRequest, SubscriptionPage, SubscriptionResponse, SubscriptionUpdateRequest
+from ..types import SubscriptionCreateRequest, SubscriptionPage, SubscriptionResponse, SubscriptionStatus, SubscriptionUpdateRequest
 
 if TYPE_CHECKING:
     from ..client import AsyncMeterFlow, MeterFlow
@@ -15,8 +16,12 @@ def create_spec(body: SubscriptionCreateRequest, idempotency_key: str | None) ->
     return RequestSpec("POST", "subscriptions", body=body, idempotency_key=idempotency_key)
 
 
-def list_spec(customer_id: str | None, limit: int | None, cursor: str | None) -> RequestSpec:
-    return RequestSpec("GET", "subscriptions", query={"customer_id": customer_id, "limit": limit, "cursor": cursor})
+def list_spec(
+    customer_id: str | None, q: str | None, status: Sequence[SubscriptionStatus] | None, limit: int | None, cursor: str | None
+) -> RequestSpec:
+    return RequestSpec(
+        "GET", "subscriptions", query={"customer_id": customer_id, "q": q, "status": status, "limit": limit, "cursor": cursor}
+    )
 
 
 def get_spec(subscription_id: str) -> RequestSpec:
@@ -40,14 +45,24 @@ class SubscriptionsResource:
         result: SubscriptionResponse = self._client.request(create_spec(body, idempotency_key))
         return result
 
-    def list(self, *, customer_id: str | None = None, limit: int | None = None, cursor: str | None = None) -> SubscriptionPage:
+    def list(
+        self,
+        *,
+        customer_id: str | None = None,
+        q: str | None = None,
+        status: Sequence[SubscriptionStatus] | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> SubscriptionPage:
         """One page of the project's subscriptions in this key's environment, newest first.
 
         ``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. ``customer_id`` narrows the list to one customer.
+        reads it — with the same filters, which apply before the page is cut. ``customer_id``
+        narrows the list to one customer, matched exactly; ``q`` to customers whose id contains it,
+        ignoring case (``%`` and ``_`` are literal); ``status`` to subscriptions in one of those statuses.
         """
-        result: SubscriptionPage = self._client.request(list_spec(customer_id, limit, cursor))
+        result: SubscriptionPage = self._client.request(list_spec(customer_id, q, status, limit, cursor))
         return result
 
     def get(self, subscription_id: str) -> SubscriptionResponse:
@@ -73,14 +88,24 @@ class AsyncSubscriptionsResource:
         result: SubscriptionResponse = await self._client.request(create_spec(body, idempotency_key))
         return result
 
-    async def list(self, *, customer_id: str | None = None, limit: int | None = None, cursor: str | None = None) -> SubscriptionPage:
+    async def list(
+        self,
+        *,
+        customer_id: str | None = None,
+        q: str | None = None,
+        status: Sequence[SubscriptionStatus] | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> SubscriptionPage:
         """One page of the project's subscriptions in this key's environment, newest first.
 
         ``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. ``customer_id`` narrows the list to one customer.
+        reads it — with the same filters, which apply before the page is cut. ``customer_id``
+        narrows the list to one customer, matched exactly; ``q`` to customers whose id contains it,
+        ignoring case (``%`` and ``_`` are literal); ``status`` to subscriptions in one of those statuses.
         """
-        result: SubscriptionPage = await self._client.request(list_spec(customer_id, limit, cursor))
+        result: SubscriptionPage = await self._client.request(list_spec(customer_id, q, status, limit, cursor))
         return result
 
     async def get(self, subscription_id: str) -> SubscriptionResponse:

{meterflow-0.3.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.3.0 → meterflow-0.5.0}/src/meterflow/resources/webhooks.py

@@ -13,7 +13,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from .._http import RequestSpec, encode_path_segment
-from ..types import WebhookDeliveryResponse, WebhookResponse
+from ..types import WebhookDeliveryPage, WebhookDeliveryResponse, WebhookResponse
 
 if TYPE_CHECKING:
     from ..client import AsyncMeterFlow, MeterFlow
@@ -35,6 +35,16 @@ def deliveries_spec(webhook_id: str) -> RequestSpec:
     return RequestSpec("GET", f"webhooks/{encode_path_segment(webhook_id)}/deliveries")
 
 
+def delivery_page_spec(webhook_id: str, limit: int | None, cursor: str | None) -> RequestSpec:
+    """The request for one page of an endpoint's delivery attempts.
+
+    webhook_id: the endpoint whose receipts are read.
+    limit: rows per page, 1–200; None for the API's default.
+    cursor: ``next_cursor`` of the page before; None for the first page.
+    """
+    return RequestSpec("GET", f"webhooks/{encode_path_segment(webhook_id)}/deliveries/page", query={"limit": limit, "cursor": cursor})
+
+
 class WebhooksResource:
     def __init__(self, client: MeterFlow) -> None:
         self._client = client
@@ -54,6 +64,20 @@ class WebhooksResource:
         result: DeliveryList = self._client.request(deliveries_spec(webhook_id))
         return result
 
+    def delivery_page(self, webhook_id: str, *, limit: int | None = None, cursor: str | None = None) -> WebhookDeliveryPage:
+        """One page of an endpoint's delivery attempts, newest first, with no cap on how far back it reads.
+
+        The same rows as ``deliveries()``, in the environment of the key. ``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.
+
+        webhook_id: the endpoint whose receipts are read.
+        limit: rows per page, 1–200; None for the API's default (50).
+        cursor: ``next_cursor`` of the page before; None for the first page.
+        """
+        result: WebhookDeliveryPage = self._client.request(delivery_page_spec(webhook_id, limit, cursor))
+        return result
+
 
 class AsyncWebhooksResource:
     def __init__(self, client: AsyncMeterFlow) -> None:
@@ -73,3 +97,17 @@ class AsyncWebhooksResource:
         """
         result: DeliveryList = await self._client.request(deliveries_spec(webhook_id))
         return result
+
+    async def delivery_page(self, webhook_id: str, *, limit: int | None = None, cursor: str | None = None) -> WebhookDeliveryPage:
+        """One page of an endpoint's delivery attempts, newest first, with no cap on how far back it reads.
+
+        The same rows as ``deliveries()``, in the environment of the key. ``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.
+
+        webhook_id: the endpoint whose receipts are read.
+        limit: rows per page, 1–200; None for the API's default (50).
+        cursor: ``next_cursor`` of the page before; None for the first page.
+        """
+        result: WebhookDeliveryPage = await self._client.request(delivery_page_spec(webhook_id, limit, cursor))
+        return result

{meterflow-0.3.0 → meterflow-0.5.0}/src/meterflow/types.py

@@ -31,6 +31,7 @@ class CreditBalanceResponse(TypedDict):
     version: int
     created_at: str
     updated_at: str
+    usage_draws_credits: bool | None
 
 
 class _CreditDeductRequestRequired(TypedDict):
@@ -119,6 +120,8 @@ class PlanMeterLimitResponse(TypedDict):
 
 
 class PlanResponse(TypedDict):
+    created_by: str | None
+    created_by_email: str | None
     id: str
     project_id: str
     name: str
@@ -261,6 +264,7 @@ class _UsageSummaryItemRequired(TypedDict):
     meter_name: str
     event_name: str
     aggregation_type: str
+    aggregation_field: str | None
     value: str
     event_count: int
 
@@ -278,6 +282,16 @@ class UsageSummaryResponse(TypedDict):
     meters: list[UsageSummaryItem]
 
 
+class _WebhookDeliveryPageRequired(TypedDict):
+    data: list[WebhookDeliveryResponse]
+
+
+class WebhookDeliveryPage(_WebhookDeliveryPageRequired, total=False):
+    """One page of an endpoint's delivery attempts, newest first; pass `next_cursor` back as `cursor` for the next."""
+
+    next_cursor: str | None
+
+
 class WebhookDeliveryResponse(TypedDict):
     id: str
     webhook_id: str
@@ -287,7 +301,6 @@ class WebhookDeliveryResponse(TypedDict):
     response_code: int | None
     response_body: str | None
     attempts: int
-    next_retry_at: str | None
     created_at: str
     completed_at: str | None
 
@@ -295,6 +308,8 @@ class WebhookDeliveryResponse(TypedDict):
 class WebhookResponse(TypedDict):
     """Returned on all reads — secret is never included."""
 
+    created_by: str | None
+    created_by_email: str | None
     id: str
     project_id: str
     url: str
@@ -332,6 +347,7 @@ __all__ = [
     "UsageEventResponse",
     "UsageSummaryItem",
     "UsageSummaryResponse",
+    "WebhookDeliveryPage",
     "WebhookDeliveryResponse",
     "WebhookResponse",
 ]

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

@@ -1,60 +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. 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. 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