meterbase 0.1.5__tar.gz → 0.3.0__tar.gz

{meterbase-0.1.5 → meterbase-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: meterbase
-Version: 0.1.5
+Version: 0.3.0
 Summary: Python SDK for the Meterbase engine
 Project-URL: Homepage, https://meterbase.tech
 Project-URL: Documentation, https://meterbase.tech/docs
@@ -185,11 +185,26 @@ see the error. When **you** supply the key, you get `TooLateError` with
 that was already recorded.
 
 **The SDK generates a key when you omit one, and reuses it across that call's
-retries** — including its own, since `track` is a `POST` it will replay.
-Supply your own when the caller already has an id for the work — a job id, a
-request id — so that a retry from further out than this SDK replays too. Keys
-are retained 35 days; a retry after that records a second event, which is not a
-case this API sets out to serve.
+retries.** For a retry from further out than this SDK — a queue, a restarted
+worker — mint the key once the work is done, and store it with the job before
+the first send:
+
+```python
+if job.usage_key is None:
+    job.usage_key = meterbase.idempotency_key()  # a UUIDv7, by the engine's clock
+    save_job(job)  # before sending, so a rerun reuses it
+
+meterbase.track(
+    customer_id=job.customer_id,
+    meter_id="ai_tokens",
+    quantity=job.tokens,
+    idempotency_key=job.usage_key,
+)
+```
+
+It is dated by the engine's clock as this client knows it, and the hour it is
+admitted for starts then: mint it when the work is queued and a slow queue can
+outlast it.
 
 ### Work you cannot do twice
 
@@ -256,6 +271,30 @@ afresh rather than finding anything.
 
 ### Customers
 
+**At sign-up, ensure the customer.** One call gets or creates them by your own
+id and gives them a first plan, and running it again changes nothing:
+
+```python
+ensured = meterbase.customers.ensure(
+    external_id="acct_1",
+    name="Acme",  # applied only when it creates the customer
+    plan="free",  # a plan key
+)
+ensured.created, ensured.plan_result, ensured.customer.plan
+```
+
+`plan_result` says what it did with the plan: `assigned`, `already_held`,
+`kept_other` when the customer holds another plan, or `none` when you named
+none. It never changes a plan the customer holds — a checkout that must move
+them calls [`customers.plan`](#a-customers-plan) — and never cancels a
+scheduled change. `cycle_anchor` puts a first plan's periods on a date the
+customer already has, and `mint_one_time=False` writes the plan's one-time
+grants already spent, for a customer you import with their remaining bonus.
+
+`ensure` and `retrieve_by_external_id` raise `MeterbaseError` before sending
+when the id is missing, empty or whitespace: without one, the lookup would name
+no customer.
+
 ```python
 customer = meterbase.customers.create(
     external_id="acct_1",
@@ -324,9 +363,17 @@ Each crossing is delivered as a webhook; see [Webhooks](#webhooks).
 ```python
 meterbase.meters.create(key="api_calls", name="API calls")  # plus optional thresholds
 meters = meterbase.meters.list().data
+meterbase.meters.retrieve("api_calls")  # by key, or by id
 meterbase.meters.archive(meter_id)  # soft delete, idempotent
 ```
 
+A meter's key works wherever its id does: `retrieve`, `update`, `usage` and
+`archive`, `meter_id` on a grant or a plan allowance, and the `meter_id` filter
+on their lists. Code written against a sandbox then runs unchanged in live,
+where the ids differ. A key that names no meter raises `NotFoundError`. A
+canonical UUID is always read as an id, so creating or renaming a meter to a
+key shaped like one raises `InvalidRequestError`.
+
 ### Plans
 
 A plan has one billing period, fixed when the plan is created. Everything it
@@ -348,6 +395,11 @@ meterbase.plans.archive(plan.id)  # stops new assignments, keeps existing ones
 customers were already measured against, so a different cadence is a different
 plan — move a customer with `customers.plan.assign`.
 
+A plan's key works wherever its id does, on the same terms as a meter's:
+`plans.retrieve("pro")`, `plans.allowances.set("pro", ...)`, `plan_id` on
+`customers.plan.assign` and `plan` on each change. A key that names no plan
+raises `NotFoundError`, and a key shaped like a UUID is refused.
+
 ### Plan allowances
 
 What a plan grants, one meter at a time. An allowance says _how much_, never
@@ -377,6 +429,12 @@ versions = meterbase.plans.allowances.list(plan.id).data
 Each `(plan, meter)` pair carries up to two lineages, `recurring` and
 `one_time`, numbering themselves separately. `kind` defaults to `recurring`.
 
+`apply_mode` says when a version reaches customers already on the plan:
+`immediate`, for the whole period they are in, or `next_cycle`, at each one's
+next boundary. Omitted, a meter's first `recurring` version on the plan is
+`immediate`, since there is nothing to phase out, and every later one is
+`next_cycle`. `one_time` is always `immediate`.
+
 **A soft cap** keeps the amount and drops the refusal: included usage, then
 overage.
 
@@ -482,6 +540,26 @@ except CycleChangeRequiresResetError:
     meterbase.customers.plan.restart(customer.id, plan=weekly.id)
 ```
 
+#### From a webhook
+
+A provider may deliver a webhook twice, and a second `restart` would start a
+second fresh period. Pass the event's id as `idempotency_key`, 1–255
+characters, and a retry repeats nothing:
+
+```python
+moved = meterbase.customers.plan.restart(
+    customer.id, plan="pro", idempotency_key=event.id
+)
+moved.replayed  # True when this event had already moved them: nothing was written
+```
+
+`assign`, `change`, `change_now` and `change_at_next_cycle` take one too. The
+same request under the key again answers with the assignment it made, as it is
+now, and writes nothing — so a second delivery of an old event cannot cancel a
+change scheduled since. Another request under the key raises
+`IdempotencyKeyReusedError`. A key is kept for good, per workspace. With a key,
+the SDK retries the call too.
+
 #### Reading where they stand
 
 ```python
@@ -513,6 +591,11 @@ instruction, and writes no new row of its own — so this reads the plan in forc
 and names it back. It returns the assignment still in force, or `None` for a
 customer holding no plan, who can have nothing pending.
 
+It takes no `idempotency_key`: it names whatever plan is in force when it runs,
+so a retry could name a different one and be refused as a different request.
+For a cancel a webhook orders, `assign` the plan the event says they keep, under
+the event's id.
+
 #### How much they have used
 
 ```python
@@ -616,6 +699,37 @@ Revoking withdraws what is left without erasing what was consumed, and is
 idempotent. Grants the engine minted itself from a plan's `one_time` allowance
 appear here with `source="plan"`; they cannot be created through `grant`.
 
+**A grant made from a payment's webhook** takes the payment's id as its
+`idempotency_key`, 1–255 characters: the provider may deliver the webhook
+twice, and a retry under the key cannot grant twice.
+
+```python
+grant = meterbase.customers.allowances.grant(
+    customer.id,
+    meter_id="ai_tokens",
+    amount=500_000,
+    source="purchased",
+    idempotency_key=payment.id,
+)
+grant.replayed  # True when this payment had already granted: nothing was written
+```
+
+The same request under the key again answers with that grant as it is now,
+perhaps spent or revoked since, and writes nothing. Another request under the
+key raises `IdempotencyKeyReusedError`, so build the body the same way every
+time: compute `expires_at` from the payment's own time, not from when the
+handler ran. A key is kept for good, per workspace. With a key, the SDK retries
+the call too.
+
+To find what a payment granted — to take it back on a refund, say — list by its
+key. Once the grant is revoked or has expired, add `include_closed=True`.
+
+```python
+paid = meterbase.customers.allowances.list(customer.id, idempotency_key=payment.id)
+for grant in paid.data:  # the grant the payment made, or none
+    meterbase.customers.allowances.revoke(customer.id, grant.id)
+```
+
 ## Webhooks
 
 Meterbase posts to your endpoints when a customer crosses a usage threshold,
@@ -786,6 +900,7 @@ except RateLimitError as error:
 | `NotFoundError`                          | 404                                                                                                                                       |
 | `ConflictError`                          | 409 — a key or external id is taken                                                                                                       |
 | `PeriodSettlingError`                    | 409 — a `ConflictError`: the period ended under a minute ago, so read it again after `retry_after` seconds                                |
+| `IdempotencyKeyReusedError`              | 409 — a `ConflictError`: the `idempotency_key` on a grant or plan change was already used for a different request. Nothing was written    |
 | `InvalidRequestError`                    | 422 — a field failed validation; or `400 invalid_query`, a query parameter that did                                                       |
 | `CycleChangeRequiresResetError`          | 422 — an `InvalidRequestError`: the two plans' cycles differ, so use `restart`                                                            |
 | `InvalidIdempotencyKeyError`             | 422 — an `InvalidRequestError`: the key was not a UUIDv7                                                                                  |
@@ -811,14 +926,18 @@ SDK would raise for a response, for realistic errors in your own tests.
 Meterbase(
     api_key="mb_sk_live_…",
     base_url="https://api.meterbase.dev",
-    timeout=35.0,  # seconds, per attempt
+    timeout=10.0,  # seconds, per attempt, on every call; unset, 35, and 3 for check
     max_retries=2,
     http_client=httpx.Client(proxy="http://localhost:8030"),  # yours to close
 )
 ```
 
 `timeout` bounds each attempt — connecting, sending, and each wait for the
-engine to answer — not the whole call. Pass an `http_client` for proxies,
+engine to answer — not the whole call. **`check` waits 3 s** unless the client
+sets `timeout`: it gates a request someone is waiting on, and answers in
+milliseconds when the engine is well. Decide what an `APITimeoutError` means
+there — failing open or failing closed — rather than leaving the user waiting
+out the 35 s the writes get. Pass an `http_client` for proxies,
 limits or a transport of your own: an `httpx.Client` for `Meterbase`, an
 `httpx.AsyncClient` for `AsyncMeterbase`.
 
@@ -838,11 +957,15 @@ an attempt already on the wire may still land, but it is never replayed, so a
 cancelled `track` cannot record usage twice. A sync call cannot be cancelled;
 bound it with `timeout` and `max_retries` instead.
 
-**Retries** apply to `GET`, `DELETE`, `track` and `reserve`, on connection
-failures, timeouts, 408, 429 and 5xx, with exponential backoff and full jitter.
+**Retries** apply to `GET`, `DELETE`, `track`, `reserve`, `customers.ensure`,
+and a grant or plan change given an `idempotency_key`, on connection failures,
+timeouts, 408, 429 and 5xx, with exponential backoff and full jitter.
 `Retry-After` is honoured when the engine sends it, up to eight seconds. Every
 other `POST` and `PATCH` is never replayed, because a retried create could
-produce a second row.
+produce a second row. An `ensure` can be, because running it twice changes
+nothing: one whose first attempt landed answers `created` false. So can a keyed
+grant or plan change, which the engine answers with what the first attempt
+wrote: one whose first attempt landed answers `replayed` true.
 
 `track` and `reserve` are the exception because they carry an idempotency key,
 and because the SDK fixes that key **before** the retry loop starts: every
@@ -871,6 +994,19 @@ Pre-1.0, the minor version is where breaking changes land — deliberately, so a
 change that will not run against your code cannot arrive as a patch. The SDK
 follows the engine's API, as the TypeScript SDK (`mbase-sdk`) does.
 
+**0.3.0** adds an `idempotency_key` on grants and plan changes, which also makes
+them safe to retry, `replayed` on their answers, and `IdempotencyKeyReusedError`.
+Nothing in it breaks code written for 0.2.0.
+
+**0.2.0** adds `customers.ensure` and `idempotency_key()`, and changes two
+behaviours:
+
+- `check` waits 3 s by default. The other calls keep 35 s, and a `timeout` set
+  on the client, or through `with_options`, still wins.
+- `retrieve_by_external_id` raises before sending when the id is missing, empty
+  or whitespace. Before, a `None` was dropped from the query, and the engine
+  answered with every customer, the newest first, which this returned.
+
 ## Development
 
 ```bash

{meterbase-0.1.5 → meterbase-0.3.0}/README.md

@@ -158,11 +158,26 @@ see the error. When **you** supply the key, you get `TooLateError` with
 that was already recorded.
 
 **The SDK generates a key when you omit one, and reuses it across that call's
-retries** — including its own, since `track` is a `POST` it will replay.
-Supply your own when the caller already has an id for the work — a job id, a
-request id — so that a retry from further out than this SDK replays too. Keys
-are retained 35 days; a retry after that records a second event, which is not a
-case this API sets out to serve.
+retries.** For a retry from further out than this SDK — a queue, a restarted
+worker — mint the key once the work is done, and store it with the job before
+the first send:
+
+```python
+if job.usage_key is None:
+    job.usage_key = meterbase.idempotency_key()  # a UUIDv7, by the engine's clock
+    save_job(job)  # before sending, so a rerun reuses it
+
+meterbase.track(
+    customer_id=job.customer_id,
+    meter_id="ai_tokens",
+    quantity=job.tokens,
+    idempotency_key=job.usage_key,
+)
+```
+
+It is dated by the engine's clock as this client knows it, and the hour it is
+admitted for starts then: mint it when the work is queued and a slow queue can
+outlast it.
 
 ### Work you cannot do twice
 
@@ -229,6 +244,30 @@ afresh rather than finding anything.
 
 ### Customers
 
+**At sign-up, ensure the customer.** One call gets or creates them by your own
+id and gives them a first plan, and running it again changes nothing:
+
+```python
+ensured = meterbase.customers.ensure(
+    external_id="acct_1",
+    name="Acme",  # applied only when it creates the customer
+    plan="free",  # a plan key
+)
+ensured.created, ensured.plan_result, ensured.customer.plan
+```
+
+`plan_result` says what it did with the plan: `assigned`, `already_held`,
+`kept_other` when the customer holds another plan, or `none` when you named
+none. It never changes a plan the customer holds — a checkout that must move
+them calls [`customers.plan`](#a-customers-plan) — and never cancels a
+scheduled change. `cycle_anchor` puts a first plan's periods on a date the
+customer already has, and `mint_one_time=False` writes the plan's one-time
+grants already spent, for a customer you import with their remaining bonus.
+
+`ensure` and `retrieve_by_external_id` raise `MeterbaseError` before sending
+when the id is missing, empty or whitespace: without one, the lookup would name
+no customer.
+
 ```python
 customer = meterbase.customers.create(
     external_id="acct_1",
@@ -297,9 +336,17 @@ Each crossing is delivered as a webhook; see [Webhooks](#webhooks).
 ```python
 meterbase.meters.create(key="api_calls", name="API calls")  # plus optional thresholds
 meters = meterbase.meters.list().data
+meterbase.meters.retrieve("api_calls")  # by key, or by id
 meterbase.meters.archive(meter_id)  # soft delete, idempotent
 ```
 
+A meter's key works wherever its id does: `retrieve`, `update`, `usage` and
+`archive`, `meter_id` on a grant or a plan allowance, and the `meter_id` filter
+on their lists. Code written against a sandbox then runs unchanged in live,
+where the ids differ. A key that names no meter raises `NotFoundError`. A
+canonical UUID is always read as an id, so creating or renaming a meter to a
+key shaped like one raises `InvalidRequestError`.
+
 ### Plans
 
 A plan has one billing period, fixed when the plan is created. Everything it
@@ -321,6 +368,11 @@ meterbase.plans.archive(plan.id)  # stops new assignments, keeps existing ones
 customers were already measured against, so a different cadence is a different
 plan — move a customer with `customers.plan.assign`.
 
+A plan's key works wherever its id does, on the same terms as a meter's:
+`plans.retrieve("pro")`, `plans.allowances.set("pro", ...)`, `plan_id` on
+`customers.plan.assign` and `plan` on each change. A key that names no plan
+raises `NotFoundError`, and a key shaped like a UUID is refused.
+
 ### Plan allowances
 
 What a plan grants, one meter at a time. An allowance says _how much_, never
@@ -350,6 +402,12 @@ versions = meterbase.plans.allowances.list(plan.id).data
 Each `(plan, meter)` pair carries up to two lineages, `recurring` and
 `one_time`, numbering themselves separately. `kind` defaults to `recurring`.
 
+`apply_mode` says when a version reaches customers already on the plan:
+`immediate`, for the whole period they are in, or `next_cycle`, at each one's
+next boundary. Omitted, a meter's first `recurring` version on the plan is
+`immediate`, since there is nothing to phase out, and every later one is
+`next_cycle`. `one_time` is always `immediate`.
+
 **A soft cap** keeps the amount and drops the refusal: included usage, then
 overage.
 
@@ -455,6 +513,26 @@ except CycleChangeRequiresResetError:
     meterbase.customers.plan.restart(customer.id, plan=weekly.id)
 ```
 
+#### From a webhook
+
+A provider may deliver a webhook twice, and a second `restart` would start a
+second fresh period. Pass the event's id as `idempotency_key`, 1–255
+characters, and a retry repeats nothing:
+
+```python
+moved = meterbase.customers.plan.restart(
+    customer.id, plan="pro", idempotency_key=event.id
+)
+moved.replayed  # True when this event had already moved them: nothing was written
+```
+
+`assign`, `change`, `change_now` and `change_at_next_cycle` take one too. The
+same request under the key again answers with the assignment it made, as it is
+now, and writes nothing — so a second delivery of an old event cannot cancel a
+change scheduled since. Another request under the key raises
+`IdempotencyKeyReusedError`. A key is kept for good, per workspace. With a key,
+the SDK retries the call too.
+
 #### Reading where they stand
 
 ```python
@@ -486,6 +564,11 @@ instruction, and writes no new row of its own — so this reads the plan in forc
 and names it back. It returns the assignment still in force, or `None` for a
 customer holding no plan, who can have nothing pending.
 
+It takes no `idempotency_key`: it names whatever plan is in force when it runs,
+so a retry could name a different one and be refused as a different request.
+For a cancel a webhook orders, `assign` the plan the event says they keep, under
+the event's id.
+
 #### How much they have used
 
 ```python
@@ -589,6 +672,37 @@ Revoking withdraws what is left without erasing what was consumed, and is
 idempotent. Grants the engine minted itself from a plan's `one_time` allowance
 appear here with `source="plan"`; they cannot be created through `grant`.
 
+**A grant made from a payment's webhook** takes the payment's id as its
+`idempotency_key`, 1–255 characters: the provider may deliver the webhook
+twice, and a retry under the key cannot grant twice.
+
+```python
+grant = meterbase.customers.allowances.grant(
+    customer.id,
+    meter_id="ai_tokens",
+    amount=500_000,
+    source="purchased",
+    idempotency_key=payment.id,
+)
+grant.replayed  # True when this payment had already granted: nothing was written
+```
+
+The same request under the key again answers with that grant as it is now,
+perhaps spent or revoked since, and writes nothing. Another request under the
+key raises `IdempotencyKeyReusedError`, so build the body the same way every
+time: compute `expires_at` from the payment's own time, not from when the
+handler ran. A key is kept for good, per workspace. With a key, the SDK retries
+the call too.
+
+To find what a payment granted — to take it back on a refund, say — list by its
+key. Once the grant is revoked or has expired, add `include_closed=True`.
+
+```python
+paid = meterbase.customers.allowances.list(customer.id, idempotency_key=payment.id)
+for grant in paid.data:  # the grant the payment made, or none
+    meterbase.customers.allowances.revoke(customer.id, grant.id)
+```
+
 ## Webhooks
 
 Meterbase posts to your endpoints when a customer crosses a usage threshold,
@@ -759,6 +873,7 @@ except RateLimitError as error:
 | `NotFoundError`                          | 404                                                                                                                                       |
 | `ConflictError`                          | 409 — a key or external id is taken                                                                                                       |
 | `PeriodSettlingError`                    | 409 — a `ConflictError`: the period ended under a minute ago, so read it again after `retry_after` seconds                                |
+| `IdempotencyKeyReusedError`              | 409 — a `ConflictError`: the `idempotency_key` on a grant or plan change was already used for a different request. Nothing was written    |
 | `InvalidRequestError`                    | 422 — a field failed validation; or `400 invalid_query`, a query parameter that did                                                       |
 | `CycleChangeRequiresResetError`          | 422 — an `InvalidRequestError`: the two plans' cycles differ, so use `restart`                                                            |
 | `InvalidIdempotencyKeyError`             | 422 — an `InvalidRequestError`: the key was not a UUIDv7                                                                                  |
@@ -784,14 +899,18 @@ SDK would raise for a response, for realistic errors in your own tests.
 Meterbase(
     api_key="mb_sk_live_…",
     base_url="https://api.meterbase.dev",
-    timeout=35.0,  # seconds, per attempt
+    timeout=10.0,  # seconds, per attempt, on every call; unset, 35, and 3 for check
     max_retries=2,
     http_client=httpx.Client(proxy="http://localhost:8030"),  # yours to close
 )
 ```
 
 `timeout` bounds each attempt — connecting, sending, and each wait for the
-engine to answer — not the whole call. Pass an `http_client` for proxies,
+engine to answer — not the whole call. **`check` waits 3 s** unless the client
+sets `timeout`: it gates a request someone is waiting on, and answers in
+milliseconds when the engine is well. Decide what an `APITimeoutError` means
+there — failing open or failing closed — rather than leaving the user waiting
+out the 35 s the writes get. Pass an `http_client` for proxies,
 limits or a transport of your own: an `httpx.Client` for `Meterbase`, an
 `httpx.AsyncClient` for `AsyncMeterbase`.
 
@@ -811,11 +930,15 @@ an attempt already on the wire may still land, but it is never replayed, so a
 cancelled `track` cannot record usage twice. A sync call cannot be cancelled;
 bound it with `timeout` and `max_retries` instead.
 
-**Retries** apply to `GET`, `DELETE`, `track` and `reserve`, on connection
-failures, timeouts, 408, 429 and 5xx, with exponential backoff and full jitter.
+**Retries** apply to `GET`, `DELETE`, `track`, `reserve`, `customers.ensure`,
+and a grant or plan change given an `idempotency_key`, on connection failures,
+timeouts, 408, 429 and 5xx, with exponential backoff and full jitter.
 `Retry-After` is honoured when the engine sends it, up to eight seconds. Every
 other `POST` and `PATCH` is never replayed, because a retried create could
-produce a second row.
+produce a second row. An `ensure` can be, because running it twice changes
+nothing: one whose first attempt landed answers `created` false. So can a keyed
+grant or plan change, which the engine answers with what the first attempt
+wrote: one whose first attempt landed answers `replayed` true.
 
 `track` and `reserve` are the exception because they carry an idempotency key,
 and because the SDK fixes that key **before** the retry loop starts: every
@@ -844,6 +967,19 @@ Pre-1.0, the minor version is where breaking changes land — deliberately, so a
 change that will not run against your code cannot arrive as a patch. The SDK
 follows the engine's API, as the TypeScript SDK (`mbase-sdk`) does.
 
+**0.3.0** adds an `idempotency_key` on grants and plan changes, which also makes
+them safe to retry, `replayed` on their answers, and `IdempotencyKeyReusedError`.
+Nothing in it breaks code written for 0.2.0.
+
+**0.2.0** adds `customers.ensure` and `idempotency_key()`, and changes two
+behaviours:
+
+- `check` waits 3 s by default. The other calls keep 35 s, and a `timeout` set
+  on the client, or through `with_options`, still wins.
+- `retrieve_by_external_id` raises before sending when the id is missing, empty
+  or whitespace. Before, a `None` was dropped from the query, and the engine
+  answered with every customer, the newest first, which this returned.
+
 ## Development
 
 ```bash

{meterbase-0.1.5 → meterbase-0.3.0}/src/meterbase/__init__.py

@@ -12,6 +12,7 @@ from .errors import (
     AuthenticationError,
     ConflictError,
     CycleChangeRequiresResetError,
+    IdempotencyKeyReusedError,
     InvalidIdempotencyKeyError,
     InvalidRequestError,
     MeterbaseError,
@@ -38,6 +39,7 @@ __all__ = [
     "ConflictError",
     "CycleChangeRequiresResetError",
     "Hold",
+    "IdempotencyKeyReusedError",
     "InvalidIdempotencyKeyError",
     "InvalidRequestError",
     "Meterbase",

{meterbase-0.1.5 → meterbase-0.3.0}/src/meterbase/_async/_transport.py

@@ -13,6 +13,7 @@ from typing import Any, TypeVar
 import httpx
 
 from .._http import (
+    DEFAULT_TIMEOUT,
     Body,
     Query,
     RequestOptions,
@@ -70,17 +71,21 @@ class AsyncTransport:
         query: Query | None = None,
         body: Body | None = None,
         idempotent: bool = False,
+        default_timeout: float = DEFAULT_TIMEOUT,
     ) -> Any:
         """
         `idempotent` replays a call even though its method is not safe. Only a
         route that carries an idempotency key may set it, and the key has to be
         in `body` already: the loop re-sends one body, so a key generated per
         attempt would count the same usage twice.
+
+        `default_timeout` applies when the options set none.
         """
         # Safe methods, plus the routes that carry an idempotency key and say
         # so. Any other POST or PATCH could create a second row on a replay.
         retryable = method in ("GET", "DELETE") or idempotent
 
+        timeout = default_timeout if options.timeout is None else options.timeout
         url = build_url(self._base_url, path, query)
         content = None if body is None else encode_body(body)
         headers = request_headers(self._api_key, has_body=content is not None)
@@ -91,7 +96,7 @@ class AsyncTransport:
                 await sleep(backoff(attempt, last_error))
 
             try:
-                response = await self._send(method, url, headers, content, options)
+                response = await self._send(method, url, headers, content, timeout)
             except APIConnectionError as unanswered:
                 # A connection failure proves nothing about whether the server
                 # acted, so it is replayed under the same idempotency rule.
@@ -122,7 +127,7 @@ class AsyncTransport:
         url: str,
         headers: dict[str, str],
         content: bytes | None,
-        options: RequestOptions,
+        timeout: float,
     ) -> httpx.Response:
         # Neither this nor the loop catches a BaseException — a cancelled task,
         # a Ctrl-C — so one ends the call where it stands and nothing is sent
@@ -134,12 +139,10 @@ class AsyncTransport:
                 url,
                 headers=headers,
                 content=content,
-                timeout=options.timeout,
+                timeout=timeout,
             )
         except httpx.TimeoutException as error:
-            raise APITimeoutError(
-                f"Request timed out after {options.timeout:g}s."
-            ) from error
+            raise APITimeoutError(f"Request timed out after {timeout:g}s.") from error
         except httpx.TransportError as error:
             raise APIConnectionError(f"Could not reach {self._origin}.") from error
 
@@ -169,6 +172,7 @@ class AsyncRequester:
         query: Query | None = None,
         body: Body | None = None,
         idempotent: bool = False,
+        default_timeout: float = DEFAULT_TIMEOUT,
     ) -> _T:
         data = await self.transport.request(
             method,
@@ -177,5 +181,6 @@ class AsyncRequester:
             query=query,
             body=body,
             idempotent=idempotent,
+            default_timeout=default_timeout,
         )
         return construct(cast_to, data)

{meterbase-0.1.5 → meterbase-0.3.0}/src/meterbase/_async/client.py

@@ -8,8 +8,8 @@ from typing import Any, TypeVar
 import httpx
 
 from .._http import (
+    CHECK_TIMEOUT,
     DEFAULT_MAX_RETRIES,
-    DEFAULT_TIMEOUT,
     RequestOptions,
     normalize_base_url,
 )
@@ -34,9 +34,9 @@ class AsyncMeterbase:
     there is no workspace to pass.
 
     `timeout` is in seconds and applies to each attempt rather than to the
-    whole call. `max_retries` counts the attempts after the first. Pass an
-    `http_client` to configure proxies, limits or transports yourself; it
-    stays yours to close.
+    whole call. Unset, it is 35 s, and 3 s for `check`. `max_retries` counts
+    the attempts after the first. Pass an `http_client` to configure proxies,
+    limits or transports yourself; it stays yours to close.
     """
 
     customers: AsyncCustomers
@@ -48,7 +48,7 @@ class AsyncMeterbase:
         *,
         api_key: str,
         base_url: str | None = None,
-        timeout: float = DEFAULT_TIMEOUT,
+        timeout: float | None = None,
         max_retries: int = DEFAULT_MAX_RETRIES,
         http_client: httpx.AsyncClient | None = None,
     ) -> None:
@@ -121,6 +121,11 @@ class AsyncMeterbase:
 
         `quantity` is what is about to be consumed, `1 … 100000000000`.
         Omitted, it is 1, which asks whether there is any capacity at all.
+
+        Waits 3 s unless the client sets `timeout`: it gates a request someone
+        is waiting on, and answers in milliseconds when the engine is well.
+        Decide what an `APITimeoutError` means here, failing open or closed,
+        rather than waiting out the 35 s the writes are given.
         """
         return await self._api.request(
             "POST",
@@ -131,6 +136,7 @@ class AsyncMeterbase:
                 "meter_id": meter_id,
                 "quantity": quantity,
             },
+            default_timeout=CHECK_TIMEOUT,
         )
 
     async def track(
@@ -246,6 +252,17 @@ class AsyncMeterbase:
         """Reports which workspace this key acts for."""
         return await self._api.request("GET", "/v1/whoami", WhoAmI)
 
+    def idempotency_key(self) -> str:
+        """
+        A UUIDv7 dated by the engine's clock as this client knows it: an
+        `idempotency_key` for `track`, or a `reservation_id`. For a retry from
+        further out than this SDK, mint one once the work is done, store it
+        with the job before the first send, and send it on every retry. The
+        engine admits a key for an hour from its date, and a reservation id
+        for 30 minutes.
+        """
+        return mint(self._api.transport.now_ms())
+
     async def aclose(self) -> None:
         """Closes the connections this client opened. An `http_client` passed
         in stays open: it is yours."""