meterbase 0.1.0__py3-none-any.whl

meterbase/_async/resources/__init__.py

@@ -0,0 +1,16 @@
+from .customer_allowances import AsyncCustomerAllowances
+from .customer_periods import AsyncCustomerPeriods
+from .customer_plan import AsyncCustomerPlan
+from .customers import AsyncCustomers
+from .meters import AsyncMeters
+from .plans import AsyncPlanAllowances, AsyncPlans
+
+__all__ = [
+    "AsyncCustomerAllowances",
+    "AsyncCustomerPeriods",
+    "AsyncCustomerPlan",
+    "AsyncCustomers",
+    "AsyncMeters",
+    "AsyncPlanAllowances",
+    "AsyncPlans",
+]

meterbase/_async/resources/customer_allowances.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from ..._http import segment
+from ..._models import ListResult, list_of
+from ..._not_given import NOT_GIVEN, NotGiven
+from ...types import Allowance, AllowanceSource
+from .._transport import AsyncRequester
+
+
+class AsyncCustomerAllowances:
+    """
+    Capacity handed to one customer on top of their plan. A grant with
+    `source="plan"` is the engine's own, minted when a plan is assigned, and
+    cannot be created here.
+    """
+
+    def __init__(self, api: AsyncRequester) -> None:
+        self._api = api
+
+    async def grant(
+        self,
+        customer_id: str,
+        *,
+        meter_id: str,
+        source: AllowanceSource,
+        amount: int | NotGiven = NOT_GIVEN,
+        no_cap: bool | NotGiven = NOT_GIVEN,
+        metadata: Mapping[str, Any] | NotGiven = NOT_GIVEN,
+        effective_at: str | NotGiven = NOT_GIVEN,
+        expires_at: str | NotGiven = NOT_GIVEN,
+    ) -> Allowance:
+        """
+        Give exactly one of `amount` or `no_cap`. Unlike a plan allowance, a
+        grant of 0 is refused: a grant that gives nothing is a no-op, not a
+        state, so `amount` is at least 1.
+
+        `source` is required: the engine will not guess why capacity was handed
+        out. `effective_at` defaults to now; dated ahead, the grant is inert
+        until then.
+        """
+        return await self._api.request(
+            "POST",
+            f"/v1/customers/{segment(customer_id)}/allowances",
+            Allowance,
+            body={
+                "meter_id": meter_id,
+                "amount": amount,
+                "no_cap": no_cap,
+                "source": source,
+                "metadata": metadata,
+                "effective_at": effective_at,
+                "expires_at": expires_at,
+            },
+        )
+
+    async def list(
+        self,
+        customer_id: str,
+        *,
+        meter_id: str | NotGiven = NOT_GIVEN,
+        include_closed: bool | NotGiven = NOT_GIVEN,
+    ) -> ListResult[Allowance]:
+        """Open grants only, unless `include_closed`: revoked, expired and
+        exhausted grants as well."""
+        return await self._api.request(
+            "GET",
+            f"/v1/customers/{segment(customer_id)}/allowances",
+            list_of(Allowance),
+            query={"meter_id": meter_id, "include_closed": include_closed},
+        )
+
+    async def retrieve(self, customer_id: str, allowance_id: str) -> Allowance:
+        return await self._api.request(
+            "GET",
+            f"/v1/customers/{segment(customer_id)}/allowances/{segment(allowance_id)}",
+            Allowance,
+        )
+
+    async def revoke(self, customer_id: str, allowance_id: str) -> Allowance:
+        """Withdraws what is left without erasing what was consumed.
+        Idempotent."""
+        return await self._api.request(
+            "DELETE",
+            f"/v1/customers/{segment(customer_id)}/allowances/{segment(allowance_id)}",
+            Allowance,
+        )

