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.
- {meterflow-0.6.1 → meterflow-0.7.0}/PKG-INFO +11 -5
- {meterflow-0.6.1 → meterflow-0.7.0}/README.md +10 -4
- {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/__init__.py +6 -0
- {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/_http.py +5 -1
- {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/_version.py +1 -1
- {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/resources/credits.py +42 -12
- {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/resources/subscriptions.py +32 -12
- {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/resources/usage.py +14 -8
- {meterflow-0.6.1 → meterflow-0.7.0}/LICENSE +0 -0
- {meterflow-0.6.1 → meterflow-0.7.0}/pyproject.toml +0 -0
- {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/_entitlement_cache.py +0 -0
- {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/_retry.py +0 -0
- {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/client.py +0 -0
- {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/errors.py +0 -0
- {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/py.typed +0 -0
- {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/resources/__init__.py +0 -0
- {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/resources/entitlements.py +0 -0
- {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/resources/plans.py +0 -0
- {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/resources/portal.py +0 -0
- {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/resources/webhooks.py +0 -0
- {meterflow-0.6.1 → meterflow-0.7.0}/src/meterflow/types.py +0 -0
- {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.
|
|
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
|
|
270
|
-
>
|
|
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":
|
|
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
|
|
218
|
-
>
|
|
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":
|
|
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.
|
|
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
|
-
|
|
53
|
-
|
|
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(
|
|
141
|
-
|
|
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(
|
|
241
|
-
|
|
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,
|
|
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",
|
|
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 ``_``
|
|
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 ``_``
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
71
|
-
``processed`` is False: billing runs after ``record()`` returns, so poll
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
125
|
-
``processed`` is False: billing runs after ``record()`` returns, so poll
|
|
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
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|