meterbase 0.1.4__tar.gz → 0.2.0__tar.gz

{meterbase-0.1.4 → meterbase-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: meterbase
-Version: 0.1.4
+Version: 0.2.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",
@@ -618,14 +657,16 @@ appear here with `source="plan"`; they cannot be created through `grant`.
 
 ## Webhooks
 
-Meterbase posts to your endpoints when a customer crosses a usage threshold.
-Add an endpoint in the dashboard under **Webhooks**; each has its own signing
-secret, shown once when you add it and revealable from its settings.
+Meterbase posts to your endpoints when a customer crosses a usage threshold,
+and when they run out of capacity on a meter. Add an endpoint in the dashboard
+under **Webhooks**; each has its own signing secret, shown once when you add it
+and revealable from its settings.
 
 | Event                 | When                                                                                   |
 | --------------------- | -------------------------------------------------------------------------------------- |
 | `threshold.crossed`   | a customer's usage of a meter crosses one of their thresholds                          |
 | `entitlement.reached` | that crossing at 100% of their plan's entitlement, sent as well as `threshold.crossed` |
+| `capacity.exhausted`  | a `track` spends the last unit a hard cap allows, so `check` refuses them from then on |
 
 ```json
 {
@@ -653,6 +694,34 @@ grants, so ask `check` for capacity. `entitlement.reached` marks the plan's
 entitlement, not spent capacity: a grant can still have balance, and a soft cap
 admits past it.
 
+`capacity.exhausted` carries no figures, since nothing is left:
+
+```json
+{
+  "id": "0199e2c4-7b10-7c3a-9d41-6a2f0e1b5c88",
+  "type": "capacity.exhausted",
+  "timestamp": "2026-10-14T09:12:03Z",
+  "data": {
+    "customer_id": "acct_1",
+    "meter_id": "ai_tokens",
+    "plan": { "id": "01993c40-…", "key": "pro", "name": "Pro" },
+    "period": {
+      "start": "2026-10-01T00:00:00Z",
+      "end": "2026-11-01T00:00:00Z"
+    },
+    "usage_event_id": "0199e2c4-7aff-7d2a-8c55-2f6e1a3bc738"
+  }
+}
+```
+
+`plan` and `period` are `None` when grants were the customer's only capacity on
+the meter. It counts the plan, a carry and every grant, so it is sent once each
+time all of them run out, and again after a new grant or period is spent. A soft
+cap or No Cap never sends it. A hold on the last unit does not send it; the
+`track` that commits the hold does. A grant expiring, a revoke or a plan change
+can leave a customer at 0 without it. Existing endpoints receive it only once
+you add it to their events.
+
 ### Verifying a delivery
 
 Verify every request before you trust it. `verify_webhook` checks the signature
@@ -662,7 +731,7 @@ and the timestamp, then returns the event:
 from flask import Flask, request
 
 from meterbase import WebhookVerificationError, verify_webhook
-from meterbase.types import EntitlementReachedEvent
+from meterbase.types import CapacityExhaustedEvent, EntitlementReachedEvent
 
 app = Flask(__name__)
 
@@ -680,6 +749,8 @@ def meterbase_webhook():
 
     if isinstance(event, EntitlementReachedEvent):
         ...  # event.data.customer_id has used their plan's allowance for event.data.meter_id
+    elif isinstance(event, CapacityExhaustedEvent):
+        ...  # check refuses event.data.customer_id on event.data.meter_id from now on
     return "", 204
 ```
 
@@ -687,9 +758,10 @@ In FastAPI or Starlette, pass `await request.body()` and `request.headers`; in
 Django, `request.body` and `request.headers`. Header names are matched without
 regard to case, so a plain `dict` works too.
 
-The event is a `ThresholdCrossedEvent` or an `EntitlementReachedEvent`, so
-`isinstance` tells them apart. New types can be added: one this release does not
-know reads as a plain `WebhookEvent`, so ignore any you do not handle.
+The event is a `ThresholdCrossedEvent`, an `EntitlementReachedEvent` or a
+`CapacityExhaustedEvent`, so `isinstance` tells them apart. New types can be
+added: one this release does not know reads as a plain `WebhookEvent`, so ignore
+any you do not handle.
 `verify_webhook` is synchronous, and fast enough to call from an async handler.
 
 Without the SDK, it is [Standard Webhooks](https://www.standardwebhooks.com):
@@ -709,7 +781,7 @@ included: Meterbase does not follow them.
 
 | Attempt | After the one before            |
 | ------- | ------------------------------- |
-| 1       | within a minute of the crossing |
+| 1       | within a minute of the event    |
 | 2       | 1 minute                        |
 | 3       | 6 minutes                       |
 | 4       | 36 minutes                      |
@@ -778,14 +850,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`.
 
@@ -805,11 +881,13 @@ 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.
-`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.
+**Retries** apply to `GET`, `DELETE`, `track`, `reserve` and
+`customers.ensure`, 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. An `ensure` can
+be, because running it twice changes nothing: one whose first attempt landed
+answers `created` false.
 
 `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
@@ -838,6 +916,15 @@ 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.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.4 → meterbase-0.2.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",
@@ -591,14 +630,16 @@ appear here with `source="plan"`; they cannot be created through `grant`.
 
 ## Webhooks
 
-Meterbase posts to your endpoints when a customer crosses a usage threshold.
-Add an endpoint in the dashboard under **Webhooks**; each has its own signing
-secret, shown once when you add it and revealable from its settings.
+Meterbase posts to your endpoints when a customer crosses a usage threshold,
+and when they run out of capacity on a meter. Add an endpoint in the dashboard
+under **Webhooks**; each has its own signing secret, shown once when you add it
+and revealable from its settings.
 
 | Event                 | When                                                                                   |
 | --------------------- | -------------------------------------------------------------------------------------- |
 | `threshold.crossed`   | a customer's usage of a meter crosses one of their thresholds                          |
 | `entitlement.reached` | that crossing at 100% of their plan's entitlement, sent as well as `threshold.crossed` |
+| `capacity.exhausted`  | a `track` spends the last unit a hard cap allows, so `check` refuses them from then on |
 
 ```json
 {
@@ -626,6 +667,34 @@ grants, so ask `check` for capacity. `entitlement.reached` marks the plan's
 entitlement, not spent capacity: a grant can still have balance, and a soft cap
 admits past it.
 
+`capacity.exhausted` carries no figures, since nothing is left:
+
+```json
+{
+  "id": "0199e2c4-7b10-7c3a-9d41-6a2f0e1b5c88",
+  "type": "capacity.exhausted",
+  "timestamp": "2026-10-14T09:12:03Z",
+  "data": {
+    "customer_id": "acct_1",
+    "meter_id": "ai_tokens",
+    "plan": { "id": "01993c40-…", "key": "pro", "name": "Pro" },
+    "period": {
+      "start": "2026-10-01T00:00:00Z",
+      "end": "2026-11-01T00:00:00Z"
+    },
+    "usage_event_id": "0199e2c4-7aff-7d2a-8c55-2f6e1a3bc738"
+  }
+}
+```
+
+`plan` and `period` are `None` when grants were the customer's only capacity on
+the meter. It counts the plan, a carry and every grant, so it is sent once each
+time all of them run out, and again after a new grant or period is spent. A soft
+cap or No Cap never sends it. A hold on the last unit does not send it; the
+`track` that commits the hold does. A grant expiring, a revoke or a plan change
+can leave a customer at 0 without it. Existing endpoints receive it only once
+you add it to their events.
+
 ### Verifying a delivery
 
 Verify every request before you trust it. `verify_webhook` checks the signature
@@ -635,7 +704,7 @@ and the timestamp, then returns the event:
 from flask import Flask, request
 
 from meterbase import WebhookVerificationError, verify_webhook
-from meterbase.types import EntitlementReachedEvent
+from meterbase.types import CapacityExhaustedEvent, EntitlementReachedEvent
 
 app = Flask(__name__)
 
@@ -653,6 +722,8 @@ def meterbase_webhook():
 
     if isinstance(event, EntitlementReachedEvent):
         ...  # event.data.customer_id has used their plan's allowance for event.data.meter_id
+    elif isinstance(event, CapacityExhaustedEvent):
+        ...  # check refuses event.data.customer_id on event.data.meter_id from now on
     return "", 204
 ```
 
@@ -660,9 +731,10 @@ In FastAPI or Starlette, pass `await request.body()` and `request.headers`; in
 Django, `request.body` and `request.headers`. Header names are matched without
 regard to case, so a plain `dict` works too.
 
-The event is a `ThresholdCrossedEvent` or an `EntitlementReachedEvent`, so
-`isinstance` tells them apart. New types can be added: one this release does not
-know reads as a plain `WebhookEvent`, so ignore any you do not handle.
+The event is a `ThresholdCrossedEvent`, an `EntitlementReachedEvent` or a
+`CapacityExhaustedEvent`, so `isinstance` tells them apart. New types can be
+added: one this release does not know reads as a plain `WebhookEvent`, so ignore
+any you do not handle.
 `verify_webhook` is synchronous, and fast enough to call from an async handler.
 
 Without the SDK, it is [Standard Webhooks](https://www.standardwebhooks.com):
@@ -682,7 +754,7 @@ included: Meterbase does not follow them.
 
 | Attempt | After the one before            |
 | ------- | ------------------------------- |
-| 1       | within a minute of the crossing |
+| 1       | within a minute of the event    |
 | 2       | 1 minute                        |
 | 3       | 6 minutes                       |
 | 4       | 36 minutes                      |
@@ -751,14 +823,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`.
 
@@ -778,11 +854,13 @@ 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.
-`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.
+**Retries** apply to `GET`, `DELETE`, `track`, `reserve` and
+`customers.ensure`, 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. An `ensure` can
+be, because running it twice changes nothing: one whose first attempt landed
+answers `created` false.
 
 `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
@@ -811,6 +889,15 @@ 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.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.4 → meterbase-0.2.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.4 → meterbase-0.2.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."""

{meterbase-0.1.4 → meterbase-0.2.0}/src/meterbase/_async/resources/customers.py

@@ -3,12 +3,13 @@ from __future__ import annotations
 from collections.abc import Mapping, Sequence
 from typing import Any, overload
 
-from ..._http import segment
+from ..._http import require_external_id, segment
 from ..._models import ListResult, list_of
 from ..._not_given import NOT_GIVEN, NotGiven
 from ...errors import NotFoundError
 from ...types import (
     Customer,
+    CustomerEnsureResult,
     CustomerEntitlement,
     CustomerUsage,
     CustomerWithPlan,
@@ -59,6 +60,50 @@ class AsyncCustomers:
             },
         )
 
+    async def ensure(
+        self,
+        *,
+        external_id: str,
+        name: str | NotGiven = NOT_GIVEN,
+        metadata: Mapping[str, Any] | NotGiven = NOT_GIVEN,
+        plan: str | NotGiven = NOT_GIVEN,
+        cycle_anchor: str | NotGiven = NOT_GIVEN,
+        mint_one_time: bool | NotGiven = NOT_GIVEN,
+    ) -> CustomerEnsureResult:
+        """
+        Gets or creates the customer by `external_id`, and gives one who holds
+        no plan the `plan` named, in one transaction. Safe on every sign-up and
+        safe to retry: rerunning it changes nothing, and it never changes a
+        plan the customer already holds. `plan_result` says which of those
+        happened.
+
+        `name` and `metadata` apply only to a customer this creates. `plan` is
+        a plan key; omit it to leave the plan alone. `cycle_anchor`, RFC 3339,
+        only with `plan` and never in the future, is used only when this call
+        assigns the plan. `mint_one_time=False` writes the plan's one-time
+        grants already spent, for an imported customer whose remaining bonus
+        you grant yourself.
+
+        Raises `MeterbaseError` before sending when `external_id` is missing,
+        empty or whitespace.
+        """
+        require_external_id("ensure", external_id)
+
+        return await self._api.request(
+            "POST",
+            "/v1/customers/ensure",
+            CustomerEnsureResult,
+            body={
+                "external_id": external_id,
+                "name": name,
+                "metadata": metadata,
+                "plan": plan,
+                "cycle_anchor": cycle_anchor,
+                "mint_one_time": mint_one_time,
+            },
+            idempotent=True,
+        )
+
     async def list(
         self, *, include_deleted: bool | NotGiven = NOT_GIVEN
     ) -> ListResult[Customer]:
@@ -88,7 +133,12 @@ class AsyncCustomers:
         Resolves the tenant's own identifier, or `None`, embedding the plan the
         way `retrieve` does. The engine answers this as a filtered list, so a
         miss is an empty collection rather than a 404.
+
+        Raises `MeterbaseError` before sending when `external_id` is missing,
+        empty or whitespace.
         """
+        require_external_id("retrieve_by_external_id", external_id)
+
         found = await self._api.request(
             "GET",
             "/v1/customers",

{meterbase-0.1.4 → meterbase-0.2.0}/src/meterbase/_http.py

@@ -24,6 +24,7 @@ from .errors import APIError, MeterbaseError, error_from_response
 
 DEFAULT_BASE_URL = "https://api.meterbase.tech"
 DEFAULT_TIMEOUT = 35.0
+CHECK_TIMEOUT = 3.0
 DEFAULT_MAX_RETRIES = 2
 MAX_BACKOFF = 8.0
 
@@ -35,8 +36,9 @@ Body = Mapping[str, object]
 
 @dataclass(frozen=True)
 class RequestOptions:
-    timeout: float
-    """Seconds, per attempt rather than per call."""
+    timeout: float | None
+    """Seconds, per attempt rather than per call. `None` leaves each call its
+    own default."""
     max_retries: int
 
     def __post_init__(self) -> None:
@@ -44,7 +46,7 @@ class RequestOptions:
         # makes no attempt has nothing to answer with.
         if self.max_retries < 0:
             raise MeterbaseError("max_retries should be 0 or more.")
-        if not self.timeout > 0:
+        if self.timeout is not None and not self.timeout > 0:
             raise MeterbaseError("timeout should be a number of seconds above 0.")
 
 
@@ -73,6 +75,17 @@ def segment(value: str) -> str:
     return quote(value, safe="")
 
 
+def require_external_id(method: str, external_id: object) -> None:
+    """
+    Without an id the lookup becomes an unfiltered list, which older engines
+    answered newest first: the caller got another customer back.
+    """
+    if external_id is None or str(external_id).strip() == "":
+        raise MeterbaseError(
+            f"customers.{method} needs an external id, and got {external_id!r}."
+        )
+
+
 def build_url(base_url: str, path: str, query: Query | None) -> str:
     pairs = [
         (key, _query_value(value))

{meterbase-0.1.4 → meterbase-0.2.0}/src/meterbase/_sync/_transport.py

@@ -17,6 +17,7 @@ from typing import Any, TypeVar
 import httpx
 
 from .._http import (
+    DEFAULT_TIMEOUT,
     Body,
     Query,
     RequestOptions,
@@ -74,17 +75,21 @@ class Transport:
         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)
@@ -95,7 +100,7 @@ class Transport:
                 sleep(backoff(attempt, last_error))
 
             try:
-                response = self._send(method, url, headers, content, options)
+                response = 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.
@@ -126,7 +131,7 @@ class Transport:
         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
@@ -138,12 +143,10 @@ class Transport:
                 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
 
@@ -173,6 +176,7 @@ class Requester:
         query: Query | None = None,
         body: Body | None = None,
         idempotent: bool = False,
+        default_timeout: float = DEFAULT_TIMEOUT,
     ) -> _T:
         data = self.transport.request(
             method,
@@ -181,5 +185,6 @@ class Requester:
             query=query,
             body=body,
             idempotent=idempotent,
+            default_timeout=default_timeout,
         )
         return construct(cast_to, data)

{meterbase-0.1.4 → meterbase-0.2.0}/src/meterbase/_sync/client.py

@@ -12,8 +12,8 @@ from typing import Any, TypeVar
 import httpx
 
 from .._http import (
+    CHECK_TIMEOUT,
     DEFAULT_MAX_RETRIES,
-    DEFAULT_TIMEOUT,
     RequestOptions,
     normalize_base_url,
 )
@@ -38,9 +38,9 @@ class Meterbase:
     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: Customers
@@ -52,7 +52,7 @@ class Meterbase:
         *,
         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.Client | None = None,
     ) -> None:
@@ -125,6 +125,11 @@ class Meterbase:
 
         `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 self._api.request(
             "POST",
@@ -135,6 +140,7 @@ class Meterbase:
                 "meter_id": meter_id,
                 "quantity": quantity,
             },
+            default_timeout=CHECK_TIMEOUT,
         )
 
     def track(
@@ -250,6 +256,17 @@ class Meterbase:
         """Reports which workspace this key acts for."""
         return 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())
+
     def close(self) -> None:
         """Closes the connections this client opened. An `http_client` passed
         in stays open: it is yours."""

{meterbase-0.1.4 → meterbase-0.2.0}/src/meterbase/_sync/resources/customers.py

@@ -7,12 +7,13 @@ from __future__ import annotations
 from collections.abc import Mapping, Sequence
 from typing import Any, overload
 
-from ..._http import segment
+from ..._http import require_external_id, segment
 from ..._models import ListResult, list_of
 from ..._not_given import NOT_GIVEN, NotGiven
 from ...errors import NotFoundError
 from ...types import (
     Customer,
+    CustomerEnsureResult,
     CustomerEntitlement,
     CustomerUsage,
     CustomerWithPlan,
@@ -63,6 +64,50 @@ class Customers:
             },
         )
 
+    def ensure(
+        self,
+        *,
+        external_id: str,
+        name: str | NotGiven = NOT_GIVEN,
+        metadata: Mapping[str, Any] | NotGiven = NOT_GIVEN,
+        plan: str | NotGiven = NOT_GIVEN,
+        cycle_anchor: str | NotGiven = NOT_GIVEN,
+        mint_one_time: bool | NotGiven = NOT_GIVEN,
+    ) -> CustomerEnsureResult:
+        """
+        Gets or creates the customer by `external_id`, and gives one who holds
+        no plan the `plan` named, in one transaction. Safe on every sign-up and
+        safe to retry: rerunning it changes nothing, and it never changes a
+        plan the customer already holds. `plan_result` says which of those
+        happened.
+
+        `name` and `metadata` apply only to a customer this creates. `plan` is
+        a plan key; omit it to leave the plan alone. `cycle_anchor`, RFC 3339,
+        only with `plan` and never in the future, is used only when this call
+        assigns the plan. `mint_one_time=False` writes the plan's one-time
+        grants already spent, for an imported customer whose remaining bonus
+        you grant yourself.
+
+        Raises `MeterbaseError` before sending when `external_id` is missing,
+        empty or whitespace.
+        """
+        require_external_id("ensure", external_id)
+
+        return self._api.request(
+            "POST",
+            "/v1/customers/ensure",
+            CustomerEnsureResult,
+            body={
+                "external_id": external_id,
+                "name": name,
+                "metadata": metadata,
+                "plan": plan,
+                "cycle_anchor": cycle_anchor,
+                "mint_one_time": mint_one_time,
+            },
+            idempotent=True,
+        )
+
     def list(
         self, *, include_deleted: bool | NotGiven = NOT_GIVEN
     ) -> ListResult[Customer]:
@@ -90,7 +135,12 @@ class Customers:
         Resolves the tenant's own identifier, or `None`, embedding the plan the
         way `retrieve` does. The engine answers this as a filtered list, so a
         miss is an empty collection rather than a 404.
+
+        Raises `MeterbaseError` before sending when `external_id` is missing,
+        empty or whitespace.
         """
+        require_external_id("retrieve_by_external_id", external_id)
+
         found = self._api.request(
             "GET",
             "/v1/customers",

meterbase-0.2.0/src/meterbase/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

{meterbase-0.1.4 → meterbase-0.2.0}/src/meterbase/errors.py

@@ -269,7 +269,7 @@ def error_from_response(
 
     if status == 400:
         # A parameter that failed validation, as a 422 is a field that did.
-        if code == "invalid_query":
+        if code in ("invalid_query", "invalid_external_id"):
             return InvalidRequestError(**fields)
         return APIError(**fields)
     if status == 401:

{meterbase-0.1.4 → meterbase-0.2.0}/src/meterbase/types.py

@@ -19,17 +19,21 @@ __all__ = [
     "AllowanceSource",
     "ApplyMode",
     "Assignment",
+    "CapacityExhaustedEvent",
+    "CapacityExhaustion",
     "CheckRateLimit",
     "CheckReason",
     "CheckResult",
     "ClosedPeriod",
     "ClosedPeriodMeter",
     "Customer",
+    "CustomerEnsureResult",
     "CustomerEntitlement",
     "CustomerUsage",
     "CustomerWithPlan",
     "DayUsage",
     "EmbeddedPlan",
+    "EnsurePlanResult",
     "EntitlementReachedEvent",
     "EntitlementState",
     "IncomingVersion",
@@ -138,6 +142,24 @@ class CustomerWithPlan(Customer):
     pending_plan: EmbeddedPlan | None
 
 
+EnsurePlanResult = Literal["assigned", "already_held", "kept_other", "none"]
+"""
+What `ensure` did with the plan it named. It never changes a plan: a customer
+holding another one is `kept_other`, and moving them stays `customers.plan`'s
+job. `none` when no plan was named.
+"""
+
+
+class CustomerEnsureResult(Model):
+    customer: CustomerWithPlan
+    """As the call left it, with the plan embedded as `retrieve` embeds it."""
+    created: bool
+    plan_result: EnsurePlanResult
+    cycle_anchor_differs: bool
+    """`cycle_anchor` was sent, and the plan the customer already held runs on
+    another anchor. Nothing changed: `customer.plan.anchor_at` is in force."""
+
+
 # Check ----------------------------------------------------------------------
 
 CheckReason = Literal["entitlement", "rate_limit"] | str
@@ -614,3 +636,28 @@ class EntitlementReachedEvent(WebhookEvent):
     id."""
 
     data: ThresholdCrossing
+
+
+class CapacityExhaustion(Model):
+    """What `capacity.exhausted` reports. No figures: available is 0."""
+
+    customer_id: str
+    """The tenant's own customer id."""
+    meter_id: str
+    """The meter's key."""
+    plan: ThresholdPlan | None
+    """The plan in force when the last unit was spent; `None` when grants were
+    the only capacity on the meter."""
+    period: Period | None
+    """That plan's period, so `end` is when it refills; `None` when grants
+    were the only capacity on the meter."""
+    usage_event_id: str
+    """The track that spent the last unit."""
+
+
+class CapacityExhaustedEvent(WebhookEvent):
+    """`capacity.exhausted`: sent when a track spends the last unit a hard cap
+    allows, so `check` refuses from then on. Once each time capacity runs
+    out."""
+
+    data: CapacityExhaustion

{meterbase-0.1.4 → meterbase-0.2.0}/src/meterbase/webhooks.py

@@ -12,7 +12,12 @@ from typing import Any, Protocol, cast
 
 from ._json import is_object
 from .errors import MeterbaseError, WebhookVerificationError
-from .types import EntitlementReachedEvent, ThresholdCrossedEvent, WebhookEvent
+from .types import (
+    CapacityExhaustedEvent,
+    EntitlementReachedEvent,
+    ThresholdCrossedEvent,
+    WebhookEvent,
+)
 
 __all__ = ["WebhookHeaders", "verify_webhook"]
 
@@ -22,6 +27,7 @@ DEFAULT_TOLERANCE_SECONDS = 5 * 60
 _EVENTS: dict[str, type[WebhookEvent]] = {
     "threshold.crossed": ThresholdCrossedEvent,
     "entitlement.reached": EntitlementReachedEvent,
+    "capacity.exhausted": CapacityExhaustedEvent,
 }
 
 
@@ -54,10 +60,10 @@ def verify_webhook(
     rotating. `tolerance_seconds` is how far `webhook-timestamp` may be from
     now.
 
-    The event is a `ThresholdCrossedEvent` or an `EntitlementReachedEvent`, so
-    `isinstance` tells them apart. A type this release does not know reads as
-    a plain `WebhookEvent`: new types can be added, so ignore any you do not
-    handle.
+    The event is a `ThresholdCrossedEvent`, an `EntitlementReachedEvent` or a
+    `CapacityExhaustedEvent`, so `isinstance` tells them apart. A type this
+    release does not know reads as a plain `WebhookEvent`: new types can be
+    added, so ignore any you do not handle.
     """
     msg_id = _header(headers, "webhook-id")
     timestamp = _header(headers, "webhook-timestamp")

meterbase-0.1.4/src/meterbase/_version.py

@@ -1 +0,0 @@
-__version__ = "0.1.4"