meterflow 0.1.2__tar.gz → 0.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: meterflow
-Version: 0.1.2
+Version: 0.2.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
@@ -75,6 +75,7 @@ Track what your customers use, enforce credit balances, gate features, and manag
   - [Usage events](#usage-events)
   - [Subscriptions](#subscriptions)
   - [Plans](#plans)
+  - [Webhook receipts](#webhook-receipts)
   - [Entitlements — ask before you act](#entitlements--ask-before-you-act)
 - [Idempotency — safe retries for writes](#idempotency--safe-retries-for-writes)
 - [Automatic retries](#automatic-retries)
@@ -235,13 +236,26 @@ bal["total_granted"]   # "5250.000000"
 bal["total_consumed"]  # "1705.000000"
 ```
 
-**Transactions** — the full history, newest first:
+**Transactions** — the history, newest first, **a page at a time**:
 
 ```python
-for t in client.credits.transactions("customer_123"):
+page = client.credits.transactions("customer_123")          # 50 rows by default
+for t in page["data"]:
     print(t["transaction_type"], t["amount"], t["balance_after"], t["description"], t["created_at"])
+
+# The whole history, page by page. `next_cursor` is None once there is nothing after it.
+cursor = None
+while True:
+    page = client.credits.transactions("customer_123", limit=200, cursor=cursor)
+    handle(page["data"])
+    cursor = page["next_cursor"]
+    if cursor is None:
+        break
 ```
 
+> **The cursor is opaque.** Pass back exactly what `next_cursor` gave you; do not build one, and do
+> not read anything out of it. `limit` is 1–200 and defaults to 50.
+
 > **Amounts are decimal strings.** Balances and amounts come back as strings (`"3545.000000"`) to avoid floating-point drift on money-like values. Parse deliberately (`decimal.Decimal(...)`) when you need arithmetic. When *sending* an amount, a number or a numeric string are both accepted.
 
 ### Usage events
@@ -254,7 +268,7 @@ Record an event every time a customer does the thing you charge for. Events are
 client.usage.record({
     "event_name": "images.generated",
     "customer_external_id": "customer_123",
-    "value": 1,                                   # what the meter aggregates: 1 for counts, seconds/MB/etc. for sums
+    "value": 1,                                   # optional — what the meter aggregates: 1 for counts, seconds/MB/etc. for sums
     "properties": {},                             # free-form context; {} when unused
     "timestamp": "2026-09-30T10:00:00Z",          # optional — defaults to arrival time on the server
 })
@@ -312,7 +326,8 @@ This is usually the difference between fitting a plan and outgrowing it: 1,000 u
 
 Two things to keep in mind:
 
-- **It only helps a `sum` meter.** A `count` meter ignores `value` and counts occurrences, so there each occurrence has to be its own event. `max`, `min` and `unique_count` read `value` as a measurement, not a quantity to add.
+- **It only helps a `sum` meter.** A `count` meter ignores `value` and counts occurrences, so there each occurrence has to be its own event. `max` and `min` read `value` as a measurement, not a quantity to add, and `unique_count` does not read it at all — it counts distinct values of the property its meter names.
+- **`value` is optional.** Leave it out and MeterFlow fills it in: for a `sum`, `max` or `min` meter that names an `aggregation_field`, the numeric value of that property on the event; otherwise `1`. So the event above can be written with `"properties": {"tokens": 1300}` and no `"value"`, as long as the meter's `aggregation_field` is `tokens`. An explicit `value` always wins, a property that is absent or is not a number falls through to `1`, and a negative one is refused with a `422`.
 - **Billing is unchanged.** A metered plan limit charges per unit — the event's `value` — so 100 units cost the same whether they arrived as 100 events or one. You are not rounding anyone's bill by batching.
 
 **Summary** — a customer's usage, broken down by meter:
@@ -353,8 +368,12 @@ print(sub["status"])  # "trialing" if the plan has trial days, else "active"
 **List / get:**
 
 ```python
-everyone = client.subscriptions.list()                          # whole project (in your key's environment)
+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"])
+
+for subscription in page["data"]:
+    print(subscription["customer_external_id"], subscription["status"])
 one = client.subscriptions.get(sub["id"])
 ```
 
@@ -391,6 +410,27 @@ plan["features"]        # ["sso", "priority-support"] — the on/off keys check(
 
 Typical use: render your pricing page or signup flow from `plans.list()` so it can never drift from what billing actually enforces.
 
+### Webhook receipts
+
+Webhooks are **read-only** through the SDK too: endpoints are registered in the dashboard, where the signing secret is shown once and never again. What the SDK gives you is the other half — which endpoints exist, and what MeterFlow actually sent them.
+
+```python
+endpoints = client.webhooks.list()                  # this project's endpoints
+receipts = client.webhooks.deliveries(endpoint_id)  # newest first
+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
+```
+
+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.
+
+> 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.
+
 ### Entitlements — ask before you act
 
 The one call to make **before** doing work for a customer: "may they use this feature — and how much is left?" A **hard** limit says no here; recording usage afterwards never blocks, so an app that skips this call gets an honest ledger but no enforcement.
@@ -399,7 +439,7 @@ The one call to make **before** doing work for a customer: "may they use this fe
 gate = client.entitlements.check("customer_123", "images.generated")
 
 if not gate["allowed"]:
-    # gate["reason"]: "hard_limit_reached" | "no_subscription" | "not_in_plan" | "insufficient_credits"
+    # gate["reason"]: "hard_limit_reached" | "no_subscription" | "not_in_plan" | "insufficient_credits" | "spend_cap_reached"
     return show_upgrade_prompt(gate)  # gate["used"] / gate["included"] / gate["period_end"] are there for the copy
 
 generate_image()
@@ -424,6 +464,30 @@ result["entitlements"]
 
 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
+
+Mint a short-lived link to a MeterFlow-hosted page showing **one** customer's balance and ledger.
+Call it from your server; send the ``url`` to that customer.
+
+```python
+link = client.portal.create_session({
+    "customer_external_id": "customer_123",
+    "topup_url": "https://acme.test/billing",   # your checkout — "buy more" goes here
+    "return_url": "https://acme.test/app",      # where "done" goes
+    "expires_in_minutes": 60,                   # default 60, maximum 1440
+})
+
+send_email(customer.email, f"Your balance: {link['url']}")
+```
+
+The token in that link reads **that one customer's** balance and ledger, in the environment of the
+key you minted it with, and nothing else: it cannot write, cannot name another customer, and is
+refused everywhere else in the API. It is never your API key — never send that to anyone.
+
+> **MeterFlow never takes the payment.** `topup_url` is a link we carry and hand back to the page;
+> what happens there is between you and your own payment provider. Grant the credits with
+> `credits.grant()` when your checkout tells you it was paid.
+
 ## Idempotency — safe retries for writes
 
 Connections drop. When your app can't tell whether a write arrived, the correct move is to send it again **with the same idempotency key** — MeterFlow recognises the key and acts only once:
@@ -538,10 +602,12 @@ Every delivery is a flat JSON object (`Content-Type: application/json`) with two
 | `subscription.created` | a subscription is created | `customer_id`, `plan_id`, `subscription_id`, `status` |
 | `subscription.updated` | a subscription is updated | `customer_id`, `subscription_id`, `status` |
 | `limit.reached` | a customer first reaches a **hard** or **soft** limit's included units this billing period (once per meter per period; metered limits report through `credit.deducted` instead) | `customer_id`, `subscription_id`, `feature` (the meter's `event_name`), `meter_id`, `limit_type`, `included`, `used`, `period_start`, `period_end` |
-| `balance.low` | a deduction 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. Needs the threshold set on the webhook; without one it never fires | `customer_id`, `balance`, `threshold`, `transaction_id` |
+| `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 rolls forward (the renewer; no `subscription.updated` is emitted for a renewal) | `customer_id`, `subscription_id`, `plan_id`, `current_period_start`, `current_period_end`, `credits_granted` |
+| `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.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` |
 
 For example, a `credit.granted` delivery:
 
@@ -605,7 +671,7 @@ with MeterFlow(api_key=os.environ["METERFLOW_API_KEY"]) as client:
 
     # Support asks: "what's Ana's situation?"
     balance = client.credits.balance("ana")
-    history = client.credits.transactions("ana")
+    history = client.credits.transactions("ana")["data"]
     usage = client.usage.summary("ana")
     entitlements = client.entitlements.get("ana")
 ```

{meterflow-0.1.2 → meterflow-0.2.0}/README.md

@@ -23,6 +23,7 @@ Track what your customers use, enforce credit balances, gate features, and manag
   - [Usage events](#usage-events)
   - [Subscriptions](#subscriptions)
   - [Plans](#plans)
+  - [Webhook receipts](#webhook-receipts)
   - [Entitlements — ask before you act](#entitlements--ask-before-you-act)
 - [Idempotency — safe retries for writes](#idempotency--safe-retries-for-writes)
 - [Automatic retries](#automatic-retries)
@@ -183,13 +184,26 @@ bal["total_granted"]   # "5250.000000"
 bal["total_consumed"]  # "1705.000000"
 ```
 
-**Transactions** — the full history, newest first:
+**Transactions** — the history, newest first, **a page at a time**:
 
 ```python
-for t in client.credits.transactions("customer_123"):
+page = client.credits.transactions("customer_123")          # 50 rows by default
+for t in page["data"]:
     print(t["transaction_type"], t["amount"], t["balance_after"], t["description"], t["created_at"])
+
+# The whole history, page by page. `next_cursor` is None once there is nothing after it.
+cursor = None
+while True:
+    page = client.credits.transactions("customer_123", limit=200, cursor=cursor)
+    handle(page["data"])
+    cursor = page["next_cursor"]
+    if cursor is None:
+        break
 ```
 
+> **The cursor is opaque.** Pass back exactly what `next_cursor` gave you; do not build one, and do
+> not read anything out of it. `limit` is 1–200 and defaults to 50.
+
 > **Amounts are decimal strings.** Balances and amounts come back as strings (`"3545.000000"`) to avoid floating-point drift on money-like values. Parse deliberately (`decimal.Decimal(...)`) when you need arithmetic. When *sending* an amount, a number or a numeric string are both accepted.
 
 ### Usage events
@@ -202,7 +216,7 @@ Record an event every time a customer does the thing you charge for. Events are
 client.usage.record({
     "event_name": "images.generated",
     "customer_external_id": "customer_123",
-    "value": 1,                                   # what the meter aggregates: 1 for counts, seconds/MB/etc. for sums
+    "value": 1,                                   # optional — what the meter aggregates: 1 for counts, seconds/MB/etc. for sums
     "properties": {},                             # free-form context; {} when unused
     "timestamp": "2026-09-30T10:00:00Z",          # optional — defaults to arrival time on the server
 })
@@ -260,7 +274,8 @@ This is usually the difference between fitting a plan and outgrowing it: 1,000 u
 
 Two things to keep in mind:
 
-- **It only helps a `sum` meter.** A `count` meter ignores `value` and counts occurrences, so there each occurrence has to be its own event. `max`, `min` and `unique_count` read `value` as a measurement, not a quantity to add.
+- **It only helps a `sum` meter.** A `count` meter ignores `value` and counts occurrences, so there each occurrence has to be its own event. `max` and `min` read `value` as a measurement, not a quantity to add, and `unique_count` does not read it at all — it counts distinct values of the property its meter names.
+- **`value` is optional.** Leave it out and MeterFlow fills it in: for a `sum`, `max` or `min` meter that names an `aggregation_field`, the numeric value of that property on the event; otherwise `1`. So the event above can be written with `"properties": {"tokens": 1300}` and no `"value"`, as long as the meter's `aggregation_field` is `tokens`. An explicit `value` always wins, a property that is absent or is not a number falls through to `1`, and a negative one is refused with a `422`.
 - **Billing is unchanged.** A metered plan limit charges per unit — the event's `value` — so 100 units cost the same whether they arrived as 100 events or one. You are not rounding anyone's bill by batching.
 
 **Summary** — a customer's usage, broken down by meter:
@@ -301,8 +316,12 @@ print(sub["status"])  # "trialing" if the plan has trial days, else "active"
 **List / get:**
 
 ```python
-everyone = client.subscriptions.list()                          # whole project (in your key's environment)
+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"])
+
+for subscription in page["data"]:
+    print(subscription["customer_external_id"], subscription["status"])
 one = client.subscriptions.get(sub["id"])
 ```
 
@@ -339,6 +358,27 @@ plan["features"]        # ["sso", "priority-support"] — the on/off keys check(
 
 Typical use: render your pricing page or signup flow from `plans.list()` so it can never drift from what billing actually enforces.
 
+### Webhook receipts
+
+Webhooks are **read-only** through the SDK too: endpoints are registered in the dashboard, where the signing secret is shown once and never again. What the SDK gives you is the other half — which endpoints exist, and what MeterFlow actually sent them.
+
+```python
+endpoints = client.webhooks.list()                  # this project's endpoints
+receipts = client.webhooks.deliveries(endpoint_id)  # newest first
+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
+```
+
+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.
+
+> 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.
+
 ### Entitlements — ask before you act
 
 The one call to make **before** doing work for a customer: "may they use this feature — and how much is left?" A **hard** limit says no here; recording usage afterwards never blocks, so an app that skips this call gets an honest ledger but no enforcement.
@@ -347,7 +387,7 @@ The one call to make **before** doing work for a customer: "may they use this fe
 gate = client.entitlements.check("customer_123", "images.generated")
 
 if not gate["allowed"]:
-    # gate["reason"]: "hard_limit_reached" | "no_subscription" | "not_in_plan" | "insufficient_credits"
+    # gate["reason"]: "hard_limit_reached" | "no_subscription" | "not_in_plan" | "insufficient_credits" | "spend_cap_reached"
     return show_upgrade_prompt(gate)  # gate["used"] / gate["included"] / gate["period_end"] are there for the copy
 
 generate_image()
@@ -372,6 +412,30 @@ result["entitlements"]
 
 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
+
+Mint a short-lived link to a MeterFlow-hosted page showing **one** customer's balance and ledger.
+Call it from your server; send the ``url`` to that customer.
+
+```python
+link = client.portal.create_session({
+    "customer_external_id": "customer_123",
+    "topup_url": "https://acme.test/billing",   # your checkout — "buy more" goes here
+    "return_url": "https://acme.test/app",      # where "done" goes
+    "expires_in_minutes": 60,                   # default 60, maximum 1440
+})
+
+send_email(customer.email, f"Your balance: {link['url']}")
+```
+
+The token in that link reads **that one customer's** balance and ledger, in the environment of the
+key you minted it with, and nothing else: it cannot write, cannot name another customer, and is
+refused everywhere else in the API. It is never your API key — never send that to anyone.
+
+> **MeterFlow never takes the payment.** `topup_url` is a link we carry and hand back to the page;
+> what happens there is between you and your own payment provider. Grant the credits with
+> `credits.grant()` when your checkout tells you it was paid.
+
 ## Idempotency — safe retries for writes
 
 Connections drop. When your app can't tell whether a write arrived, the correct move is to send it again **with the same idempotency key** — MeterFlow recognises the key and acts only once:
@@ -486,10 +550,12 @@ Every delivery is a flat JSON object (`Content-Type: application/json`) with two
 | `subscription.created` | a subscription is created | `customer_id`, `plan_id`, `subscription_id`, `status` |
 | `subscription.updated` | a subscription is updated | `customer_id`, `subscription_id`, `status` |
 | `limit.reached` | a customer first reaches a **hard** or **soft** limit's included units this billing period (once per meter per period; metered limits report through `credit.deducted` instead) | `customer_id`, `subscription_id`, `feature` (the meter's `event_name`), `meter_id`, `limit_type`, `included`, `used`, `period_start`, `period_end` |
-| `balance.low` | a deduction 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. Needs the threshold set on the webhook; without one it never fires | `customer_id`, `balance`, `threshold`, `transaction_id` |
+| `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 rolls forward (the renewer; no `subscription.updated` is emitted for a renewal) | `customer_id`, `subscription_id`, `plan_id`, `current_period_start`, `current_period_end`, `credits_granted` |
+| `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.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` |
 
 For example, a `credit.granted` delivery:
 
@@ -553,7 +619,7 @@ with MeterFlow(api_key=os.environ["METERFLOW_API_KEY"]) as client:
 
     # Support asks: "what's Ana's situation?"
     balance = client.credits.balance("ana")
-    history = client.credits.transactions("ana")
+    history = client.credits.transactions("ana")["data"]
     usage = client.usage.summary("ana")
     entitlements = client.entitlements.get("ana")
 ```

{meterflow-0.1.2 → meterflow-0.2.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.1.2"
+__version__ = "0.2.0"

{meterflow-0.1.2 → meterflow-0.2.0}/src/meterflow/client.py

@@ -19,8 +19,10 @@ from ._retry import RetryPolicy
 from .resources.credits import AsyncCreditsResource, CreditsResource
 from .resources.entitlements import AsyncEntitlementsResource, EntitlementsResource
 from .resources.plans import AsyncPlansResource, PlansResource
+from .resources.portal import AsyncPortalResource, PortalResource
 from .resources.subscriptions import AsyncSubscriptionsResource, SubscriptionsResource
 from .resources.usage import AsyncUsageResource, UsageResource
+from .resources.webhooks import AsyncWebhooksResource, WebhooksResource
 
 DEFAULT_BASE_URL = "https://api.meter-flow.com/api/v1"
 DEFAULT_TIMEOUT_SECONDS = 30.0
@@ -76,7 +78,9 @@ class MeterFlow(_BaseClient):
         self.usage = UsageResource(self)
         self.subscriptions = SubscriptionsResource(self)
         self.plans = PlansResource(self)
+        self.portal = PortalResource(self)
         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."""
@@ -121,7 +125,9 @@ class AsyncMeterFlow(_BaseClient):
         self.usage = AsyncUsageResource(self)
         self.subscriptions = AsyncSubscriptionsResource(self)
         self.plans = AsyncPlansResource(self)
+        self.portal = AsyncPortalResource(self)
         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."""

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

@@ -0,0 +1 @@
+"""The six SDK-facing resources, each in a sync and an async flavour sharing one set of request specs."""

{meterflow-0.1.2 → meterflow-0.2.0}/src/meterflow/resources/credits.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from .._http import RequestSpec, encode_path_segment
-from ..types import CreditBalanceResponse, CreditDeductRequest, CreditGrantRequest, CreditTransactionResponse
+from ..types import CreditBalanceResponse, CreditDeductRequest, CreditGrantRequest, CreditTransactionPage, CreditTransactionResponse
 
 if TYPE_CHECKING:
     from ..client import AsyncMeterFlow, MeterFlow
@@ -23,8 +23,8 @@ def balance_spec(customer_id: str) -> RequestSpec:
     return RequestSpec("GET", f"credits/{encode_path_segment(customer_id)}/balance")
 
 
-def transactions_spec(customer_id: str) -> RequestSpec:
-    return RequestSpec("GET", f"credits/{encode_path_segment(customer_id)}/transactions")
+def transactions_spec(customer_id: str, limit: int | None, cursor: str | None) -> RequestSpec:
+    return RequestSpec("GET", f"credits/{encode_path_segment(customer_id)}/transactions", query={"limit": limit, "cursor": cursor})
 
 
 class CreditsResource:
@@ -46,9 +46,14 @@ class CreditsResource:
         result: CreditBalanceResponse = self._client.request(balance_spec(customer_id))
         return result
 
-    def transactions(self, customer_id: str) -> list[CreditTransactionResponse]:
-        """The full history, newest first."""
-        result: list[CreditTransactionResponse] = self._client.request(transactions_spec(customer_id))
+    def transactions(self, customer_id: str, *, limit: int | None = None, cursor: str | None = None) -> CreditTransactionPage:
+        """One page of the ledger, newest first.
+
+        The ledger grows with every charge, so it is read a page at a time: ``data`` holds the rows
+        and ``next_cursor`` the mark for the page after this one (``None`` on the last). Pass it
+        back as ``cursor`` unchanged — it is opaque, and nothing but this API reads it.
+        """
+        result: CreditTransactionPage = self._client.request(transactions_spec(customer_id, limit, cursor))
         return result
 
 
@@ -71,7 +76,12 @@ class AsyncCreditsResource:
         result: CreditBalanceResponse = await self._client.request(balance_spec(customer_id))
         return result
 
-    async def transactions(self, customer_id: str) -> list[CreditTransactionResponse]:
-        """The full history, newest first."""
-        result: list[CreditTransactionResponse] = await self._client.request(transactions_spec(customer_id))
+    async def transactions(self, customer_id: str, *, limit: int | None = None, cursor: str | None = None) -> CreditTransactionPage:
+        """One page of the ledger, newest first.
+
+        The ledger grows with every charge, so it is read a page at a time: ``data`` holds the rows
+        and ``next_cursor`` the mark for the page after this one (``None`` on the last). Pass it
+        back as ``cursor`` unchanged — it is opaque, and nothing but this API reads it.
+        """
+        result: CreditTransactionPage = await self._client.request(transactions_spec(customer_id, limit, cursor))
         return result

meterflow-0.2.0/src/meterflow/resources/portal.py

@@ -0,0 +1,52 @@
+"""The hosted balance portal: mint a link for one of your customers.
+
+Only the mint is here. The two reads behind the page — the balance and the ledger — are made by
+the person holding the link, with the link's own token; this client holds a secret key, and the
+two must never be the same credential.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .._http import RequestSpec
+from ..types import PortalLinkRequest, PortalLinkResponse
+
+if TYPE_CHECKING:
+    from ..client import AsyncMeterFlow, MeterFlow
+
+_DOC = """Mint a link to the hosted balance page for one of your customers.
+
+        Call this from **your** server and send the ``url`` to that customer. It carries a
+        short-lived token that reads their balance and their ledger and nothing else, in the
+        environment of the key you called with; it is never your API key and it can write nothing.
+
+        The page shows the balance and sends "buy more" to your own checkout (``topup_url``):
+        MeterFlow never takes the payment. ``expires_in_minutes`` defaults to 60, maximum 1440.
+        """
+
+
+def create_session_spec(body: PortalLinkRequest) -> RequestSpec:
+    return RequestSpec("POST", "portal/sessions", body=body)
+
+
+class PortalResource:
+    def __init__(self, client: MeterFlow) -> None:
+        self._client = client
+
+    def create_session(self, body: PortalLinkRequest) -> PortalLinkResponse:
+        result: PortalLinkResponse = self._client.request(create_session_spec(body))
+        return result
+
+    create_session.__doc__ = _DOC
+
+
+class AsyncPortalResource:
+    def __init__(self, client: AsyncMeterFlow) -> None:
+        self._client = client
+
+    async def create_session(self, body: PortalLinkRequest) -> PortalLinkResponse:
+        result: PortalLinkResponse = await self._client.request(create_session_spec(body))
+        return result
+
+    create_session.__doc__ = _DOC

{meterflow-0.1.2 → meterflow-0.2.0}/src/meterflow/resources/subscriptions.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from .._http import RequestSpec, encode_path_segment
-from ..types import SubscriptionCreateRequest, SubscriptionResponse, SubscriptionUpdateRequest
+from ..types import SubscriptionCreateRequest, SubscriptionPage, SubscriptionResponse, SubscriptionUpdateRequest
 
 if TYPE_CHECKING:
     from ..client import AsyncMeterFlow, MeterFlow
@@ -15,8 +15,8 @@ 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) -> RequestSpec:
-    return RequestSpec("GET", "subscriptions", query={"customer_id": customer_id})
+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 get_spec(subscription_id: str) -> RequestSpec:
@@ -40,9 +40,14 @@ class SubscriptionsResource:
         result: SubscriptionResponse = self._client.request(create_spec(body, idempotency_key))
         return result
 
-    def list(self, *, customer_id: str | None = None) -> list[SubscriptionResponse]:
-        """The project's subscriptions in this key's environment, optionally one customer's."""
-        result: list[SubscriptionResponse] = self._client.request(list_spec(customer_id))
+    def list(self, *, customer_id: str | 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.
+        """
+        result: SubscriptionPage = self._client.request(list_spec(customer_id, limit, cursor))
         return result
 
     def get(self, subscription_id: str) -> SubscriptionResponse:
@@ -68,9 +73,14 @@ class AsyncSubscriptionsResource:
         result: SubscriptionResponse = await self._client.request(create_spec(body, idempotency_key))
         return result
 
-    async def list(self, *, customer_id: str | None = None) -> list[SubscriptionResponse]:
-        """The project's subscriptions in this key's environment, optionally one customer's."""
-        result: list[SubscriptionResponse] = await self._client.request(list_spec(customer_id))
+    async def list(self, *, customer_id: str | 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.
+        """
+        result: SubscriptionPage = await self._client.request(list_spec(customer_id, limit, cursor))
         return result
 
     async def get(self, subscription_id: str) -> SubscriptionResponse:

meterflow-0.2.0/src/meterflow/resources/webhooks.py

@@ -0,0 +1,75 @@
+"""Webhook receipts — read-only through the SDK: endpoints are registered in the dashboard.
+
+An endpoint is created, edited and deleted where the signing secret can be shown once and never
+again. What an SDK consumer needs at 3am is the other half: which endpoints exist, and what
+MeterFlow actually sent them. That is this module.
+
+Not to be confused with :mod:`meterflow.webhook`, which verifies the signature on a webhook your
+server has just received. This reads what we sent; that proves we sent it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .._http import RequestSpec, encode_path_segment
+from ..types import WebhookDeliveryResponse, WebhookResponse
+
+if TYPE_CHECKING:
+    from ..client import AsyncMeterFlow, MeterFlow
+
+# Spelled as module-level aliases, where `list` is still the builtin. Inside the class bodies below
+# it is not: a method called `list` shadows it for every annotation that follows, so writing
+# `list[WebhookDeliveryResponse]` on `deliveries` resolves to the method and mypy rejects it.
+# `plans.py` never meets this only because its second method returns a bare type.
+WebhookList = list[WebhookResponse]
+DeliveryList = list[WebhookDeliveryResponse]
+
+
+def list_spec() -> RequestSpec:
+    # No project_id: the key's own project is the scope, and a query could not widen it.
+    return RequestSpec("GET", "webhooks")
+
+
+def deliveries_spec(webhook_id: str) -> RequestSpec:
+    return RequestSpec("GET", f"webhooks/{encode_path_segment(webhook_id)}/deliveries")
+
+
+class WebhooksResource:
+    def __init__(self, client: MeterFlow) -> None:
+        self._client = client
+
+    def list(self) -> WebhookList:
+        """The endpoints registered for this key's project. Never includes a secret."""
+        result: WebhookList = self._client.request(list_spec())
+        return result
+
+    def deliveries(self, webhook_id: str) -> DeliveryList:
+        """One endpoint's delivery attempts, newest first: what was sent, the HTTP status that came
+        back, how many attempts and when the next retry is due.
+
+        Capped at the most recent 100, and scoped to the key's own environment — a ``mf_test_*``
+        key reads test receipts, a ``mf_live_*`` key live ones. Another project's webhook is a 404.
+        """
+        result: DeliveryList = self._client.request(deliveries_spec(webhook_id))
+        return result
+
+
+class AsyncWebhooksResource:
+    def __init__(self, client: AsyncMeterFlow) -> None:
+        self._client = client
+
+    async def list(self) -> WebhookList:
+        """The endpoints registered for this key's project. Never includes a secret."""
+        result: WebhookList = await self._client.request(list_spec())
+        return result
+
+    async def deliveries(self, webhook_id: str) -> DeliveryList:
+        """One endpoint's delivery attempts, newest first: what was sent, the HTTP status that came
+        back, how many attempts and when the next retry is due.
+
+        Capped at the most recent 100, and scoped to the key's own environment — a ``mf_test_*``
+        key reads test receipts, a ``mf_live_*`` key live ones. Another project's webhook is a 404.
+        """
+        result: DeliveryList = await self._client.request(deliveries_spec(webhook_id))
+        return result

{meterflow-0.1.2 → meterflow-0.2.0}/src/meterflow/types.py

@@ -6,7 +6,14 @@ from __future__ import annotations
 
 from typing import Any, Literal, TypedDict
 
-EntitlementReason = Literal["no_subscription", "not_in_plan", "hard_limit_reached", "soft_limit_exceeded", "insufficient_credits"]
+EntitlementReason = Literal[
+    "no_subscription",
+    "not_in_plan",
+    "hard_limit_reached",
+    "soft_limit_exceeded",
+    "insufficient_credits",
+    "spend_cap_reached",
+]
 
 FeatureType = Literal["boolean", "metered"]
 
@@ -48,6 +55,19 @@ class CreditGrantRequest(_CreditGrantRequestRequired, total=False):
     metadata: dict[str, Any]
 
 
+class _CreditTransactionPageRequired(TypedDict):
+    data: list[CreditTransactionResponse]
+
+
+class CreditTransactionPage(_CreditTransactionPageRequired, total=False):
+    """One page of a customer's credit ledger, newest first. `next_cursor` is the opaque mark for the page after this one, and `null` on the
+    last page — pass it back as `cursor` unchanged. The list grows with a customer's traffic, which is why it is paged at all
+    (docs/DECISIONS.md, 2026-10-14).
+    """
+
+    next_cursor: str | None
+
+
 class CreditTransactionResponse(TypedDict):
     id: str
     project_id: str
@@ -108,7 +128,6 @@ class PlanResponse(TypedDict):
     currency: str
     trial_days: int
     is_active: bool
-    is_public: bool
     is_published: bool
     metadata_: dict[str, Any]
     meter_limits: list[PlanMeterLimitResponse]
@@ -117,16 +136,61 @@ class PlanResponse(TypedDict):
     updated_at: str
 
 
+class _PortalLinkRequestRequired(TypedDict):
+    customer_external_id: str
+
+
+class PortalLinkRequest(_PortalLinkRequestRequired, total=False):
+    """One link, for one of the caller's customers. The environment is **not** here: it comes from the API key's prefix, like every other
+    SDK-facing write.
+    """
+
+    return_url: str | None
+    topup_url: str | None
+    expires_in_minutes: int | None
+
+
+class _PortalLinkResponseRequired(TypedDict):
+    url: str
+    token: str
+    expires_at: str
+    customer_external_id: str
+    environment: str
+
+
+class PortalLinkResponse(_PortalLinkResponseRequired, total=False):
+    """The link to send, and what it is for. The signing material is never part of this."""
+
+    return_url: str | None
+    topup_url: str | None
+
+
 class _SubscriptionCreateRequestRequired(TypedDict):
     plan_id: str
     customer_external_id: str
 
 
 class SubscriptionCreateRequest(_SubscriptionCreateRequestRequired, total=False):
+    spend_cap: float | str | None
+    topup_amount: float | str | None
+    max_topups_per_window: int | None
     metadata: dict[str, Any]
     idempotency_key: str | None
 
 
+class _SubscriptionPageRequired(TypedDict):
+    data: list[SubscriptionResponse]
+
+
+class SubscriptionPage(_SubscriptionPageRequired, total=False):
+    """One page of a project's subscriptions, newest first. `next_cursor` is the opaque mark for the page after this one, and `null` on the
+    last page — pass it back as `cursor` unchanged. The list grows with a customer's traffic, which is why it is paged at all
+    (docs/DECISIONS.md, 2026-10-14).
+    """
+
+    next_cursor: str | None
+
+
 class SubscriptionResponse(TypedDict):
     id: str
     project_id: str
@@ -137,6 +201,10 @@ class SubscriptionResponse(TypedDict):
     current_period_start: str
     current_period_end: str | None
     trial_end_date: str | None
+    spend_cap: str | None
+    topup_amount: str | None
+    max_topups_per_window: int | None
+    idempotency_key: str | None
     canceled_at: str | None
     metadata_: dict[str, Any]
     created_at: str
@@ -145,6 +213,9 @@ class SubscriptionResponse(TypedDict):
 
 class SubscriptionUpdateRequest(TypedDict, total=False):
     status: SubscriptionStatus | None
+    spend_cap: float | str | None
+    topup_amount: float | str | None
+    max_topups_per_window: int | None
     metadata: dict[str, Any] | None
 
 
@@ -158,7 +229,7 @@ class _UsageEventRequestRequired(TypedDict):
 
 
 class UsageEventRequest(_UsageEventRequestRequired, total=False):
-    value: float | str
+    value: float | str | None
     properties: dict[str, Any]
     idempotency_key: str | None
     timestamp: str | None
@@ -206,10 +277,41 @@ class UsageSummaryResponse(TypedDict):
     meters: list[UsageSummaryItem]
 
 
+class WebhookDeliveryResponse(TypedDict):
+    id: str
+    webhook_id: str
+    event_type: str
+    payload: dict[str, Any]
+    status: str
+    response_code: int | None
+    response_body: str | None
+    attempts: int
+    next_retry_at: str | None
+    created_at: str
+    completed_at: str | None
+
+
+class WebhookResponse(TypedDict):
+    """Returned on all reads — secret is never included."""
+
+    id: str
+    project_id: str
+    url: str
+    events: list[str]
+    low_balance_threshold: str | None
+    is_active: bool
+    last_triggered_at: str | None
+    failure_count: int
+    metadata_: dict[str, Any]
+    created_at: str
+    updated_at: str
+
+
 __all__ = [
     "CreditBalanceResponse",
     "CreditDeductRequest",
     "CreditGrantRequest",
+    "CreditTransactionPage",
     "CreditTransactionResponse",
     "EntitlementReason",
     "EntitlementResponse",
@@ -217,7 +319,10 @@ __all__ = [
     "FeatureType",
     "PlanMeterLimitResponse",
     "PlanResponse",
+    "PortalLinkRequest",
+    "PortalLinkResponse",
     "SubscriptionCreateRequest",
+    "SubscriptionPage",
     "SubscriptionResponse",
     "SubscriptionStatus",
     "SubscriptionUpdateRequest",
@@ -226,4 +331,6 @@ __all__ = [
     "UsageEventResponse",
     "UsageSummaryItem",
     "UsageSummaryResponse",
+    "WebhookDeliveryResponse",
+    "WebhookResponse",
 ]

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

@@ -1 +0,0 @@
-"""The five SDK-facing resources, each in a sync and an async flavour sharing one set of request specs."""