meterflow 0.2.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: meterflow
-Version: 0.2.0
+Version: 0.4.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
@@ -234,8 +238,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 +378,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 +429,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.
 
@@ -462,6 +474,8 @@ 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).
 
 ### The balance portal — a page you don't have to build
@@ -502,6 +516,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 +620,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.2.0 → meterflow-0.4.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
@@ -182,8 +186,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 +326,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 +377,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.
 
@@ -410,6 +422,8 @@ 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).
 
 ### The balance portal — a page you don't have to build
@@ -450,6 +464,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 +568,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.2.0 → meterflow-0.4.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.2.0 → meterflow-0.4.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.2.0"
+__version__ = "0.4.0"

{meterflow-0.2.0 → meterflow-0.4.0}/src/meterflow/resources/entitlements.py

@@ -35,7 +35,10 @@ class EntitlementsResource:
         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."""
+        """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
 
@@ -50,7 +53,10 @@ class AsyncEntitlementsResource:
         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."""
+        """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
 

{meterflow-0.2.0 → meterflow-0.4.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.2.0 → meterflow-0.4.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.2.0 → meterflow-0.4.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):
@@ -104,6 +105,7 @@ class EntitlementsResponse(TypedDict):
     environment: str
     subscription_id: str | None
     plan_id: str | None
+    plan_name: str | None
     period_end: str | None
     entitlements: list[EntitlementResponse]
 
@@ -118,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
@@ -260,6 +264,7 @@ class _UsageSummaryItemRequired(TypedDict):
     meter_name: str
     event_name: str
     aggregation_type: str
+    aggregation_field: str | None
     value: str
     event_count: int
 
@@ -277,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
@@ -286,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
 
@@ -294,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
@@ -331,6 +347,7 @@ __all__ = [
     "UsageEventResponse",
     "UsageSummaryItem",
     "UsageSummaryResponse",
+    "WebhookDeliveryPage",
     "WebhookDeliveryResponse",
     "WebhookResponse",
 ]