meterflow 0.1.0__py3-none-any.whl

meterflow/__init__.py

@@ -0,0 +1,43 @@
+"""Official Python SDK for MeterFlow — usage-based billing, credit management, and metering.
+
+from meterflow import MeterFlow
+
+client = MeterFlow(api_key="mf_live_...")
+client.credits.grant({"customer_external_id": "customer_123", "amount": 5000, "metadata": {}})
+"""
+
+from ._version import __version__
+from .client import AsyncMeterFlow, ClientOptions, MeterFlow
+from .errors import (
+    AuthError,
+    ConflictError,
+    InsufficientCreditsError,
+    MeterFlowError,
+    NotFoundError,
+    PayloadTooLargeError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+    ValidationFieldError,
+)
+from .resources.usage import MAX_BATCH_EVENTS
+from .webhook import verify_webhook
+
+__all__ = [
+    "__version__",
+    "MeterFlow",
+    "AsyncMeterFlow",
+    "ClientOptions",
+    "MeterFlowError",
+    "AuthError",
+    "NotFoundError",
+    "InsufficientCreditsError",
+    "ConflictError",
+    "PayloadTooLargeError",
+    "ValidationError",
+    "ValidationFieldError",
+    "RateLimitError",
+    "ServerError",
+    "MAX_BATCH_EVENTS",
+    "verify_webhook",
+]

meterflow/_http.py