meterbase/_async/resources/customer_periods.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from ..._http import segment
+from ..._not_given import NOT_GIVEN, NotGiven
+from ...errors import NotFoundError
+from ...types import ClosedPeriod
+from .._transport import AsyncRequester
+
+
+class AsyncCustomerPeriods:
+    """A customer's ended periods, exact from the engine's counters: the
+    figures to bill from."""
+
+    def __init__(self, api: AsyncRequester) -> None:
+        self._api = api
+
+    async def last(
+        self, id: str, *, before: str | NotGiven = NOT_GIVEN
+    ) -> ClosedPeriod | None:
+        """
+        The newest period that has ended, or that ended at or before `before`;
+        `None` when there is none. Walk back by passing each period's `from_`
+        as `before`, exactly as it came. Raises `PeriodSettlingError` for a
+        minute after a period ends.
+
+        `before` is an RFC 3339 instant; omitted, now. It is a string rather
+        than a `datetime` so that a period's `from_` goes back verbatim: the
+        engine's carry microseconds, and a `before` short of one names the
+        period before it.
+        """
+        try:
+            return await self._api.request(
+                "GET",
+                f"/v1/customers/{segment(id)}/periods/last",
+                ClosedPeriod,
+                query={"before": before},
+            )
+        except NotFoundError as error:
+            if error.code in ("no_plan_assigned", "no_previous_period"):
+                return None
+            raise

