meterflow 0.1.0__py3-none-any.whl

meterflow/resources/plans.py

@@ -0,0 +1,49 @@
+"""Plans — read-only through the SDK: pricing is managed by humans in the dashboard."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .._http import RequestSpec, encode_path_segment
+from ..types import PlanResponse
+
+if TYPE_CHECKING:
+    from ..client import AsyncMeterFlow, MeterFlow
+
+
+def list_spec(project_id: str | None) -> RequestSpec:
+    return RequestSpec("GET", "plans", query={"project_id": project_id})
+
+
+def get_spec(plan_id: str, project_id: str | None) -> RequestSpec:
+    return RequestSpec("GET", f"plans/{encode_path_segment(plan_id)}", query={"project_id": project_id})
+
+
+class PlansResource:
+    def __init__(self, client: MeterFlow) -> None:
+        self._client = client
+
+    def list(self, *, project_id: str | None = None) -> list[PlanResponse]:
+        """The project's plans — render your pricing page from this so it can never drift from billing."""
+        result: list[PlanResponse] = self._client.request(list_spec(project_id))
+        return result
+
+    def get(self, plan_id: str, *, project_id: str | None = None) -> PlanResponse:
+        """One plan, including its per-meter limits and feature keys."""
+        result: PlanResponse = self._client.request(get_spec(plan_id, project_id))
+        return result
+
+
+class AsyncPlansResource:
+    def __init__(self, client: AsyncMeterFlow) -> None:
+        self._client = client
+
+    async def list(self, *, project_id: str | None = None) -> list[PlanResponse]:
+        """The project's plans — render your pricing page from this so it can never drift from billing."""
+        result: list[PlanResponse] = await self._client.request(list_spec(project_id))
+        return result
+
+    async def get(self, plan_id: str, *, project_id: str | None = None) -> PlanResponse:
+        """One plan, including its per-meter limits and feature keys."""
+        result: PlanResponse = await self._client.request(get_spec(plan_id, project_id))
+        return result

meterflow/resources/subscriptions.py

@@ -0,0 +1,89 @@
+"""Subscriptions — one customer on one plan from a date; renews itself."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .._http import RequestSpec, encode_path_segment
+from ..types import SubscriptionCreateRequest, SubscriptionResponse, SubscriptionUpdateRequest
+
+if TYPE_CHECKING:
+    from ..client import AsyncMeterFlow, MeterFlow
+
+
+def create_spec(body: SubscriptionCreateRequest, idempotency_key: str | None) -> RequestSpec:
+    return RequestSpec("POST", "subscriptions", body=body, idempotency_key=idempotency_key)
+
+
+def list_spec(customer_id: str | None) -> RequestSpec:
+    return RequestSpec("GET", "subscriptions", query={"customer_id": customer_id})
+
+
+def get_spec(subscription_id: str) -> RequestSpec:
+    return RequestSpec("GET", f"subscriptions/{encode_path_segment(subscription_id)}")
+
+
+def update_spec(subscription_id: str, body: SubscriptionUpdateRequest, idempotency_key: str | None) -> RequestSpec:
+    return RequestSpec("PATCH", f"subscriptions/{encode_path_segment(subscription_id)}", body=body, idempotency_key=idempotency_key)
+
+
+def delete_spec(subscription_id: str) -> RequestSpec:
+    return RequestSpec("DELETE", f"subscriptions/{encode_path_segment(subscription_id)}")
+
+
+class SubscriptionsResource:
+    def __init__(self, client: MeterFlow) -> None:
+        self._client = client
+
+    def create(self, body: SubscriptionCreateRequest, *, idempotency_key: str | None = None) -> SubscriptionResponse:
+        """Put a customer on a plan. ``status`` is ``trialing`` if the plan has trial days, else ``active``."""
+        result: SubscriptionResponse = self._client.request(create_spec(body, idempotency_key))
+        return result
+
+    def list(self, *, customer_id: str | None = None) -> list[SubscriptionResponse]:
+        """The project's subscriptions in this key's environment, optionally one customer's."""
+        result: list[SubscriptionResponse] = self._client.request(list_spec(customer_id))
+        return result
+
+    def get(self, subscription_id: str) -> SubscriptionResponse:
+        result: SubscriptionResponse = self._client.request(get_spec(subscription_id))
+        return result
+
+    def update(self, subscription_id: str, body: SubscriptionUpdateRequest, *, idempotency_key: str | None = None) -> SubscriptionResponse:
+        """Change status or metadata. Cancel with ``{"status": "canceled"}`` — the record stays for history."""
+        result: SubscriptionResponse = self._client.request(update_spec(subscription_id, body, idempotency_key))
+        return result
+
+    def delete(self, subscription_id: str) -> None:
+        """Remove the record entirely — for test data; prefer cancelling in production."""
+        self._client.request(delete_spec(subscription_id))
+
+
+class AsyncSubscriptionsResource:
+    def __init__(self, client: AsyncMeterFlow) -> None:
+        self._client = client
+
+    async def create(self, body: SubscriptionCreateRequest, *, idempotency_key: str | None = None) -> SubscriptionResponse:
+        """Put a customer on a plan. ``status`` is ``trialing`` if the plan has trial days, else ``active``."""
+        result: SubscriptionResponse = await self._client.request(create_spec(body, idempotency_key))
+        return result
+
+    async def list(self, *, customer_id: str | None = None) -> list[SubscriptionResponse]:
+        """The project's subscriptions in this key's environment, optionally one customer's."""
+        result: list[SubscriptionResponse] = await self._client.request(list_spec(customer_id))
+        return result
+
+    async def get(self, subscription_id: str) -> SubscriptionResponse:
+        result: SubscriptionResponse = await self._client.request(get_spec(subscription_id))
+        return result
+
+    async def update(
+        self, subscription_id: str, body: SubscriptionUpdateRequest, *, idempotency_key: str | None = None
+    ) -> SubscriptionResponse:
+        """Change status or metadata. Cancel with ``{"status": "canceled"}`` — the record stays for history."""
+        result: SubscriptionResponse = await self._client.request(update_spec(subscription_id, body, idempotency_key))
+        return result
+
+    async def delete(self, subscription_id: str) -> None:
+        """Remove the record entirely — for test data; prefer cancelling in production."""
+        await self._client.request(delete_spec(subscription_id))

