meterbase 0.1.5__tar.gz → 0.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: meterbase
-Version: 0.1.5
+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",
@@ -811,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`.
 
@@ -838,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
@@ -871,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.5 → 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",
@@ -784,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`.
 
@@ -811,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
@@ -844,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.5 → 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.5 → 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.5 → 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.5 → 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.5 → 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.5 → 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.5 → 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.5 → 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.5 → meterbase-0.2.0}/src/meterbase/types.py

@@ -27,11 +27,13 @@ __all__ = [
     "ClosedPeriod",
     "ClosedPeriodMeter",
     "Customer",
+    "CustomerEnsureResult",
     "CustomerEntitlement",
     "CustomerUsage",
     "CustomerWithPlan",
     "DayUsage",
     "EmbeddedPlan",
+    "EnsurePlanResult",
     "EntitlementReachedEvent",
     "EntitlementState",
     "IncomingVersion",
@@ -140,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

meterbase-0.1.5/src/meterbase/_version.py

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