meterbase/_async/resources/customer_plan.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from ..._http import segment
+from ..._models import ListResult, list_of
+from ..._not_given import NOT_GIVEN, NotGiven
+from ..._time import parse_instant
+from ...errors import NotFoundError
+from ...types import ApplyMode, Assignment, Reconciliation
+from .._io import both
+from .._transport import AsyncRequester
+
+
+class AsyncCustomerPlan:
+    """
+    Which plan a customer holds. The history is append-only: there is no patch
+    and no delete, and moving a customer to a different plan is the same call
+    as their first.
+
+    `assign` is that call, mirroring the wire. The rest name the four moves a
+    caller actually makes — later, now, now-and-start-over, and never mind — so
+    that picking one does not mean knowing what `effective` and
+    `reconciliation` do to a half-used period. They name the plan `plan`
+    rather than `plan_id`: they sit a layer above the wire, where `assign`
+    still mirrors it field for field.
+    """
+
+    def __init__(self, api: AsyncRequester) -> None:
+        self._api = api
+
+    async def assign(
+        self,
+        customer_id: str,
+        *,
+        plan_id: str,
+        effective: ApplyMode | NotGiven = NOT_GIVEN,
+        reconciliation: Reconciliation | NotGiven = NOT_GIVEN,
+        cycle_anchor: str | NotGiven = NOT_GIVEN,
+    ) -> Assignment:
+        """
+        Put a customer on a plan. This is the wire call, and the only one that
+        takes `cycle_anchor` — a first assignment's one chance to put their
+        periods on a date they already have.
+
+        Returns the instruction as recorded, which is not always as asked: a
+        first plan is recorded `immediate` whatever `effective` said.
+
+        `effective` defaults to `next_cycle` on a change, and is forced to
+        `immediate` on a customer's first plan: there is no period to wait
+        out. `reconciliation` is `immediate` only; the engine refuses it beside
+        `next_cycle`. `cycle_anchor` defaults to the instant the plan lands,
+        and is refused beside `reconciliation="reset"`, which anchors at the
+        change instant itself.
+        """
+        return await self._api.request(
+            "POST",
+            f"/v1/customers/{segment(customer_id)}/plan",
+            Assignment,
+            body={
+                "plan_id": plan_id,
+                "effective": effective,
+                "reconciliation": reconciliation,
+                "cycle_anchor": cycle_anchor,
+            },
+        )
+
+    async def change(
+        self,
+        customer_id: str,
+        *,
+        plan: str,
+        effective: ApplyMode | NotGiven = NOT_GIVEN,
+        reconciliation: Reconciliation | NotGiven = NOT_GIVEN,
+    ) -> Assignment:
+        """
+        Move a customer to a different plan, named by its Meterbase id, with
+        both knobs in the open. `effective` defaults to `next_cycle`;
+        `reconciliation` applies only to an `immediate` change and defaults to
+        `none`.
+
+        Reach for `change_at_next_cycle`, `change_now` or `restart` when one of
+        them says what you mean — this is the form to fall back to when the two
+        are chosen at runtime.
+        """
+        return await self.assign(
+            customer_id,
+            plan_id=plan,
+            effective=effective,
+            reconciliation=reconciliation,
+        )
+
+    async def change_at_next_cycle(self, customer_id: str, *, plan: str) -> Assignment:
+        """
+        Schedule the move for the end of the period they are in: they keep the
+        plan they are paying for until it runs out, and the new one starts at
+        their next boundary. Nothing is pro-rated, because nothing is split.
+
+        Two plans on different cycles share no boundary, and this answers
+        `CycleChangeRequiresResetError` — use `restart` for that move.
+        """
+        return await self.change(customer_id, plan=plan, effective="next_cycle")
+
+    async def change_now(
+        self,
+        customer_id: str,
+        *,
+        plan: str,
+        reconciliation: Reconciliation | NotGiven = NOT_GIVEN,
+    ) -> Assignment:
+        """
+        Move them now, inside the period already running. Their renewal day
+        does not move; what changes is this period's cap, and `reconciliation`
+        says how:
+
+        - `none` (the default) — the new plan's amount governs the whole
+          period. Usage already spent still counts, so a downgrade can deny
+          until the period ends.
+        - `prorate` — each plan's amount weighted by the fraction of the period
+          it was held for. Refused between plans on different cycles, which
+          share no period to weight.
+
+        To have the period itself start over instead, use `restart`.
+        """
+        return await self.change(
+            customer_id,
+            plan=plan,
+            effective="immediate",
+            reconciliation=reconciliation,
+        )
+
+    async def restart(self, customer_id: str, *, plan: str) -> Assignment:
+        """
+        Move them now and start a fresh period today: the period they were in
+        closes where the change lands, keeping the usage it had, and the new
+        plan's full amount opens immediately.
+
+        This moves the customer's anchor, so their renewal day becomes today.
+        It is the move for a customer starting over — a new contract, a
+        re-signup — and the only one that can take a customer between plans
+        whose cycles differ.
+        """
+        return await self.change(
+            customer_id,
+            plan=plan,
+            effective="immediate",
+            reconciliation="reset",
+        )
+
+    async def cancel_scheduled_change(self, customer_id: str) -> Assignment | None:
+        """
+        Call off a change that has not landed yet, leaving the customer on the
+        plan they hold. Naming the plan already held is what supersedes a
+        pending instruction, so this reads the plan in force and names it back.
+
+        Returns the assignment still in force, or `None` for a customer holding
+        no plan — who can have nothing pending, since a first assignment
+        always lands at once.
+        """
+        current = await self.retrieve(customer_id)
+        if current is None:
+            return None
+
+        return await self.assign(customer_id, plan_id=current.plan_id)
+
+    async def retrieve(self, customer_id: str) -> Assignment | None:
+        """
+        The plan in force now, which is not always the newest instruction: a
+        change dated ahead does not govern yet.
+
+        `None` when the customer holds no plan. That is a default deny rather
+        than a failure — they are entitled to nothing — so it is an answer here
+        and not a raised `NotFoundError`. A customer who does not exist at all
+        still raises one.
+        """
+        try:
+            return await self._api.request(
+                "GET", f"/v1/customers/{segment(customer_id)}/plan", Assignment
+            )
+        except NotFoundError as error:
+            if error.code == "no_plan_assigned":
+                return None
+            raise
+
+    async def pending(self, customer_id: str) -> Assignment | None:
+        """
+        The change waiting to land, or `None` when none is. At most one is ever
+        live: a newer instruction supersedes the one before it.
+
+        Read against the assignment in force rather than against the local
+        clock, so a change landing seconds from now is not reported as already
+        governing.
+        """
+        current, history = await both(
+            self.retrieve(customer_id), self.history(customer_id)
+        )
+
+        if current is None:
+            in_force = datetime.min.replace(tzinfo=timezone.utc)
+        else:
+            parsed = parse_instant(current.effective_at)
+            if parsed is None:
+                return None
+            in_force = parsed
+
+        return next(
+            (
+                row
+                for row in history.data
+                if row.superseded_at is None
+                and _lands_after(row.effective_at, in_force)
+            ),
+            None,
+        )
+
+    async def history(self, customer_id: str) -> ListResult[Assignment]:
+        """Every instruction, superseded ones included: it is the whole
+        trail."""
+        return await self._api.request(
+            "GET",
+            f"/v1/customers/{segment(customer_id)}/plan/history",
+            list_of(Assignment),
+        )
+
+
+def _lands_after(effective_at: str, in_force: datetime) -> bool:
+    at = parse_instant(effective_at)
+    return at is not None and at > in_force