@@ -0,0 +1,160 @@
+"""The HTTP layer both clients share: URL/header building, error-body parsing, status → error mapping.
+
+Only the *waiting* differs between sync and async, so the request loops live in ``client.py`` and
+everything they call lives here, once. Mirrors ``sdks/node/src/utils/http.ts``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from ._version import __version__
+from .errors import (
+    AuthError,
+    ConflictError,
+    InsufficientCreditsError,
+    MeterFlowError,
+    NotFoundError,
+    PayloadTooLargeError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+    ValidationFieldError,
+)
+
+USER_AGENT = f"meterflow-python/{__version__}"
+
+QueryValue = str | int | float | bool | None
+
+# Indirections so tests can make the retry loop instantaneous without touching the clock.
+_sleep = time.sleep
+
+
+async def _async_sleep(seconds: float) -> None:
+    await asyncio.sleep(seconds)
+
+
+@dataclass(frozen=True)
+class RequestSpec:
+    """One API call, described by a resource method and executed by a client."""
+
+    method: str
+    path: str
+    body: Any = None
+    query: dict[str, QueryValue] = field(default_factory=dict)
+    idempotency_key: str | None = None
+    timeout: float | None = None
+
+
+def encode_path_segment(value: str) -> str:
+    """Customer ids are caller-chosen strings (emails, ``user/42``…) — they must never split the path."""
+    return quote(value, safe="")
+
+
+def build_headers(api_key: str, spec: RequestSpec) -> dict[str, str]:
+    headers = {"Authorization": f"Bearer {api_key}", "User-Agent": USER_AGENT, "Accept": "application/json"}
+    if spec.body is not None:
+        headers["Content-Type"] = "application/json"
+    if spec.idempotency_key:
+        headers["Idempotency-Key"] = spec.idempotency_key
+    return headers
+
+
+def build_params(query: dict[str, QueryValue]) -> dict[str, str]:
+    """Unset (``None``) filters are simply not sent; booleans go as ``true``/``false`` like the Node SDK."""
+    params: dict[str, str] = {}
+    for key, value in query.items():
+        if value is None:
+            continue
+        params[key] = ("true" if value else "false") if isinstance(value, bool) else str(value)
+    return params
+
+
+@dataclass(frozen=True)
+class ParsedError:
+    message: str
+    fields: list[ValidationFieldError]
+
+
+def _is_field_error(value: object) -> bool:
+    return isinstance(value, dict) and isinstance(value.get("field"), str) and isinstance(value.get("message"), str)
+
+
+def parse_error_body(response: httpx.Response) -> ParsedError:
+    """The API answers every error as ``{"error": {"code", "message", "fields"?}}`` (``app/api/src/exceptions.py``).
+
+    ``detail`` is FastAPI's default shape, kept as a fallback so an unexpected passthrough still
+    yields a readable message rather than a JSON blob.
+    """
+    try:
+        payload = response.json()
+    except (json.JSONDecodeError, ValueError):
+        return ParsedError(response.reason_phrase or f"HTTP {response.status_code}", [])
+    if not isinstance(payload, dict):
+        return ParsedError(json.dumps(payload), [])
+    error = payload.get("error")
+    if isinstance(error, dict) and isinstance(error.get("message"), str):
+        raw_fields = error.get("fields")
+        fields: list[ValidationFieldError] = (
+            [{"field": item["field"], "message": item["message"]} for item in raw_fields if _is_field_error(item)]
+            if isinstance(raw_fields, list)
+            else []
+        )
+        # A 422's headline is always "Validation failed"; the field list is what the caller needs.
+        detail = "; ".join(f"{item['field']}: {item['message']}" for item in fields)
+        message = f"{error['message']}: {detail}" if detail else error["message"]
+        return ParsedError(message, fields)
+    detail_value = payload.get("detail")
+    if isinstance(detail_value, str):
+        return ParsedError(detail_value, [])
+    return ParsedError(json.dumps(payload), [])
+
+
+def map_response_error(response: httpx.Response) -> MeterFlowError:
+    status = response.status_code
+    parsed = parse_error_body(response)
+    request_id = response.headers.get("x-request-id")
+    message, fields = parsed.message, parsed.fields
+    if status in (401, 403):
+        return AuthError(message, request_id=request_id, status_code=status)
+    if status == 402:
+        return InsufficientCreditsError(message, request_id=request_id)
+    if status == 404:
+        return NotFoundError(message, request_id=request_id)
+    if status == 409:
+        return ConflictError(message, request_id=request_id)
+    if status == 413:
+        return PayloadTooLargeError(message, request_id=request_id)
+    if status == 422:
+        return ValidationError(message, request_id=request_id, fields=fields)
+    if status == 429:
+        retry_after_raw = response.headers.get("retry-after")
+        retry_after = int(retry_after_raw) if retry_after_raw is not None and retry_after_raw.strip().isdigit() else None
+        return RateLimitError(message, retry_after=retry_after, request_id=request_id)
+    if status >= 500:
+        return ServerError(message, request_id=request_id, status_code=status)
+    return MeterFlowError(message, "request_error", retryable=False, request_id=request_id, status_code=status)
+
+
+def decode_response(response: httpx.Response) -> Any:
+    """2xx → parsed JSON; ``204`` / an empty body → ``None`` (``subscriptions.delete``)."""
+    if response.status_code == 204 or not response.content:
+        return None
+    return response.json()
+
+
+def request_kwargs(api_key: str, spec: RequestSpec) -> dict[str, Any]:
+    """Everything ``httpx.Client.request`` / ``AsyncClient.request`` needs beyond the method and path."""
+    kwargs: dict[str, Any] = {"headers": build_headers(api_key, spec), "params": build_params(spec.query)}
+    if spec.body is not None:
+        kwargs["content"] = json.dumps(spec.body).encode("utf-8")
+    if spec.timeout is not None:
+        kwargs["timeout"] = spec.timeout
+    return kwargs

meterflow/_retry.py

@@ -0,0 +1,38 @@
+"""Retry policy shared by the sync and async clients.
+
+The policy only *decides* — how long to wait before attempt N+1, or that the caller should give up.
+The clients do the sleeping (``time.sleep`` vs ``asyncio.sleep``), so the backoff maths lives once.
+Mirrors the Node SDK: exponential base (1 s × factor^attempt, capped), ±25 % jitter, and a 429's
+``Retry-After`` taken verbatim instead of the computed delay.
+"""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass
+
+from .errors import MeterFlowError, RateLimitError
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    retries: int = 3
+    factor: float = 2.0
+    jitter: bool = True
+    max_delay_seconds: float = 10.0
+
+    def should_retry(self, error: BaseException) -> bool:
+        """API errors say for themselves whether a retry can help; anything else is a transport failure and can."""
+        if isinstance(error, MeterFlowError):
+            return error.retryable
+        return True
+
+    def delay_before_retry(self, attempt: int, error: BaseException) -> float | None:
+        """Seconds to wait before retrying ``attempt`` (0-based), or ``None`` when the caller must re-raise."""
+        is_last = attempt >= self.retries
+        if is_last or not self.should_retry(error):
+            return None
+        if isinstance(error, RateLimitError) and error.retry_after is not None:
+            return float(error.retry_after)
+        base = min(1.0 * (self.factor**attempt), self.max_delay_seconds)
+        return base * (0.75 + random.random() * 0.5) if self.jitter else base  # noqa: S311 — jitter, not security

meterflow/_version.py

@@ -0,0 +1,3 @@
+# The one place the version lives. pyproject.toml reads it (hatch dynamic version) and the
+# User-Agent header reports it, so a release bump edits this file and nothing else.
+__version__ = "0.1.0"

meterflow/client.py

@@ -0,0 +1,148 @@
+"""``MeterFlow`` (sync) and ``AsyncMeterFlow`` — same options, same resources, same errors.
+
+Resources describe a call as a ``RequestSpec``; the client executes it with retries. Everything that
+does not depend on *how* you wait lives in ``_http.py`` and ``_retry.py``, so the two clients are
+thin and cannot drift apart.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from itertools import count
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from ._http import RequestSpec, _async_sleep, _sleep, decode_response, map_response_error, request_kwargs
+from ._retry import RetryPolicy
+from .resources.credits import AsyncCreditsResource, CreditsResource
+from .resources.entitlements import AsyncEntitlementsResource, EntitlementsResource
+from .resources.plans import AsyncPlansResource, PlansResource
+from .resources.subscriptions import AsyncSubscriptionsResource, SubscriptionsResource
+from .resources.usage import AsyncUsageResource, UsageResource
+
+DEFAULT_BASE_URL = "https://api.meter-flow.com/api/v1"
+DEFAULT_TIMEOUT_SECONDS = 30.0
+DEFAULT_RETRIES = 3
+KEY_PREFIXES = ("mf_live_", "mf_test_")
+
+
+@dataclass(frozen=True)
+class ClientOptions:
+    """The resolved configuration — what the Node SDK exposes as ``client.options``."""
+
+    api_key: str
+    base_url: str
+    timeout: float
+    retries: int
+
+
+class _BaseClient:
+    def __init__(self, api_key: str, base_url: str | None, timeout: float | None, retries: int | None) -> None:
+        if not api_key.startswith(KEY_PREFIXES):
+            raise ValueError("api_key must start with mf_live_ or mf_test_")
+        self.options = ClientOptions(
+            api_key=api_key,
+            base_url=(base_url or DEFAULT_BASE_URL).rstrip("/") + "/",
+            timeout=DEFAULT_TIMEOUT_SECONDS if timeout is None else timeout,
+            retries=DEFAULT_RETRIES if retries is None else retries,
+        )
+        self._retry = RetryPolicy(retries=self.options.retries)
+
+    def _kwargs(self, spec: RequestSpec) -> dict[str, Any]:
+        return request_kwargs(self.options.api_key, spec)
+
+
+class MeterFlow(_BaseClient):
+    """Synchronous client.
+
+    ``transport`` injects an ``httpx`` transport (tests, proxies) — the Python counterpart of the
+    Node SDK's ``fetch`` option. Use it as a context manager or call ``close()`` to release connections.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        retries: int | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        super().__init__(api_key, base_url, timeout, retries)
+        self._http = httpx.Client(base_url=self.options.base_url, timeout=self.options.timeout, transport=transport)
+        self.credits = CreditsResource(self)
+        self.usage = UsageResource(self)
+        self.subscriptions = SubscriptionsResource(self)
+        self.plans = PlansResource(self)
+        self.entitlements = EntitlementsResource(self)
+
+    def request(self, spec: RequestSpec) -> Any:
+        """Internal — used by resource classes; not part of the public API."""
+        for attempt in count():
+            try:
+                response = self._http.request(spec.method, spec.path, **self._kwargs(spec))
+                if response.is_error:
+                    raise map_response_error(response)
+                return decode_response(response)
+            except Exception as error:
+                delay = self._retry.delay_before_retry(attempt, error)
+                if delay is None:
+                    raise
+                _sleep(delay)
+        raise AssertionError("unreachable")  # pragma: no cover — `count()` never ends
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> MeterFlow:
+        return self
+
+    def __exit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None) -> None:
+        self.close()
+
+
+class AsyncMeterFlow(_BaseClient):
+    """Asynchronous client — identical surface, every method awaitable. ``async with`` or ``aclose()``."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        retries: int | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        super().__init__(api_key, base_url, timeout, retries)
+        self._http = httpx.AsyncClient(base_url=self.options.base_url, timeout=self.options.timeout, transport=transport)
+        self.credits = AsyncCreditsResource(self)
+        self.usage = AsyncUsageResource(self)
+        self.subscriptions = AsyncSubscriptionsResource(self)
+        self.plans = AsyncPlansResource(self)
+        self.entitlements = AsyncEntitlementsResource(self)
+
+    async def request(self, spec: RequestSpec) -> Any:
+        """Internal — used by resource classes; not part of the public API."""
+        for attempt in count():
+            try:
+                response = await self._http.request(spec.method, spec.path, **self._kwargs(spec))
+                if response.is_error:
+                    raise map_response_error(response)
+                return decode_response(response)
+            except Exception as error:
+                delay = self._retry.delay_before_retry(attempt, error)
+                if delay is None:
+                    raise
+                await _async_sleep(delay)
+        raise AssertionError("unreachable")  # pragma: no cover — `count()` never ends
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncMeterFlow:
+        return self
+
+    async def __aexit__(self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None) -> None:
+        await self.aclose()