meterflow/resources/usage.py

@@ -0,0 +1,77 @@
+"""Usage events — "this customer just did this thing, this much", matched to a meter by ``event_name``."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .._http import RequestSpec, encode_path_segment
+from ..errors import PayloadTooLargeError
+from ..types import UsageEventRequest, UsageEventResponse, UsageSummaryResponse
+
+if TYPE_CHECKING:
+    from ..client import AsyncMeterFlow, MeterFlow
+
+# The API refuses a batch above this with 413. The SDK checks it before sending so an oversized
+# batch fails instantly, offline, with the same ``PayloadTooLargeError`` — and it does NOT split
+# the batch for you: one call is one request with one idempotency key, and silently turning it
+# into N requests would leave partial success indistinguishable from failure. Chunk at the call
+# site, where you can pick a key per chunk.
+MAX_BATCH_EVENTS = 500
+
+
+def record_spec(body: UsageEventRequest, idempotency_key: str | None) -> RequestSpec:
+    return RequestSpec("POST", "usage/events", body=body, idempotency_key=idempotency_key)
+
+
+def record_batch_spec(events: list[UsageEventRequest], idempotency_key: str | None) -> RequestSpec:
+    if len(events) > MAX_BATCH_EVENTS:
+        raise PayloadTooLargeError(f"A batch may contain at most {MAX_BATCH_EVENTS} events; this one has {len(events)}. Split it.")
+    return RequestSpec("POST", "usage/events/batch", body={"events": events}, idempotency_key=idempotency_key)
+
+
+def summary_spec(customer_id: str, meter_id: str | None, from_: str | None, to: str | None) -> RequestSpec:
+    return RequestSpec("GET", f"usage/{encode_path_segment(customer_id)}", query={"meter_id": meter_id, "from_": from_, "to": to})
+
+
+class UsageResource:
+    def __init__(self, client: MeterFlow) -> None:
+        self._client = client
+
+    def record(self, body: UsageEventRequest, *, idempotency_key: str | None = None) -> UsageEventResponse:
+        """Record one event. Returns immediately (``processed: False``); totals materialise moments later."""
+        result: UsageEventResponse = self._client.request(record_spec(body, idempotency_key))
+        return result
+
+    def record_batch(self, events: list[UsageEventRequest], *, idempotency_key: str | None = None) -> list[UsageEventResponse]:
+        """Record up to ``MAX_BATCH_EVENTS`` events in one request. A larger list is refused locally, never sent."""
+        result: list[UsageEventResponse] = self._client.request(record_batch_spec(events, idempotency_key))
+        return result
+
+    def summary(
+        self, customer_id: str, *, meter_id: str | None = None, from_: str | None = None, to: str | None = None
+    ) -> UsageSummaryResponse:
+        """A customer's usage broken down by meter. ``from_`` keeps the API's trailing underscore."""
+        result: UsageSummaryResponse = self._client.request(summary_spec(customer_id, meter_id, from_, to))
+        return result
+
+
+class AsyncUsageResource:
+    def __init__(self, client: AsyncMeterFlow) -> None:
+        self._client = client
+
+    async def record(self, body: UsageEventRequest, *, idempotency_key: str | None = None) -> UsageEventResponse:
+        """Record one event. Returns immediately (``processed: False``); totals materialise moments later."""
+        result: UsageEventResponse = await self._client.request(record_spec(body, idempotency_key))
+        return result
+
+    async def record_batch(self, events: list[UsageEventRequest], *, idempotency_key: str | None = None) -> list[UsageEventResponse]:
+        """Record up to ``MAX_BATCH_EVENTS`` events in one request. A larger list is refused locally, never sent."""
+        result: list[UsageEventResponse] = await self._client.request(record_batch_spec(events, idempotency_key))
+        return result
+
+    async def summary(
+        self, customer_id: str, *, meter_id: str | None = None, from_: str | None = None, to: str | None = None
+    ) -> UsageSummaryResponse:
+        """A customer's usage broken down by meter. ``from_`` keeps the API's trailing underscore."""
+        result: UsageSummaryResponse = await self._client.request(summary_spec(customer_id, meter_id, from_, to))
+        return result

meterflow/types.py

@@ -0,0 +1,214 @@
+# GENERATED by scripts/generate_types.py from docs/openapi.json — DO NOT EDIT.
+# OpenAPI version: 0.1.0. Re-run the script after the contract changes; CI fails on drift.
+"""Request and response shapes of the SDK-facing API, as TypedDicts (plain dicts at runtime)."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+EntitlementReason = Literal["no_subscription", "not_in_plan", "hard_limit_reached", "soft_limit_exceeded", "insufficient_credits"]
+
+FeatureType = Literal["boolean", "metered"]
+
+SubscriptionStatus = Literal["active", "trialing", "past_due", "paused", "canceled", "expired"]
+
+
+class CreditBalanceResponse(TypedDict):
+    id: str
+    project_id: str
+    customer_external_id: str
+    balance: str
+    total_granted: str
+    total_consumed: str
+    version: int
+    created_at: str
+    updated_at: str
+
+
+class _CreditDeductRequestRequired(TypedDict):
+    customer_external_id: str
+    amount: float | str
+
+
+class CreditDeductRequest(_CreditDeductRequestRequired, total=False):
+    description: str | None
+    idempotency_key: str | None
+    metadata: dict[str, Any]
+
+
+class _CreditGrantRequestRequired(TypedDict):
+    customer_external_id: str
+    amount: float | str
+
+
+class CreditGrantRequest(_CreditGrantRequestRequired, total=False):
+    description: str | None
+    idempotency_key: str | None
+    metadata: dict[str, Any]
+
+
+class CreditTransactionResponse(TypedDict):
+    id: str
+    project_id: str
+    customer_external_id: str
+    transaction_type: str
+    amount: str
+    balance_before: str
+    balance_after: str
+    description: str | None
+    idempotency_key: str | None
+    metadata_: dict[str, Any]
+    created_at: str
+
+
+class _EntitlementResponseRequired(TypedDict):
+    feature: str
+    feature_type: FeatureType
+    allowed: bool
+
+
+class EntitlementResponse(_EntitlementResponseRequired, total=False):
+    reason: EntitlementReason | None
+    limit_type: str | None
+    included: int | None
+    used: str | None
+    remaining: str | None
+    period_start: str | None
+    period_end: str | None
+
+
+class EntitlementsResponse(TypedDict):
+    customer_id: str
+    environment: str
+    subscription_id: str | None
+    plan_id: str | None
+    period_end: str | None
+    entitlements: list[EntitlementResponse]
+
+
+class PlanMeterLimitResponse(TypedDict):
+    id: str
+    plan_id: str
+    meter_id: str
+    included_units: int | None
+    overage_rate: str | None
+    limit_type: str
+
+
+class PlanResponse(TypedDict):
+    id: str
+    project_id: str
+    name: str
+    slug: str
+    description: str | None
+    billing_period: str
+    price: str
+    currency: str
+    trial_days: int
+    is_active: bool
+    is_public: bool
+    metadata_: dict[str, Any]
+    meter_limits: list[PlanMeterLimitResponse]
+    features: list[str]
+    created_at: str
+    updated_at: str
+
+
+class _SubscriptionCreateRequestRequired(TypedDict):
+    plan_id: str
+    customer_external_id: str
+
+
+class SubscriptionCreateRequest(_SubscriptionCreateRequestRequired, total=False):
+    metadata: dict[str, Any]
+    idempotency_key: str | None
+
+
+class SubscriptionResponse(TypedDict):
+    id: str
+    project_id: str
+    plan_id: str
+    customer_external_id: str
+    status: str
+    current_period_start: str
+    current_period_end: str | None
+    trial_end_date: str | None
+    canceled_at: str | None
+    metadata_: dict[str, Any]
+    created_at: str
+    updated_at: str
+
+
+class SubscriptionUpdateRequest(TypedDict, total=False):
+    status: SubscriptionStatus | None
+    metadata: dict[str, Any] | None
+
+
+class UsageEventBatchRequest(TypedDict):
+    events: list[UsageEventRequest]
+
+
+class _UsageEventRequestRequired(TypedDict):
+    event_name: str
+    customer_external_id: str
+
+
+class UsageEventRequest(_UsageEventRequestRequired, total=False):
+    value: float | str
+    properties: dict[str, Any]
+    idempotency_key: str | None
+    timestamp: str | None
+
+
+class UsageEventResponse(TypedDict):
+    id: str
+    project_id: str
+    meter_id: str
+    customer_external_id: str
+    event_name: str
+    value: str
+    properties: dict[str, Any]
+    idempotency_key: str | None
+    processed: bool
+    timestamp: str
+    created_at: str
+
+
+class UsageSummaryItem(TypedDict):
+    meter_id: str
+    meter_name: str
+    event_name: str
+    aggregation_type: str
+    value: str
+    event_count: int
+
+
+class UsageSummaryResponse(TypedDict):
+    project_id: str
+    customer_external_id: str
+    from_: str | None
+    to: str | None
+    meters: list[UsageSummaryItem]
+
+
+__all__ = [
+    "CreditBalanceResponse",
+    "CreditDeductRequest",
+    "CreditGrantRequest",
+    "CreditTransactionResponse",
+    "EntitlementReason",
+    "EntitlementResponse",
+    "EntitlementsResponse",
+    "FeatureType",
+    "PlanMeterLimitResponse",
+    "PlanResponse",
+    "SubscriptionCreateRequest",
+    "SubscriptionResponse",
+    "SubscriptionStatus",
+    "SubscriptionUpdateRequest",
+    "UsageEventBatchRequest",
+    "UsageEventRequest",
+    "UsageEventResponse",
+    "UsageSummaryItem",
+    "UsageSummaryResponse",
+]

meterflow/webhook.py

@@ -0,0 +1,21 @@
+"""Webhook signature verification — HMAC-SHA256 over the raw body, hex-encoded, timing-safe.
+
+Byte-for-byte the same scheme as the Node SDK's ``verifyWebhook`` and the API's signer: a delivery
+signed by MeterFlow verifies here with the webhook's secret, and nothing else does.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+
+def verify_webhook(body: bytes | str, signature: str, secret: str) -> bool:
+    """Return ``True`` when ``signature`` (the ``X-MeterFlow-Signature`` header) matches ``body``.
+
+    Pass the **raw** request body — re-serialised JSON changes whitespace and key order and will
+    not match. Never raises on bad input: an empty, short or malformed signature is simply ``False``.
+    """
+    raw = body.encode("utf-8") if isinstance(body, str) else body
+    expected = hmac.new(secret.encode("utf-8"), raw, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, signature)