meterbase/_async/resources/customers.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, overload
+
+from ..._http import segment
+from ..._models import ListResult, list_of
+from ..._not_given import NOT_GIVEN, NotGiven
+from ...errors import NotFoundError
+from ...types import (
+    Customer,
+    CustomerEntitlement,
+    CustomerUsage,
+    CustomerWithPlan,
+    UsagePeriod,
+)
+from .._transport import AsyncRequester
+from .customer_allowances import AsyncCustomerAllowances
+from .customer_periods import AsyncCustomerPeriods
+from .customer_plan import AsyncCustomerPlan
+
+
+class AsyncCustomers:
+    plan: AsyncCustomerPlan
+    """The plan they hold, and the trail of instructions that got them
+    there."""
+    allowances: AsyncCustomerAllowances
+    """Grants, which sit on top of whatever the plan gives."""
+    periods: AsyncCustomerPeriods
+    """Periods that have ended, with the figures to bill them from."""
+
+    def __init__(self, api: AsyncRequester) -> None:
+        self._api = api
+        self.plan = AsyncCustomerPlan(api)
+        self.allowances = AsyncCustomerAllowances(api)
+        self.periods = AsyncCustomerPeriods(api)
+
+    async def create(
+        self,
+        *,
+        external_id: str,
+        name: str | NotGiven = NOT_GIVEN,
+        metadata: Mapping[str, Any] | NotGiven = NOT_GIVEN,
+        thresholds: Sequence[int] | NotGiven = NOT_GIVEN,
+    ) -> Customer:
+        """
+        `thresholds` is whole percents, 1–1000, at most 32 of them; a mark over
+        100 is an overage alert. Omitted, the customer inherits.
+        """
+        return await self._api.request(
+            "POST",
+            "/v1/customers",
+            Customer,
+            body={
+                "external_id": external_id,
+                "name": name,
+                "metadata": metadata,
+                "thresholds": thresholds,
+            },
+        )
+
+    async def list(
+        self, *, include_deleted: bool | NotGiven = NOT_GIVEN
+    ) -> ListResult[Customer]:
+        """Lean: a listing does not embed the plan. Read one customer for
+        that."""
+        return await self._api.request(
+            "GET",
+            "/v1/customers",
+            list_of(Customer),
+            query={"include_deleted": include_deleted},
+        )
+
+    async def retrieve(self, id: str) -> CustomerWithPlan:
+        """
+        One customer, with the plan they hold. `plan` is the one in force now
+        and `pending_plan` the change waiting to land, each `None` when there
+        is none — so knowing what a customer is on costs no second request.
+        """
+        return await self._api.request(
+            "GET", f"/v1/customers/{segment(id)}", CustomerWithPlan
+        )
+
+    async def retrieve_by_external_id(
+        self, external_id: str
+    ) -> CustomerWithPlan | None:
+        """
+        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.
+        """
+        found = await self._api.request(
+            "GET",
+            "/v1/customers",
+            list_of(CustomerWithPlan),
+            query={"external_id": external_id},
+        )
+        return found.data[0] if found.data else None
+
+    async def entitlement(self, id: str) -> CustomerEntitlement | None:
+        """`None` for a customer holding no plan, as `plan.retrieve` answers."""
+        try:
+            return await self._api.request(
+                "GET",
+                f"/v1/customers/{segment(id)}/entitlement",
+                CustomerEntitlement,
+            )
+        except NotFoundError as error:
+            if error.code == "no_plan_assigned":
+                return None
+            raise
+
+    @overload
+    async def usage(self, id: str, *, days: int) -> CustomerUsage: ...
+
+    @overload
+    async def usage(self, id: str, *, period: UsagePeriod) -> CustomerUsage | None: ...
+
+    async def usage(
+        self,
+        id: str,
+        *,
+        days: int | NotGiven = NOT_GIVEN,
+        period: UsagePeriod | NotGiven = NOT_GIVEN,
+    ) -> CustomerUsage | None:
+        """
+        Usage per UTC day: `days` is 1–90 of them ending today, or `period` is
+        `"current"` or `"last"`. A period the customer never had, holding no
+        plan now or none before this period, is `None`.
+        """
+        try:
+            return await self._api.request(
+                "GET",
+                f"/v1/customers/{segment(id)}/usage",
+                CustomerUsage,
+                query={"days": days, "period": period},
+            )
+        except NotFoundError as error:
+            if error.code in ("no_plan_assigned", "no_previous_period"):
+                return None
+            raise
+
+    async def update(
+        self,
+        id: str,
+        *,
+        external_id: str | NotGiven = NOT_GIVEN,
+        name: str | NotGiven = NOT_GIVEN,
+        metadata: Mapping[str, Any] | NotGiven = NOT_GIVEN,
+        thresholds: Sequence[int] | NotGiven | None = NOT_GIVEN,
+    ) -> Customer:
+        """
+        An omitted field is left alone. `external_id` cannot be cleared, and
+        `metadata` is replaced wholesale rather than merged.
+
+        `thresholds` reads `None` as a value, not as silence: omit it to keep
+        the stored list, pass `None` to go back to inheriting the meter's or
+        the workspace's, pass `[]` to turn alerts off for this customer alone.
+        """
+        return await self._api.request(
+            "PATCH",
+            f"/v1/customers/{segment(id)}",
+            Customer,
+            body={
+                "external_id": external_id,
+                "name": name,
+                "metadata": metadata,
+                "thresholds": thresholds,
+            },
+        )
+
+    async def delete(self, id: str) -> Customer:
+        """Soft delete: usage and assignments keep referencing the customer."""
+        return await self._api.request(
+            "DELETE", f"/v1/customers/{segment(id)}", Customer
+        )