meterflow/errors.py

@@ -0,0 +1,98 @@
+"""Typed error hierarchy — one class per HTTP outcome, mirroring the Node SDK one-to-one.
+
+Every error carries the API's ``X-Request-ID`` (``request_id``) so a support ticket can point at the
+exact request, plus ``status_code``, ``error_type`` and ``retryable`` for structured logging.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class ValidationFieldError(TypedDict):
+    """One field the API rejected, as returned in a 422's ``error.fields``."""
+
+    field: str
+    message: str
+
+
+class MeterFlowError(Exception):
+    def __init__(
+        self,
+        message: str,
+        error_type: str = "request_error",
+        *,
+        retryable: bool = False,
+        request_id: str | None = None,
+        status_code: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.error_type = error_type
+        self.retryable = retryable
+        self.request_id = request_id
+        self.status_code = status_code
+
+    def __str__(self) -> str:
+        return self.message
+
+
+class AuthError(MeterFlowError):
+    """401 / 403 — the key is missing, invalid, revoked or not allowed to do this."""
+
+    def __init__(self, message: str, *, request_id: str | None = None, status_code: int = 401) -> None:
+        super().__init__(message, "auth_error", retryable=False, request_id=request_id, status_code=status_code)
+
+
+class NotFoundError(MeterFlowError):
+    """404 — no such customer, plan, subscription… or an unknown feature key (a typo, not a plan)."""
+
+    def __init__(self, message: str, *, request_id: str | None = None) -> None:
+        super().__init__(message, "not_found", retryable=False, request_id=request_id, status_code=404)
+
+
+class InsufficientCreditsError(MeterFlowError):
+    """402 — a deduction the balance cannot cover. A business outcome, not a failure: prompt a top-up."""
+
+    def __init__(self, message: str, *, request_id: str | None = None) -> None:
+        super().__init__(message, "insufficient_credits", retryable=False, request_id=request_id, status_code=402)
+
+
+class ConflictError(MeterFlowError):
+    """409 — the write clashes with current state (e.g. the project is deactivated)."""
+
+    def __init__(self, message: str, *, request_id: str | None = None) -> None:
+        super().__init__(message, "conflict", retryable=False, request_id=request_id, status_code=409)
+
+
+class ValidationError(MeterFlowError):
+    """422 — the API rejected the payload. ``fields`` holds the per-field detail (empty when none was sent)."""
+
+    def __init__(self, message: str, *, request_id: str | None = None, fields: list[ValidationFieldError] | None = None) -> None:
+        super().__init__(message, "validation_error", retryable=False, request_id=request_id, status_code=422)
+        self.fields: list[ValidationFieldError] = list(fields or [])
+
+
+class PayloadTooLargeError(MeterFlowError):
+    """413 — well-formed but too big; today only ``usage.record_batch`` above ``MAX_BATCH_EVENTS``.
+
+    Never retried: the same payload would be refused again. Split it at the call site.
+    """
+
+    def __init__(self, message: str, *, request_id: str | None = None) -> None:
+        super().__init__(message, "payload_too_large", retryable=False, request_id=request_id, status_code=413)
+
+
+class RateLimitError(MeterFlowError):
+    """429 — retried automatically after the server's ``Retry-After`` (seconds, exposed as ``retry_after``)."""
+
+    def __init__(self, message: str, *, retry_after: int | None = None, request_id: str | None = None) -> None:
+        super().__init__(message, "rate_limit", retryable=True, request_id=request_id, status_code=429)
+        self.retry_after = retry_after
+
+
+class ServerError(MeterFlowError):
+    """5xx — MeterFlow's side; retried automatically with backoff."""
+
+    def __init__(self, message: str, *, request_id: str | None = None, status_code: int = 500) -> None:
+        super().__init__(message, "server_error", retryable=True, request_id=request_id, status_code=status_code)

meterflow/resources/__init__.py

@@ -0,0 +1 @@
+"""The five SDK-facing resources, each in a sync and an async flavour sharing one set of request specs."""

meterflow/resources/credits.py

@@ -0,0 +1,77 @@
+"""Credits — an append-only ledger per customer: grant up, deduct down, never edited in place."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .._http import RequestSpec, encode_path_segment
+from ..types import CreditBalanceResponse, CreditDeductRequest, CreditGrantRequest, CreditTransactionResponse
+
+if TYPE_CHECKING:
+    from ..client import AsyncMeterFlow, MeterFlow
+
+
+def grant_spec(body: CreditGrantRequest, idempotency_key: str | None) -> RequestSpec:
+    return RequestSpec("POST", "credits/grant", body=body, idempotency_key=idempotency_key)
+
+
+def deduct_spec(body: CreditDeductRequest, idempotency_key: str | None) -> RequestSpec:
+    return RequestSpec("POST", "credits/deduct", body=body, idempotency_key=idempotency_key)
+
+
+def balance_spec(customer_id: str) -> RequestSpec:
+    return RequestSpec("GET", f"credits/{encode_path_segment(customer_id)}/balance")
+
+
+def transactions_spec(customer_id: str) -> RequestSpec:
+    return RequestSpec("GET", f"credits/{encode_path_segment(customer_id)}/transactions")
+
+
+class CreditsResource:
+    def __init__(self, client: MeterFlow) -> None:
+        self._client = client
+
+    def grant(self, body: CreditGrantRequest, *, idempotency_key: str | None = None) -> CreditTransactionResponse:
+        """Add credits (plan renewals, top-ups, goodwill). Returns the ledger line."""
+        result: CreditTransactionResponse = self._client.request(grant_spec(body, idempotency_key))
+        return result
+
+    def deduct(self, body: CreditDeductRequest, *, idempotency_key: str | None = None) -> CreditTransactionResponse:
+        """Remove credits. Raises ``InsufficientCreditsError`` (402) rather than take the customer below zero."""
+        result: CreditTransactionResponse = self._client.request(deduct_spec(body, idempotency_key))
+        return result
+
+    def balance(self, customer_id: str) -> CreditBalanceResponse:
+        """The customer's current position — amounts are decimal strings."""
+        result: CreditBalanceResponse = self._client.request(balance_spec(customer_id))
+        return result
+
+    def transactions(self, customer_id: str) -> list[CreditTransactionResponse]:
+        """The full history, newest first."""
+        result: list[CreditTransactionResponse] = self._client.request(transactions_spec(customer_id))
+        return result
+
+
+class AsyncCreditsResource:
+    def __init__(self, client: AsyncMeterFlow) -> None:
+        self._client = client
+
+    async def grant(self, body: CreditGrantRequest, *, idempotency_key: str | None = None) -> CreditTransactionResponse:
+        """Add credits (plan renewals, top-ups, goodwill). Returns the ledger line."""
+        result: CreditTransactionResponse = await self._client.request(grant_spec(body, idempotency_key))
+        return result
+
+    async def deduct(self, body: CreditDeductRequest, *, idempotency_key: str | None = None) -> CreditTransactionResponse:
+        """Remove credits. Raises ``InsufficientCreditsError`` (402) rather than take the customer below zero."""
+        result: CreditTransactionResponse = await self._client.request(deduct_spec(body, idempotency_key))
+        return result
+
+    async def balance(self, customer_id: str) -> CreditBalanceResponse:
+        """The customer's current position — amounts are decimal strings."""
+        result: CreditBalanceResponse = await self._client.request(balance_spec(customer_id))
+        return result
+
+    async def transactions(self, customer_id: str) -> list[CreditTransactionResponse]:
+        """The full history, newest first."""
+        result: list[CreditTransactionResponse] = await self._client.request(transactions_spec(customer_id))
+        return result

meterflow/resources/entitlements.py

@@ -0,0 +1,60 @@
+"""Entitlements — ask BEFORE doing the work.
+
+``check()`` is where a hard limit says no; recording usage afterwards never blocks, so an app that
+skips this call gets no enforcement at all — only an honest ledger.
+
+``allowed: False`` is a normal answer, not an error: the call returns and ``reason`` says why
+(``no_subscription``, ``not_in_plan``, ``hard_limit_reached``, ``insufficient_credits``). A feature
+key the project does not know at all is a 404 → ``NotFoundError``, because that is a typo, not a plan.
+
+Both calls return ``Cache-Control: private, max-age=15`` — cache per customer for a few seconds on
+hot paths rather than calling on every request.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .._http import RequestSpec, encode_path_segment
+from ..types import EntitlementResponse, EntitlementsResponse
+
+if TYPE_CHECKING:
+    from ..client import AsyncMeterFlow, MeterFlow
+
+
+def get_spec(customer_id: str) -> RequestSpec:
+    return RequestSpec("GET", f"entitlements/{encode_path_segment(customer_id)}")
+
+
+def check_spec(customer_id: str, feature: str, quantity: int | None) -> RequestSpec:
+    return RequestSpec("GET", f"entitlements/{encode_path_segment(customer_id)}/check", query={"feature": feature, "quantity": quantity})
+
+
+class EntitlementsResource:
+    def __init__(self, client: MeterFlow) -> None:
+        self._client = client
+
+    def get(self, customer_id: str) -> EntitlementsResponse:
+        """Every feature on the customer's plan, with this period's usage. Empty ``entitlements`` without a subscription."""
+        result: EntitlementsResponse = self._client.request(get_spec(customer_id))
+        return result
+
+    def check(self, customer_id: str, feature: str, *, quantity: int | None = None) -> EntitlementResponse:
+        """May this customer use ``feature`` (``quantity`` more units of it — "may they do 5 more?") right now?"""
+        result: EntitlementResponse = self._client.request(check_spec(customer_id, feature, quantity))
+        return result
+
+
+class AsyncEntitlementsResource:
+    def __init__(self, client: AsyncMeterFlow) -> None:
+        self._client = client
+
+    async def get(self, customer_id: str) -> EntitlementsResponse:
+        """Every feature on the customer's plan, with this period's usage. Empty ``entitlements`` without a subscription."""
+        result: EntitlementsResponse = await self._client.request(get_spec(customer_id))
+        return result
+
+    async def check(self, customer_id: str, feature: str, *, quantity: int | None = None) -> EntitlementResponse:
+        """May this customer use ``feature`` (``quantity`` more units of it — "may they do 5 more?") right now?"""
+        result: EntitlementResponse = await self._client.request(check_spec(customer_id, feature, quantity))
+        return result