meterbase 0.1.0__py3-none-any.whl

meterbase/types.py

@@ -0,0 +1,600 @@
+"""
+Wire types, shaped exactly as the engine sends them: checkable against the API
+reference line by line, with no translation layer to drift.
+
+Each response is a `Model`, which is the engine's JSON as it arrived with a
+typed attribute for each field. Times are RFC 3339 strings, as sent: the
+engine's carry microseconds, which a round trip through anything else can
+drop.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+from ._models import ListResult, Model
+
+__all__ = [
+    "Allowance",
+    "AllowanceSource",
+    "ApplyMode",
+    "Assignment",
+    "CheckRateLimit",
+    "CheckReason",
+    "CheckResult",
+    "ClosedPeriod",
+    "ClosedPeriodMeter",
+    "Customer",
+    "CustomerEntitlement",
+    "CustomerUsage",
+    "CustomerWithPlan",
+    "DayUsage",
+    "EmbeddedPlan",
+    "EntitlementReachedEvent",
+    "EntitlementState",
+    "IncomingVersion",
+    "ListResult",
+    "Meter",
+    "MeterEntitlement",
+    "MeterUsage",
+    "MeterUsageHistory",
+    "Model",
+    "Period",
+    "Plan",
+    "PlanAllowance",
+    "PlanAllowanceKind",
+    "PlanCycle",
+    "Reconciliation",
+    "RecordedReconciliation",
+    "ReleaseResult",
+    "ReserveResponse",
+    "ThresholdCrossedEvent",
+    "ThresholdCrossing",
+    "ThresholdPlan",
+    "TrackResult",
+    "UsageEvent",
+    "UsagePeriod",
+    "Validity",
+    "ValidityParam",
+    "WebhookEvent",
+    "WhoAmI",
+]
+
+
+# Meters ---------------------------------------------------------------------
+
+
+class Meter(Model):
+    id: str
+    workspace_id: str
+    key: str
+    name: str
+    description: str
+    unit: str
+    value: str
+    thresholds: list[int] | None
+    """Usage-alert percents for this meter. `None` inherits the workspace's
+    defaults; `[]` turns alerts off for the meter. A customer's own list beats
+    this one."""
+    created_at: str
+    updated_at: str
+    archived_at: str | None
+
+
+# Customers ------------------------------------------------------------------
+
+
+class Customer(Model):
+    id: str
+    workspace_id: str
+    external_id: str
+    name: str
+    metadata: dict[str, Any]
+    thresholds: list[int] | None
+    """Usage-alert percents for this customer. `None` inherits — the meter's
+    list, then the workspace's. `[]` turns alerts off for this customer. The
+    most specific of the three, and it always wins."""
+    created_at: str
+    updated_at: str
+    deleted_at: str | None
+
+
+class EmbeddedPlan(Model):
+    """
+    A plan as a customer read embeds it: the plan itself, flattened onto the
+    assignment that named it.
+
+    `id` is the **plan's**. The assignment's own id is on
+    `customers.plan.retrieve`, which is where instructions are identified;
+    what a reader wants from an embed is which plan. `cycle` is here because
+    `anchor_at` fixes a period only alongside its stride.
+    """
+
+    id: str
+    key: str
+    name: str
+    cycle: PlanCycle
+    effective_at: str
+    """When this instruction takes effect — ahead of now on `pending_plan`."""
+    anchor_at: str
+    """What the customer's periods are measured from."""
+    effective: ApplyMode
+    reconciliation: RecordedReconciliation
+
+
+class CustomerWithPlan(Customer):
+    """
+    A single-customer read. The plan travels with the customer because a
+    caller holding one almost always goes on to ask what it is entitled to.
+
+    `plan` is the one in force now and `pending_plan` the change waiting to
+    land, each `None` when there is none — holding no plan is a default deny,
+    not a failure. `customers.list`, `create`, `update` and `delete` answer a
+    plain `Customer`: a listing does not embed, where the same read would run
+    per row for an answer most callers of a list do not want.
+    """
+
+    plan: EmbeddedPlan | None
+    pending_plan: EmbeddedPlan | None
+
+
+# Check ----------------------------------------------------------------------
+
+CheckReason = Literal["entitlement", "rate_limit"] | str
+"""
+Which gate turned the request away. `entitlement` is named ahead of
+`rate_limit` when both refuse: running out of plan is the one the customer can
+act on, and being told about the window instead would send them to support
+over the wrong thing.
+
+Open on purpose. The engine's contract says this list will grow, and a closed
+one would turn every code the engine adds into a release the caller has to
+wait on the SDK for. Branch on the codes you know; anything else is still a
+refusal, and still means do not do the work.
+"""
+
+
+class CheckRateLimit(Model):
+    """
+    One rate-limit window in force for this customer and meter.
+
+    Windows are fixed and clock-aligned — a cell starts at a multiple of the
+    window counted from the epoch — which is what lets `used` be a literal
+    count of what the current cell holds and `resets_at` a clock time. A
+    sliding window would owe the reader a footnote for both.
+    """
+
+    window_seconds: int
+    """A whole number of seconds from `60` to `2592000`: a minute to 30
+    days."""
+    max: int
+    used: int
+    remaining: int
+    """`max - used`, floored at 0."""
+    exceeded: bool
+    """`used + quantity > max`: this request does not fit in this window."""
+    resets_at: str
+    """End of the current cell, when `used` goes back to 0. Waiting for it is
+    the fix for a window that refused — unless the quantity is larger than
+    `max`, which never fits however long the caller waits."""
+
+
+class CheckResult(Model):
+    allowed: bool
+    """Both gates: the capacity covers the quantity **and** every rate-limit
+    window admits it. Under `no_cap` or a soft cap the capacity always does."""
+    no_cap: bool
+    """Unlimited for this meter. `available` is `None`. Rate limits still
+    apply — a customer who is never refused on capacity is the one a runaway
+    loop costs most."""
+    available: int | None
+    """
+    The whole capacity: the plan's unused entitlement for the current period,
+    floored at 0, plus every open grant. `None` under `no_cap`, where capacity
+    is not a number. Under a soft cap it is what is left of the included
+    amount, and running out of it refuses nothing.
+
+    One figure and no breakdown: `check` answers from a single cached integer,
+    and itemising where the capacity came from would cost it that. For the
+    per-grant detail, read `customers.allowances.list`.
+    """
+    allow_overage: bool
+    """A soft cap: past `available`, only a rate limit refuses. `False`
+    everywhere else, `no_cap` included."""
+    reason: CheckReason | None = None
+    """Which gate said no. Absent when allowed — `None` here — so its presence
+    is the denial."""
+    rate_limits: list[CheckRateLimit]
+    """
+    Every window in force, refused or not, which is why the engine reports
+    them on every call: a caller that only heard about a limit when it was
+    refused could not slow down before it, only after.
+
+    A limit is protective, not commercial, so it sits beside `available` and
+    is never folded into it — a customer well inside their plan can still be
+    limited, and the two are fixed by different people for different reasons.
+    `[]` when no rule applies, which is the ordinary case.
+    """
+
+
+# Usage ----------------------------------------------------------------------
+
+
+class UsageEvent(Model):
+    """
+    A receipt. The same shape whether the event is new or a replay — no
+    capacity figures, no nullable fields, nothing to branch on.
+    """
+
+    id: str
+    """Meterbase's id for the event. A retry of the same key returns this same
+    id."""
+    customer_id: str
+    meter_id: str
+    quantity: int
+    occurred_at: str
+    """When Meterbase stored it, which chooses the period the event counts
+    against."""
+    recorded_at: str
+    """The same instant as `occurred_at`. Both are on the wire so a reader of
+    either keeps working."""
+    idempotency_key: str
+    replayed: bool
+    """`True` when this key had already been recorded: nothing was written, and
+    this is the original event."""
+
+
+class TrackResult(Model):
+    """Enveloped, like the list reads, so the receipt can grow a sibling field
+    without breaking callers."""
+
+    event: UsageEvent
+
+
+class ReserveResponse(CheckResult):
+    """
+    What the engine answers a reserve with: everything `check` answers, and
+    the hold. `reserve` hands it back as a `Hold`, which adds the two calls
+    that close it.
+    """
+
+    reservation_id: str | None = None
+    """The hold's id, and the event's once a track commits it. `None` on a
+    refusal, which holds nothing."""
+    quantity: int | None = None
+    """What the hold set aside."""
+    expires_at: str | None = None
+    """When the hold comes back on its own. `None` on a refusal."""
+
+
+class ReleaseResult(Model):
+    """The hold that was given back, and what it had set aside."""
+
+    reservation_id: str
+    quantity: int
+
+
+# Plans ----------------------------------------------------------------------
+
+PlanCycle = Literal["daily", "weekly", "monthly", "quarterly", "half_yearly", "yearly"]
+"""
+A plan's billing period. Every recurring allowance it holds is measured
+against it, and it is fixed when the plan is created. `one_time` is not among
+them: that is a kind of allowance, not a period.
+"""
+
+
+class Plan(Model):
+    id: str
+    workspace_id: str
+    key: str
+    name: str
+    description: str
+    cycle: PlanCycle
+    created_at: str
+    updated_at: str
+    archived_at: str | None
+
+
+# Plan allowances ------------------------------------------------------------
+
+PlanAllowanceKind = Literal["recurring", "one_time"]
+"""Which of a `(plan, meter)` pair's two lineages a version belongs to. Each
+numbers itself separately."""
+
+ApplyMode = Literal["immediate", "next_cycle"]
+
+Reconciliation = Literal["none", "prorate", "reset"]
+"""
+What an `immediate` plan change does with the period it lands in: `none` lets
+the new plan's amount govern the whole period, `prorate` weights the two plans
+by the fraction each was held for, and `reset` closes the period at the change
+and opens a fresh one — moving the customer's anchor, and so their renewal
+day.
+"""
+
+RecordedReconciliation = Literal["none", "prorate", "reset", "rebalance"]
+"""
+Reconciliation as a stored row may read it. The plan history is append-only,
+so a mode the API has since stopped accepting — `rebalance` — survives in rows
+written while it did. Responses widen to this; requests do not.
+"""
+
+
+class Validity(Model):
+    """
+    How long a one-time grant lives once minted. Months are kept apart from
+    days because they are not the same length: three months from Jan 31 dies
+    Apr 30, ninety days dies May 1.
+    """
+
+    months: int
+    days: int
+
+
+class ValidityParam(TypedDict):
+    """`Validity`, as a parameter: `valid_for={"months": 3, "days": 0}`."""
+
+    months: int
+    days: int
+
+
+class PlanAllowance(Model):
+    id: str
+    workspace_id: str
+    plan_id: str
+    meter_id: str
+    version: int
+    """1, 2, 3… per lineage. Assigned by the engine, never by the caller."""
+    amount: int | None
+    """Units per period. `0` is legal and grants nothing. `None` under
+    `no_cap`."""
+    no_cap: bool
+    allow_overage: bool
+    """A soft cap: once `amount` is used up, `check` and `reserve` admit rather
+    than refuse, and the usage past it is overage."""
+    kind: PlanAllowanceKind
+    valid_for: Validity | None
+    """`one_time` only; `None` is a grant that never expires."""
+    effective_from: str
+    apply_mode: ApplyMode
+    created_at: str
+
+
+# Plan assignments -----------------------------------------------------------
+
+
+class Assignment(Model):
+    id: str
+    workspace_id: str
+    customer_id: str
+    plan_id: str
+    effective_at: str
+    """Ahead of now for a change that has not landed yet."""
+    effective: ApplyMode
+    """As recorded, which is not always as asked: a first plan starts at
+    once."""
+    reconciliation: RecordedReconciliation
+    """Widened for history: a row written under an older engine may name a
+    mode the API no longer takes."""
+    anchor_at: str
+    """What periods are measured from. A plan change inherits it, so a
+    customer's renewal day never moves under them —
+    `reconciliation="reset"` is the one thing that moves it."""
+    superseded_at: str | None
+    """Set when a newer instruction replaced this one before it took
+    effect."""
+    created_at: str
+
+
+# Entitlement ----------------------------------------------------------------
+
+EntitlementState = Literal["granted", "awaiting"]
+"""`awaiting`: the plan meters this, but its only versions land later."""
+
+
+class Period(Model):
+    """`[start, end)`."""
+
+    start: str
+    end: str
+
+
+class IncomingVersion(Model):
+    """The version that takes over this meter, and when."""
+
+    version: PlanAllowance
+    lands_at: str
+
+
+class _MeterFigures(Model):
+    meter_id: str
+    state: EntitlementState
+    version: PlanAllowance | None
+    amount: int | None
+    no_cap: bool
+    allow_overage: bool
+    """The version in effect's; `False` while `awaiting`."""
+    used: int
+    """What counts toward `amount`."""
+    total: int
+    """`used`, plus what grants paid for."""
+    remaining: int | None
+    overage_used: int | None
+    """`max(used - amount, 0)`, under a hard cap too. `None` where `remaining`
+    is."""
+
+
+class MeterEntitlement(_MeterFigures):
+    """One meter the plan meters, in the current period."""
+
+    reserved: int
+    available: int | None
+    incoming: IncomingVersion | None
+
+
+class CustomerEntitlement(Model):
+    """The current period only, and only the meters the plan meters."""
+
+    customer_id: str
+    plan_id: str
+    cycle: PlanCycle
+    since: str
+    period: Period
+    meters: list[MeterEntitlement]
+
+
+# Closed periods -------------------------------------------------------------
+
+
+class ClosedPeriodMeter(_MeterFigures):
+    """The entitlement meter at the period's last instant, less what describes
+    now. `total - used` is what grants absorbed."""
+
+
+class ClosedPeriod(Model):
+    """`[from, to)`, final: nothing written after it restates it."""
+
+    customer_id: str
+    plan_id: str
+    """The plan in force at the period's last instant."""
+    cycle: PlanCycle
+    since: str
+    """When that plan took effect, as on the entitlement read."""
+    from_: str
+    """`from` on the wire. Microseconds included: pass it back as `before`
+    exactly as it came."""
+    to: str
+    """Its boundary, or the instant a reset closed it early."""
+    meters: list[ClosedPeriodMeter]
+    """One per meter that plan meters."""
+
+
+# Usage by day ---------------------------------------------------------------
+
+UsagePeriod = Literal["current", "last"]
+
+
+class DayUsage(Model):
+    date: str
+    """A UTC day, `YYYY-MM-DD`."""
+    quantity: int
+
+
+class MeterUsage(Model):
+    """Every day of the range that has begun, zeros included."""
+
+    meter_id: str
+    total: int
+    days: list[DayUsage]
+
+
+class CustomerUsage(Model):
+    """`[from, to)`. Only the meters with usage in the range."""
+
+    customer_id: str
+    from_: str
+    """`from` on the wire."""
+    to: str
+    meters: list[MeterUsage]
+
+
+class MeterUsageHistory(MeterUsage):
+    """Every customer's usage of one meter. `[from, to)`."""
+
+    from_: str
+    """`from` on the wire."""
+    to: str
+
+
+# Customer allowances --------------------------------------------------------
+
+AllowanceSource = Literal["purchased", "bonus", "manual"]
+"""`plan` is not accepted on a grant: the engine mints those itself when a
+plan is assigned."""
+
+
+class Allowance(Model):
+    id: str
+    workspace_id: str
+    customer_id: str
+    meter_id: str
+    amount: int | None
+    no_cap: bool
+    consumed: int
+    remaining: int | None
+    """`None` under `no_cap`."""
+    source: AllowanceSource | Literal["plan"]
+    metadata: dict[str, Any]
+    effective_at: str
+    expires_at: str | None
+    revoked_at: str | None
+    exhausted_at: str | None
+    created_at: str
+    plan_allowance_version_id: str | None
+    """`None` unless `source` is `plan`. With `assignment_id` and
+    `cancelled_at`, it answers where the grant came from and why it went
+    away."""
+    assignment_id: str | None
+    cancelled_at: str | None
+
+
+class WhoAmI(Model):
+    workspace: str
+    caller: str
+    kind: Literal["api_key", "service"]
+
+
+# Webhooks -------------------------------------------------------------------
+
+
+class ThresholdPlan(Model):
+    id: str
+    key: str
+    name: str
+
+
+class ThresholdCrossing(Model):
+    """What a threshold crossing reports, as `threshold.crossed` and
+    `entitlement.reached` send it."""
+
+    customer_id: str
+    """The tenant's own customer id."""
+    meter_id: str
+    """The meter's key."""
+    plan: ThresholdPlan | None
+    """The plan in force when it crossed; `None` if they held none."""
+    threshold: int
+    """A whole percent, 1–1000; past 100 is an overage alert."""
+    used: int
+    """The plan's figure at the crossing; it does not include grants."""
+    entitlement: int
+    """The plan's figure at the crossing; it does not include grants."""
+    period: Period
+    usage_event_id: str | None
+
+
+class WebhookEvent(Model):
+    """
+    A delivery. New types can be added; ignore any you do not handle.
+    `verify_webhook` answers the subclass for each type this SDK knows, so
+    `isinstance` tells them apart, and this class itself for any other.
+    """
+
+    id: str
+    """The same on every attempt and every endpoint: dedupe on it."""
+    type: str
+    timestamp: str
+
+
+class ThresholdCrossedEvent(WebhookEvent):
+    """`threshold.crossed`: sent for every mark a customer crosses."""
+
+    data: ThresholdCrossing
+
+
+class EntitlementReachedEvent(WebhookEvent):
+    """`entitlement.reached`: sent for the 100% crossing too, under its own
+    id."""
+
+    data: ThresholdCrossing