meterflow 0.6.1__tar.gz → 0.7.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (22) hide show
  1. {meterflow-0.6.1 → meterflow-0.7.0}/PKG-INFO +11 -5
  2. {meterflow-0.6.1 → meterflow-0.7.0}/README.md +10 -4
  3. {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/__init__.py +6 -0
  4. {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/_http.py +5 -1
  5. {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/_version.py +1 -1
  6. {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/resources/credits.py +42 -12
  7. {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/resources/subscriptions.py +32 -12
  8. {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/resources/usage.py +14 -8
  9. {meterflow-0.6.1 → meterflow-0.7.0}/LICENSE +0 -0
  10. {meterflow-0.6.1 → meterflow-0.7.0}/pyproject.toml +0 -0
  11. {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/_entitlement_cache.py +0 -0
  12. {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/_retry.py +0 -0
  13. {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/client.py +0 -0
  14. {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/errors.py +0 -0
  15. {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/py.typed +0 -0
  16. {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/resources/__init__.py +0 -0
  17. {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/resources/entitlements.py +0 -0
  18. {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/resources/plans.py +0 -0
  19. {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/resources/portal.py +0 -0
  20. {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/resources/webhooks.py +0 -0
  21. {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/types.py +0 -0
  22. {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/webhook.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: meterflow
3
- Version: 0.6.1
3
+ Version: 0.7.0
4
4
  Summary: Official Python SDK for MeterFlow — usage-based billing, credit management, and metering.
5
5
  Project-URL: Homepage, https://meter-flow.com
6
6
  Project-URL: Documentation, https://meter-flow.com/guide
@@ -264,10 +264,14 @@ while True:
264
264
  cursor = page["next_cursor"]
265
265
  if cursor is None:
266
266
  break
267
+
268
+ # Another order: `sort` is "created_at" (the default) or "amount", `order` "desc" (the default) or "asc".
269
+ largest_first = client.credits.transactions("customer_123", sort="amount", order="desc")
267
270
  ```
268
271
 
269
- > **The cursor is opaque.** Pass back exactly what `next_cursor` gave you; do not build one, and do
270
- > not read anything out of it. `limit` is 1–200 and defaults to 50.
272
+ > **The cursor is opaque.** Pass back exactly what `next_cursor` gave you, with the same `sort` and `order`
273
+ > (another order with it is a `ValidationError`); do not build one, and do not read anything out of it.
274
+ > `limit` is 1–200 and defaults to 50.
271
275
 
272
276
  > **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.
273
277
 
@@ -303,12 +307,13 @@ Record an event every time a customer does the thing you charge for. Events are
303
307
  **Record one event:**
304
308
 
305
309
  ```python
310
+
306
311
  client.usage.record({
307
312
  "event_name": "images.generated",
308
313
  "customer_external_id": "customer_123",
309
314
  "value": 1, # optional — what the meter aggregates: 1 for counts, seconds/MB/etc. for sums
310
315
  "properties": {}, # free-form context; {} when unused
311
- "timestamp": "2026-09-30T10:00:00Z", # optional — defaults to arrival time on the server
316
+ # "timestamp": leave it out — the API stamps arrival time; one more than 300 s old or 60 s ahead is refused (422)
312
317
  })
313
318
  ```
314
319
 
@@ -410,6 +415,7 @@ page = client.subscriptions.list() # whole project
410
415
  theirs = client.subscriptions.list(customer_id="customer_123") # one customer
411
416
  more = client.subscriptions.list(limit=200, cursor=page["next_cursor"])
412
417
  behind = client.subscriptions.list(q="acme", status=["past_due", "paused"]) # ids containing "acme", in either status
418
+ by_status = client.subscriptions.list(sort="status", order="asc") # or "created_at" (default), "customer_external_id"
413
419
 
414
420
  for subscription in page["data"]:
415
421
  print(subscription["customer_external_id"], subscription["status"])
@@ -670,7 +676,7 @@ Every delivery is a flat JSON object (`Content-Type: application/json`) with two
670
676
  |---|---|---|
671
677
  | `usage.recorded` | a usage event is ingested (single or batch) | `customer_id`, `event_name`, `value`, `event_id` |
672
678
  | `credit.granted` | credits are granted | `customer_id`, `amount`, `balance_after`, `transaction_id` |
673
- | `credit.deducted` | credits are deducted | `customer_id`, `amount`, `balance_after`, `transaction_id` |
679
+ | `credit.deducted` | credits are deducted: by a deduct call, or by a metered usage charge | `customer_id`, `amount`, `balance_after`, `transaction_id`, `transaction_type` (`deduct` or `usage`), `usage_event_id` (the billed event for `usage`, else null) |
674
680
  | `subscription.created` | a subscription is created | `customer_id`, `plan_id`, `subscription_id`, `status` |
675
681
  | `subscription.updated` | a subscription is updated | `customer_id`, `subscription_id`, `status` |
676
682
  | `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` |
@@ -212,10 +212,14 @@ while True:
212
212
  cursor = page["next_cursor"]
213
213
  if cursor is None:
214
214
  break
215
+
216
+ # Another order: `sort` is "created_at" (the default) or "amount", `order` "desc" (the default) or "asc".
217
+ largest_first = client.credits.transactions("customer_123", sort="amount", order="desc")
215
218
  ```
216
219
 
217
- > **The cursor is opaque.** Pass back exactly what `next_cursor` gave you; do not build one, and do
218
- > not read anything out of it. `limit` is 1–200 and defaults to 50.
220
+ > **The cursor is opaque.** Pass back exactly what `next_cursor` gave you, with the same `sort` and `order`
221
+ > (another order with it is a `ValidationError`); do not build one, and do not read anything out of it.
222
+ > `limit` is 1–200 and defaults to 50.
219
223
 
220
224
  > **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.
221
225
 
@@ -251,12 +255,13 @@ Record an event every time a customer does the thing you charge for. Events are
251
255
  **Record one event:**
252
256
 
253
257
  ```python
258
+
254
259
  client.usage.record({
255
260
  "event_name": "images.generated",
256
261
  "customer_external_id": "customer_123",
257
262
  "value": 1, # optional — what the meter aggregates: 1 for counts, seconds/MB/etc. for sums
258
263
  "properties": {}, # free-form context; {} when unused
259
- "timestamp": "2026-09-30T10:00:00Z", # optional — defaults to arrival time on the server
264
+ # "timestamp": leave it out — the API stamps arrival time; one more than 300 s old or 60 s ahead is refused (422)
260
265
  })
261
266
  ```
262
267
 
@@ -358,6 +363,7 @@ page = client.subscriptions.list() # whole project
358
363
  theirs = client.subscriptions.list(customer_id="customer_123") # one customer
359
364
  more = client.subscriptions.list(limit=200, cursor=page["next_cursor"])
360
365
  behind = client.subscriptions.list(q="acme", status=["past_due", "paused"]) # ids containing "acme", in either status
366
+ by_status = client.subscriptions.list(sort="status", order="asc") # or "created_at" (default), "customer_external_id"
361
367
 
362
368
  for subscription in page["data"]:
363
369
  print(subscription["customer_external_id"], subscription["status"])
@@ -618,7 +624,7 @@ Every delivery is a flat JSON object (`Content-Type: application/json`) with two
618
624
  |---|---|---|
619
625
  | `usage.recorded` | a usage event is ingested (single or batch) | `customer_id`, `event_name`, `value`, `event_id` |
620
626
  | `credit.granted` | credits are granted | `customer_id`, `amount`, `balance_after`, `transaction_id` |
621
- | `credit.deducted` | credits are deducted | `customer_id`, `amount`, `balance_after`, `transaction_id` |
627
+ | `credit.deducted` | credits are deducted: by a deduct call, or by a metered usage charge | `customer_id`, `amount`, `balance_after`, `transaction_id`, `transaction_type` (`deduct` or `usage`), `usage_event_id` (the billed event for `usage`, else null) |
622
628
  | `subscription.created` | a subscription is created | `customer_id`, `plan_id`, `subscription_id`, `status` |
623
629
  | `subscription.updated` | a subscription is updated | `customer_id`, `subscription_id`, `status` |
624
630
  | `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` |
@@ -7,6 +7,7 @@ client.credits.grant({"customer_external_id": "customer_123", "amount": 5000, "m
7
7
  """
8
8
 
9
9
  from ._entitlement_cache import EntitlementDefault, EntitlementFallbackContext
10
+ from ._http import SortOrder
10
11
  from ._version import __version__
11
12
  from .client import AsyncMeterFlow, ClientOptions, MeterFlow
12
13
  from .errors import (
@@ -21,7 +22,9 @@ from .errors import (
21
22
  ValidationError,
22
23
  ValidationFieldError,
23
24
  )
25
+ from .resources.credits import TransactionSort
24
26
  from .resources.entitlements import EntitlementCheck, EntitlementList
27
+ from .resources.subscriptions import SubscriptionSort
25
28
  from .resources.usage import MAX_BATCH_EVENTS
26
29
  from .webhook import verify_webhook
27
30
 
@@ -45,5 +48,8 @@ __all__ = [
45
48
  "EntitlementList",
46
49
  "EntitlementDefault",
47
50
  "EntitlementFallbackContext",
51
+ "SortOrder",
52
+ "SubscriptionSort",
53
+ "TransactionSort",
48
54
  "verify_webhook",
49
55
  ]
@@ -10,7 +10,7 @@ import json
10
10
  import time
11
11
  from collections.abc import Sequence
12
12
  from dataclasses import dataclass, field
13
- from typing import Any
13
+ from typing import Any, Literal
14
14
  from urllib.parse import quote
15
15
 
16
16
  import httpx
@@ -41,6 +41,10 @@ async def _async_sleep(seconds: float) -> None:
41
41
  await asyncio.sleep(seconds)
42
42
 
43
43
 
44
+ # Which way a list is ordered: ``desc`` (each list's default) or ``asc``.
45
+ SortOrder = Literal["asc", "desc"]
46
+
47
+
44
48
  @dataclass(frozen=True)
45
49
  class RequestSpec:
46
50
  """One API call, described by a resource method and made by a client.
@@ -1,2 +1,2 @@
1
1
  # The package's version: pyproject.toml reads it, and the User-Agent sends it. A release edits only this line.
2
- __version__ = "0.6.1"
2
+ __version__ = "0.7.0"
@@ -2,10 +2,10 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- from typing import TYPE_CHECKING
5
+ from typing import TYPE_CHECKING, Literal
6
6
 
7
7
  from .._entitlement_cache import expire_entitlements
8
- from .._http import RequestSpec, encode_path_segment
8
+ from .._http import RequestSpec, SortOrder, encode_path_segment
9
9
  from ..types import (
10
10
  CreditBalanceResponse,
11
11
  CreditDeductRequest,
@@ -49,8 +49,18 @@ def balance_spec(customer_id: str) -> RequestSpec:
49
49
  return RequestSpec("GET", f"credits/{encode_path_segment(customer_id)}/balance")
50
50
 
51
51
 
52
- def transactions_spec(customer_id: str, limit: int | None, cursor: str | None) -> RequestSpec:
53
- return RequestSpec("GET", f"credits/{encode_path_segment(customer_id)}/transactions", query={"limit": limit, "cursor": cursor})
52
+ # The columns ``credits.transactions()`` can order by.
53
+ TransactionSort = Literal["created_at", "amount"]
54
+
55
+
56
+ def transactions_spec(
57
+ customer_id: str, limit: int | None, cursor: str | None, sort: TransactionSort | None, order: SortOrder | None
58
+ ) -> RequestSpec:
59
+ return RequestSpec(
60
+ "GET",
61
+ f"credits/{encode_path_segment(customer_id)}/transactions",
62
+ query={"limit": limit, "cursor": cursor, "sort": sort, "order": order},
63
+ )
54
64
 
55
65
 
56
66
  class CreditsResource:
@@ -137,17 +147,27 @@ class CreditsResource:
137
147
  result: CreditBalanceResponse = self._client.request(balance_spec(customer_id))
138
148
  return result
139
149
 
140
- def transactions(self, customer_id: str, *, limit: int | None = None, cursor: str | None = None) -> CreditTransactionPage:
141
- """One page of the customer's ledger, newest first.
150
+ def transactions(
151
+ self,
152
+ customer_id: str,
153
+ *,
154
+ limit: int | None = None,
155
+ cursor: str | None = None,
156
+ sort: TransactionSort | None = None,
157
+ order: SortOrder | None = None,
158
+ ) -> CreditTransactionPage:
159
+ """One page of the customer's ledger, newest first unless ``sort`` / ``order`` say otherwise.
142
160
 
143
161
  ``data`` holds the rows and ``next_cursor`` the mark for the next page (``None`` on the last). Pass it back as
144
- ``cursor`` unchanged; it is opaque.
162
+ ``cursor`` unchanged, with the same order; it is opaque.
145
163
 
146
164
  customer_id: your id for the customer.
147
165
  limit: rows per page, 1–200; None for the API's default (50).
148
166
  cursor: ``next_cursor`` of the page before; None for the first page.
167
+ sort: the column to order by; None for ``created_at``. Ties are broken by the row id.
168
+ order: ``desc`` or ``asc``; None for ``desc``.
149
169
  """
150
- result: CreditTransactionPage = self._client.request(transactions_spec(customer_id, limit, cursor))
170
+ result: CreditTransactionPage = self._client.request(transactions_spec(customer_id, limit, cursor, sort, order))
151
171
  return result
152
172
 
153
173
 
@@ -237,15 +257,25 @@ class AsyncCreditsResource:
237
257
  result: CreditBalanceResponse = await self._client.request(balance_spec(customer_id))
238
258
  return result
239
259
 
240
- async def transactions(self, customer_id: str, *, limit: int | None = None, cursor: str | None = None) -> CreditTransactionPage:
241
- """One page of the customer's ledger, newest first.
260
+ async def transactions(
261
+ self,
262
+ customer_id: str,
263
+ *,
264
+ limit: int | None = None,
265
+ cursor: str | None = None,
266
+ sort: TransactionSort | None = None,
267
+ order: SortOrder | None = None,
268
+ ) -> CreditTransactionPage:
269
+ """One page of the customer's ledger, newest first unless ``sort`` / ``order`` say otherwise.
242
270
 
243
271
  ``data`` holds the rows and ``next_cursor`` the mark for the next page (``None`` on the last). Pass it back as
244
- ``cursor`` unchanged; it is opaque.
272
+ ``cursor`` unchanged, with the same order; it is opaque.
245
273
 
246
274
  customer_id: your id for the customer.
247
275
  limit: rows per page, 1–200; None for the API's default (50).
248
276
  cursor: ``next_cursor`` of the page before; None for the first page.
277
+ sort: the column to order by; None for ``created_at``. Ties are broken by the row id.
278
+ order: ``desc`` or ``asc``; None for ``desc``.
249
279
  """
250
- result: CreditTransactionPage = await self._client.request(transactions_spec(customer_id, limit, cursor))
280
+ result: CreditTransactionPage = await self._client.request(transactions_spec(customer_id, limit, cursor, sort, order))
251
281
  return result
@@ -3,9 +3,9 @@
3
3
  from __future__ import annotations
4
4
 
5
5
  from collections.abc import Sequence
6
- from typing import TYPE_CHECKING
6
+ from typing import TYPE_CHECKING, Literal
7
7
 
8
- from .._http import RequestSpec, encode_path_segment
8
+ from .._http import RequestSpec, SortOrder, encode_path_segment
9
9
  from ..types import SubscriptionCreateRequest, SubscriptionPage, SubscriptionResponse, SubscriptionStatus, SubscriptionUpdateRequest
10
10
 
11
11
  if TYPE_CHECKING:
@@ -16,11 +16,23 @@ def create_spec(body: SubscriptionCreateRequest, idempotency_key: str | None) ->
16
16
  return RequestSpec("POST", "subscriptions", body=body, idempotency_key=idempotency_key)
17
17
 
18
18
 
19
+ # The columns ``subscriptions.list()`` can order by.
20
+ SubscriptionSort = Literal["created_at", "customer_external_id", "status"]
21
+
22
+
19
23
  def list_spec(
20
- customer_id: str | None, q: str | None, status: Sequence[SubscriptionStatus] | None, limit: int | None, cursor: str | None
24
+ customer_id: str | None,
25
+ q: str | None,
26
+ status: Sequence[SubscriptionStatus] | None,
27
+ limit: int | None,
28
+ cursor: str | None,
29
+ sort: SubscriptionSort | None,
30
+ order: SortOrder | None,
21
31
  ) -> RequestSpec:
22
32
  return RequestSpec(
23
- "GET", "subscriptions", query={"customer_id": customer_id, "q": q, "status": status, "limit": limit, "cursor": cursor}
33
+ "GET",
34
+ "subscriptions",
35
+ query={"customer_id": customer_id, "q": q, "status": status, "limit": limit, "cursor": cursor, "sort": sort, "order": order},
24
36
  )
25
37
 
26
38
 
@@ -57,20 +69,24 @@ class SubscriptionsResource:
57
69
  status: Sequence[SubscriptionStatus] | None = None,
58
70
  limit: int | None = None,
59
71
  cursor: str | None = None,
72
+ sort: SubscriptionSort | None = None,
73
+ order: SortOrder | None = None,
60
74
  ) -> SubscriptionPage:
61
- """One page of the project's subscriptions in this key's environment, newest first.
75
+ """One page of the project's subscriptions in this key's environment, newest first unless ``sort`` / ``order`` say otherwise.
62
76
 
63
77
  ``data`` holds the rows and ``next_cursor`` the mark for the next page (``None`` on the last). Pass it back as
64
- ``cursor`` unchanged, with the same filters: they apply before the page is cut. In ``q``, ``%`` and ``_`` are
65
- matched literally.
78
+ ``cursor`` unchanged, with the same filters and order: they apply before the page is cut. In ``q``, ``%`` and ``_``
79
+ are matched literally.
66
80
 
67
81
  customer_id: only this customer's subscriptions, matched exactly.
68
82
  q: only customers whose id contains this, ignoring case.
69
83
  status: only subscriptions in one of these statuses.
70
84
  limit: rows per page, 1–200; None for the API's default (50).
71
85
  cursor: ``next_cursor`` of the page before; None for the first page.
86
+ sort: the column to order by; None for ``created_at``. Ties are broken by the row id.
87
+ order: ``desc`` or ``asc``; None for ``desc``.
72
88
  """
73
- result: SubscriptionPage = self._client.request(list_spec(customer_id, q, status, limit, cursor))
89
+ result: SubscriptionPage = self._client.request(list_spec(customer_id, q, status, limit, cursor, sort, order))
74
90
  return result
75
91
 
76
92
  def get(self, subscription_id: str) -> SubscriptionResponse:
@@ -123,20 +139,24 @@ class AsyncSubscriptionsResource:
123
139
  status: Sequence[SubscriptionStatus] | None = None,
124
140
  limit: int | None = None,
125
141
  cursor: str | None = None,
142
+ sort: SubscriptionSort | None = None,
143
+ order: SortOrder | None = None,
126
144
  ) -> SubscriptionPage:
127
- """One page of the project's subscriptions in this key's environment, newest first.
145
+ """One page of the project's subscriptions in this key's environment, newest first unless ``sort`` / ``order`` say otherwise.
128
146
 
129
147
  ``data`` holds the rows and ``next_cursor`` the mark for the next page (``None`` on the last). Pass it back as
130
- ``cursor`` unchanged, with the same filters: they apply before the page is cut. In ``q``, ``%`` and ``_`` are
131
- matched literally.
148
+ ``cursor`` unchanged, with the same filters and order: they apply before the page is cut. In ``q``, ``%`` and ``_``
149
+ are matched literally.
132
150
 
133
151
  customer_id: only this customer's subscriptions, matched exactly.
134
152
  q: only customers whose id contains this, ignoring case.
135
153
  status: only subscriptions in one of these statuses.
136
154
  limit: rows per page, 1–200; None for the API's default (50).
137
155
  cursor: ``next_cursor`` of the page before; None for the first page.
156
+ sort: the column to order by; None for ``created_at``. Ties are broken by the row id.
157
+ order: ``desc`` or ``asc``; None for ``desc``.
138
158
  """
139
- result: SubscriptionPage = await self._client.request(list_spec(customer_id, q, status, limit, cursor))
159
+ result: SubscriptionPage = await self._client.request(list_spec(customer_id, q, status, limit, cursor, sort, order))
140
160
  return result
141
161
 
142
162
  async def get(self, subscription_id: str) -> SubscriptionResponse:
@@ -42,7 +42,8 @@ class UsageResource:
42
42
  def record(self, body: UsageEventRequest, *, idempotency_key: str | None = None) -> UsageEventResponse:
43
43
  """Record one usage event. It returns at once with ``processed: False``; billing follows moments later (see ``event()``).
44
44
 
45
- The customer's cached entitlement answers go stale.
45
+ A ``timestamp`` more than 300 s in the past or 60 s in the future is refused (422); omit it to stamp now. The
46
+ customer's cached entitlement answers go stale.
46
47
 
47
48
  body: the customer, the event name, and its value or properties.
48
49
  idempotency_key: sent as the ``Idempotency-Key`` header: a retried write with the same key is answered once, for 24 hours.
@@ -54,7 +55,8 @@ class UsageResource:
54
55
  def record_batch(self, events: list[UsageEventRequest], *, idempotency_key: str | None = None) -> list[UsageEventResponse]:
55
56
  """Record up to ``MAX_BATCH_EVENTS`` events in one request; a larger list raises ``PayloadTooLargeError`` and is never sent.
56
57
 
57
- Each customer's cached entitlement answers go stale.
58
+ One event stamped outside the window ``record()`` allows refuses the whole batch (422, naming it); nothing is
59
+ recorded. Each customer's cached entitlement answers go stale.
58
60
 
59
61
  events: the events, each as ``record()`` takes it.
60
62
  idempotency_key: one key for the whole batch.
@@ -67,8 +69,9 @@ class UsageResource:
67
69
  """Read one recorded event back, with ``billing_outcome``.
68
70
 
69
71
  ``charged``, or why nothing was charged (``no_subscription``, ``no_meter_limit``, ``not_metered``,
70
- ``within_allowance``, ``not_deducted``, ``spend_cap_reached``, ``aggregation_not_billable``). It is None while
71
- ``processed`` is False: billing runs after ``record()`` returns, so poll this to learn what happened.
72
+ ``within_allowance``, ``not_deducted``, ``spend_cap_reached``, ``aggregation_not_billable``,
73
+ ``processing_failed``). It is None while ``processed`` is False: billing runs after ``record()`` returns, so poll
74
+ this to learn what happened.
72
75
 
73
76
  event_id: the event's ``id``, from ``record()``.
74
77
  """
@@ -96,7 +99,8 @@ class AsyncUsageResource:
96
99
  async def record(self, body: UsageEventRequest, *, idempotency_key: str | None = None) -> UsageEventResponse:
97
100
  """Record one usage event. It returns at once with ``processed: False``; billing follows moments later (see ``event()``).
98
101
 
99
- The customer's cached entitlement answers go stale.
102
+ A ``timestamp`` more than 300 s in the past or 60 s in the future is refused (422); omit it to stamp now. The
103
+ customer's cached entitlement answers go stale.
100
104
 
101
105
  body: the customer, the event name, and its value or properties.
102
106
  idempotency_key: sent as the ``Idempotency-Key`` header: a retried write with the same key is answered once, for 24 hours.
@@ -108,7 +112,8 @@ class AsyncUsageResource:
108
112
  async def record_batch(self, events: list[UsageEventRequest], *, idempotency_key: str | None = None) -> list[UsageEventResponse]:
109
113
  """Record up to ``MAX_BATCH_EVENTS`` events in one request; a larger list raises ``PayloadTooLargeError`` and is never sent.
110
114
 
111
- Each customer's cached entitlement answers go stale.
115
+ One event stamped outside the window ``record()`` allows refuses the whole batch (422, naming it); nothing is
116
+ recorded. Each customer's cached entitlement answers go stale.
112
117
 
113
118
  events: the events, each as ``record()`` takes it.
114
119
  idempotency_key: one key for the whole batch.
@@ -121,8 +126,9 @@ class AsyncUsageResource:
121
126
  """Read one recorded event back, with ``billing_outcome``.
122
127
 
123
128
  ``charged``, or why nothing was charged (``no_subscription``, ``no_meter_limit``, ``not_metered``,
124
- ``within_allowance``, ``not_deducted``, ``spend_cap_reached``, ``aggregation_not_billable``). It is None while
125
- ``processed`` is False: billing runs after ``record()`` returns, so poll this to learn what happened.
129
+ ``within_allowance``, ``not_deducted``, ``spend_cap_reached``, ``aggregation_not_billable``,
130
+ ``processing_failed``). It is None while ``processed`` is False: billing runs after ``record()`` returns, so poll
131
+ this to learn what happened.
126
132
 
127
133
  event_id: the event's ``id``, from ``record()``.
128
134
  """
File without changes
File without changes