meterbase/_async/resources/meters.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from ..._http import segment
+from ..._models import ListResult, list_of
+from ..._not_given import NOT_GIVEN, NotGiven
+from ...types import Meter, MeterUsageHistory
+from .._transport import AsyncRequester
+
+
+class AsyncMeters:
+    def __init__(self, api: AsyncRequester) -> None:
+        self._api = api
+
+    async def create(
+        self,
+        *,
+        key: str,
+        name: str,
+        description: str | NotGiven = NOT_GIVEN,
+        unit: str | NotGiven = NOT_GIVEN,
+        value: str | NotGiven = NOT_GIVEN,
+        thresholds: Sequence[int] | NotGiven = NOT_GIVEN,
+    ) -> Meter:
+        """
+        `thresholds` is whole percents, 1–1000, at most 32 of them; a mark over
+        100 is an overage alert. Omitted, the meter inherits the workspace's.
+        """
+        return await self._api.request(
+            "POST",
+            "/v1/meters",
+            Meter,
+            body={
+                "key": key,
+                "name": name,
+                "description": description,
+                "unit": unit,
+                "value": value,
+                "thresholds": thresholds,
+            },
+        )
+
+    async def list(
+        self, *, include_archived: bool | NotGiven = NOT_GIVEN
+    ) -> ListResult[Meter]:
+        return await self._api.request(
+            "GET",
+            "/v1/meters",
+            list_of(Meter),
+            query={"include_archived": include_archived},
+        )
+
+    async def retrieve(self, id: str) -> Meter:
+        return await self._api.request("GET", f"/v1/meters/{segment(id)}", Meter)
+
+    async def update(
+        self,
+        id: str,
+        *,
+        key: str | NotGiven = NOT_GIVEN,
+        name: str | NotGiven = NOT_GIVEN,
+        description: str | NotGiven = NOT_GIVEN,
+        unit: str | NotGiven = NOT_GIVEN,
+        value: str | NotGiven = NOT_GIVEN,
+        thresholds: Sequence[int] | NotGiven | None = NOT_GIVEN,
+    ) -> Meter:
+        """
+        An omitted field is left alone; `""` clears an optional one.
+
+        `thresholds` is the exception on both counts: `None` is a value there,
+        not silence. Omit it to keep the stored list, pass `None` to inherit
+        the workspace's again, pass `[]` to turn alerts off for this meter.
+        """
+        return await self._api.request(
+            "PATCH",
+            f"/v1/meters/{segment(id)}",
+            Meter,
+            body={
+                "key": key,
+                "name": name,
+                "description": description,
+                "unit": unit,
+                "value": value,
+                "thresholds": thresholds,
+            },
+        )
+
+    async def usage(self, id: str, *, days: int) -> MeterUsageHistory:
+        """Every customer's usage of the meter per UTC day: `days` is 1–90 of
+        them, ending today."""
+        return await self._api.request(
+            "GET",
+            f"/v1/meters/{segment(id)}/usage",
+            MeterUsageHistory,
+            query={"days": days},
+        )
+
+    async def archive(self, id: str) -> Meter:
+        """Soft delete: plans and usage keep referencing the meter.
+        Idempotent."""
+        return await self._api.request("DELETE", f"/v1/meters/{segment(id)}", Meter)