meterbase 0.1.0__tar.gz → 0.1.2__tar.gz

{meterbase-0.1.0 → meterbase-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: meterbase
-Version: 0.1.0
+Version: 0.1.2
 Summary: Python SDK for the Meterbase engine
 Project-URL: Homepage, https://meterbase.tech
 Project-URL: Documentation, https://meterbase.tech/docs
@@ -81,10 +81,11 @@ denial — that is an answer, not a failure. Absence of entitlement is not
 permission: a customer with no plan and no grant is denied.
 
 `available` is the whole capacity — the plan's unused entitlement for the
-current period plus every open grant — and is `None` under `no_cap`, where
-capacity is not a number. It is one figure and not a 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 a customer's allowances.
+current period, with what is left of any [rollover](#plan-allowances) carry,
+plus every open grant — and is `None` under `no_cap`, where capacity is not a
+number. It is one figure and not a 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 a customer's allowances.
 
 A check answers **two gates**, and `allowed` needs both: the capacity has to
 cover the quantity, and every rate limit in force — _at most so much of this
@@ -392,6 +393,22 @@ is refused beside `no_cap` and on `one_time`. Like the amount, it is a term of
 the version, so turning it on or off follows `apply_mode`: at each customer's
 next cycle by default.
 
+**Rollover** carries what a period leaves of `amount` into the next one, which
+spends it first. Whatever that period leaves of the carry is lost, so a carry
+never stacks.
+
+```python
+meterbase.plans.allowances.set(plan.id, meter_id=meter.id, amount=1_000, rollover=True)
+```
+
+Both periods' versions must roll over, so moving to a plan that does not ends
+the carry. A `restart` passes nothing on, and usage the carry paid reaches no
+threshold. Read it as `carried_in` and `carried_used` on
+[the entitlement](#how-much-they-have-used). `rollover` defaults to `False`,
+goes beside `allow_overage` and on an amount of `0`, and is refused beside
+`no_cap` and on `one_time`. It follows `apply_mode` too, and the first carry
+arrives a boundary after the version lands.
+
 ### A customer's plan
 
 A customer's plan is an append-only history, not a field: assigning is the only
@@ -448,10 +465,11 @@ is the wire shape underneath all four, and still takes `plan_id`.
 
 #### Two plans on different cycles
 
-A weekly plan and a monthly one share no boundary to wait for and no period to
-weight, so `change_at_next_cycle` and `change_now` + `"prorate"` both raise
-`CycleChangeRequiresResetError`. `restart` is the move that works, and plain
-`change_now` is the other way out — it keeps the period that is running.
+Plans on different cycles share no period to keep, so `change_now` between
+them raises `CycleChangeRequiresResetError`, with `"none"` or `"prorate"`
+alike. A weekly plan and a month-based one share no boundary to wait for
+either, so `change_at_next_cycle` between those two raises it too. `restart` is
+the move that works: it starts a fresh period on the new cycle.
 
 ```python
 from meterbase import CycleChangeRequiresResetError
@@ -473,8 +491,9 @@ trail = meterbase.customers.plan.history(customer.id).data
 `retrieve` is the plan **in force now**, which is not always the newest
 instruction — a change dated ahead does not govern yet — and is `None` for a
 customer holding no plan. That is a default deny rather than a failure, so it
-is an answer here rather than a raised `NotFoundError`; a customer who does not
-exist at all still raises one.
+is an answer here rather than a raised `NotFoundError`. An id that names no
+customer reads as `None` too: the engine answers it as a customer holding no
+plan.
 
 `pending` is the change waiting to land, and at most one ever is: a newer
 instruction supersedes the one before it. `history` is the whole trail,
@@ -504,12 +523,16 @@ for meter in entitlement.meters if entitlement else []:
 
 `entitlement` is the plan's side of the current period, one entry per meter the
 plan meters: the read behind a usage bar in your own app. `used` is what
-`amount` is measured against, `total` adds what grants paid for, and
-`available` is what `check` would answer. `overage_used` is how far `used` has
-run past `amount` — what a [soft cap](#plan-allowances) bills for, and reported
-under a hard cap too — and `None` where there is no amount; `allow_overage`
-says whether the cap in effect is soft. Meters are named by id, and like
-`retrieve` it is `None` for a customer holding no plan.
+`amount` is measured against, `total` adds what the carry and grants paid for,
+and `available` is what `check` would answer. `overage_used` is how far `used`
+has run past `amount` — what a [soft cap](#plan-allowances) bills for, and
+reported under a hard cap too — and `None` where there is no amount;
+`allow_overage` says whether the cap in effect is soft. `rollover` says whether
+it [rolls over](#plan-allowances): `carried_in` is what the last period left of
+its amount, `carried_used` what this one has spent of it, and
+`carried_in - carried_used` what goes at the period's end. Both are `0` where
+nothing rolled over and `None` where there is no amount. Meters are named by
+id, and like `retrieve` it is `None` for a customer holding no plan.
 
 Unlike `check`, it is not answered from a cache, so read it where usage is
 shown rather than on every request.
@@ -518,7 +541,9 @@ shown rather than on every request.
 
 `customers.periods.last` is the newest period that has ended, with the figures
 to bill from: per meter, the cap `check` answered at its last instant, `used`
-against it, and `overage_used`, which is what a soft cap bills; `total - used`
+against it, and `overage_used`, which is what a soft cap bills. `carried_in`,
+`carried_used` and `carried_out` are what a rolling allowance took from the
+period before, spent, and passed to the next, and `total - used - carried_used`
 is what grants absorbed. They come from the counters behind `check`, which
 count each event exactly once. [Usage by day](#usage-by-day) is for where
 usage went, not for billing.
@@ -854,8 +879,9 @@ exactly that much away, that a replay takes nothing, and that a reused key
 replays whatever the body says; that a hold's commit records what the work cost
 and gives the rest back; that a rate limit comes back on every `check` and
 refuses with the allowance untouched; that a soft cap admits and holds past its
-amount and reports the overage; that a period a `restart` closes settles for a
-minute, which the run waits out, and then reads final; that plan changes
+amount and reports the overage; that a rolling allowance carries nothing into a
+first period or across a `restart`; that a period a `restart` closes settles
+for a minute, which the run waits out, and then reads final; that plan changes
 schedule, cancel and re-anchor as documented; and — reading each model's
 annotations — that the engine's fields still match the SDK's types exactly, in
 both directions.

{meterbase-0.1.0 → meterbase-0.1.2}/README.md

@@ -54,10 +54,11 @@ denial — that is an answer, not a failure. Absence of entitlement is not
 permission: a customer with no plan and no grant is denied.
 
 `available` is the whole capacity — the plan's unused entitlement for the
-current period plus every open grant — and is `None` under `no_cap`, where
-capacity is not a number. It is one figure and not a 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 a customer's allowances.
+current period, with what is left of any [rollover](#plan-allowances) carry,
+plus every open grant — and is `None` under `no_cap`, where capacity is not a
+number. It is one figure and not a 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 a customer's allowances.
 
 A check answers **two gates**, and `allowed` needs both: the capacity has to
 cover the quantity, and every rate limit in force — _at most so much of this
@@ -365,6 +366,22 @@ is refused beside `no_cap` and on `one_time`. Like the amount, it is a term of
 the version, so turning it on or off follows `apply_mode`: at each customer's
 next cycle by default.
 
+**Rollover** carries what a period leaves of `amount` into the next one, which
+spends it first. Whatever that period leaves of the carry is lost, so a carry
+never stacks.
+
+```python
+meterbase.plans.allowances.set(plan.id, meter_id=meter.id, amount=1_000, rollover=True)
+```
+
+Both periods' versions must roll over, so moving to a plan that does not ends
+the carry. A `restart` passes nothing on, and usage the carry paid reaches no
+threshold. Read it as `carried_in` and `carried_used` on
+[the entitlement](#how-much-they-have-used). `rollover` defaults to `False`,
+goes beside `allow_overage` and on an amount of `0`, and is refused beside
+`no_cap` and on `one_time`. It follows `apply_mode` too, and the first carry
+arrives a boundary after the version lands.
+
 ### A customer's plan
 
 A customer's plan is an append-only history, not a field: assigning is the only
@@ -421,10 +438,11 @@ is the wire shape underneath all four, and still takes `plan_id`.
 
 #### Two plans on different cycles
 
-A weekly plan and a monthly one share no boundary to wait for and no period to
-weight, so `change_at_next_cycle` and `change_now` + `"prorate"` both raise
-`CycleChangeRequiresResetError`. `restart` is the move that works, and plain
-`change_now` is the other way out — it keeps the period that is running.
+Plans on different cycles share no period to keep, so `change_now` between
+them raises `CycleChangeRequiresResetError`, with `"none"` or `"prorate"`
+alike. A weekly plan and a month-based one share no boundary to wait for
+either, so `change_at_next_cycle` between those two raises it too. `restart` is
+the move that works: it starts a fresh period on the new cycle.
 
 ```python
 from meterbase import CycleChangeRequiresResetError
@@ -446,8 +464,9 @@ trail = meterbase.customers.plan.history(customer.id).data
 `retrieve` is the plan **in force now**, which is not always the newest
 instruction — a change dated ahead does not govern yet — and is `None` for a
 customer holding no plan. That is a default deny rather than a failure, so it
-is an answer here rather than a raised `NotFoundError`; a customer who does not
-exist at all still raises one.
+is an answer here rather than a raised `NotFoundError`. An id that names no
+customer reads as `None` too: the engine answers it as a customer holding no
+plan.
 
 `pending` is the change waiting to land, and at most one ever is: a newer
 instruction supersedes the one before it. `history` is the whole trail,
@@ -477,12 +496,16 @@ for meter in entitlement.meters if entitlement else []:
 
 `entitlement` is the plan's side of the current period, one entry per meter the
 plan meters: the read behind a usage bar in your own app. `used` is what
-`amount` is measured against, `total` adds what grants paid for, and
-`available` is what `check` would answer. `overage_used` is how far `used` has
-run past `amount` — what a [soft cap](#plan-allowances) bills for, and reported
-under a hard cap too — and `None` where there is no amount; `allow_overage`
-says whether the cap in effect is soft. Meters are named by id, and like
-`retrieve` it is `None` for a customer holding no plan.
+`amount` is measured against, `total` adds what the carry and grants paid for,
+and `available` is what `check` would answer. `overage_used` is how far `used`
+has run past `amount` — what a [soft cap](#plan-allowances) bills for, and
+reported under a hard cap too — and `None` where there is no amount;
+`allow_overage` says whether the cap in effect is soft. `rollover` says whether
+it [rolls over](#plan-allowances): `carried_in` is what the last period left of
+its amount, `carried_used` what this one has spent of it, and
+`carried_in - carried_used` what goes at the period's end. Both are `0` where
+nothing rolled over and `None` where there is no amount. Meters are named by
+id, and like `retrieve` it is `None` for a customer holding no plan.
 
 Unlike `check`, it is not answered from a cache, so read it where usage is
 shown rather than on every request.
@@ -491,7 +514,9 @@ shown rather than on every request.
 
 `customers.periods.last` is the newest period that has ended, with the figures
 to bill from: per meter, the cap `check` answered at its last instant, `used`
-against it, and `overage_used`, which is what a soft cap bills; `total - used`
+against it, and `overage_used`, which is what a soft cap bills. `carried_in`,
+`carried_used` and `carried_out` are what a rolling allowance took from the
+period before, spent, and passed to the next, and `total - used - carried_used`
 is what grants absorbed. They come from the counters behind `check`, which
 count each event exactly once. [Usage by day](#usage-by-day) is for where
 usage went, not for billing.
@@ -827,8 +852,9 @@ exactly that much away, that a replay takes nothing, and that a reused key
 replays whatever the body says; that a hold's commit records what the work cost
 and gives the rest back; that a rate limit comes back on every `check` and
 refuses with the allowance untouched; that a soft cap admits and holds past its
-amount and reports the overage; that a period a `restart` closes settles for a
-minute, which the run waits out, and then reads final; that plan changes
+amount and reports the overage; that a rolling allowance carries nothing into a
+first period or across a `restart`; that a period a `restart` closes settles
+for a minute, which the run waits out, and then reads final; that plan changes
 schedule, cancel and re-anchor as documented; and — reading each model's
 annotations — that the engine's fields still match the SDK's types exactly, in
 both directions.

{meterbase-0.1.0 → meterbase-0.1.2}/src/meterbase/_async/resources/customer_plan.py

@@ -96,8 +96,9 @@ class AsyncCustomerPlan:
         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.
+        A weekly plan and a month-based one share no boundary, and between
+        them this raises `CycleChangeRequiresResetError`: use `restart` for
+        that move. Other cycles land on the coarser plan's boundary.
         """
         return await self.change(customer_id, plan=plan, effective="next_cycle")
 
@@ -117,10 +118,11 @@ class AsyncCustomerPlan:
           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.
+          it was held for.
 
-        To have the period itself start over instead, use `restart`.
+        Between plans on different cycles both are refused with
+        `CycleChangeRequiresResetError`: there is no period to keep, so use
+        `restart`. To have the period itself start over, use `restart` too.
         """
         return await self.change(
             customer_id,
@@ -170,8 +172,8 @@ class AsyncCustomerPlan:
 
         `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.
+        and not a raised `NotFoundError`. An id that names no customer answers
+        `None` too: the engine reads it as a customer holding no plan.
         """
         try:
             return await self._api.request(

{meterbase-0.1.0 → meterbase-0.1.2}/src/meterbase/_async/resources/customers.py

@@ -98,7 +98,9 @@ class AsyncCustomers:
         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."""
+        """`None` for a customer holding no plan, as `plan.retrieve` answers,
+        and for an id that names no customer, which the engine reads the same
+        way."""
         try:
             return await self._api.request(
                 "GET",

{meterbase-0.1.0 → meterbase-0.1.2}/src/meterbase/_async/resources/plans.py

@@ -32,6 +32,7 @@ class AsyncPlanAllowances:
         amount: int | NotGiven = NOT_GIVEN,
         no_cap: bool | NotGiven = NOT_GIVEN,
         allow_overage: bool | NotGiven = NOT_GIVEN,
+        rollover: bool | NotGiven = NOT_GIVEN,
         kind: PlanAllowanceKind | NotGiven = NOT_GIVEN,
         valid_for: ValidityParam | Validity | NotGiven = NOT_GIVEN,
         apply_mode: ApplyMode | NotGiven = NOT_GIVEN,
@@ -41,9 +42,11 @@ class AsyncPlanAllowances:
         cycle. Give exactly one of `amount` or `no_cap`.
 
         `allow_overage` is a soft cap: past `amount`, admit rather than refuse.
-        Defaults to `False`; refused beside `no_cap` and on `one_time`. `kind`
-        defaults to `recurring`. `valid_for` is `one_time` only. `apply_mode`
-        defaults to `next_cycle`, except `one_time` which is always immediate.
+        `rollover` carries what a period leaves of `amount` into the next one,
+        which spends it first. Both default to `False` and are refused beside
+        `no_cap` and on `one_time`. `kind` defaults to `recurring`. `valid_for`
+        is `one_time` only. `apply_mode` defaults to `next_cycle`, except
+        `one_time` which is always immediate.
         """
         return await self._api.request(
             "POST",
@@ -54,6 +57,7 @@ class AsyncPlanAllowances:
                 "amount": amount,
                 "no_cap": no_cap,
                 "allow_overage": allow_overage,
+                "rollover": rollover,
                 "kind": kind,
                 "valid_for": valid_for,
                 "apply_mode": apply_mode,

{meterbase-0.1.0 → meterbase-0.1.2}/src/meterbase/_sync/resources/customer_plan.py

@@ -100,8 +100,9 @@ class CustomerPlan:
         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.
+        A weekly plan and a month-based one share no boundary, and between
+        them this raises `CycleChangeRequiresResetError`: use `restart` for
+        that move. Other cycles land on the coarser plan's boundary.
         """
         return self.change(customer_id, plan=plan, effective="next_cycle")
 
@@ -121,10 +122,11 @@ class CustomerPlan:
           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.
+          it was held for.
 
-        To have the period itself start over instead, use `restart`.
+        Between plans on different cycles both are refused with
+        `CycleChangeRequiresResetError`: there is no period to keep, so use
+        `restart`. To have the period itself start over, use `restart` too.
         """
         return self.change(
             customer_id,
@@ -174,8 +176,8 @@ class CustomerPlan:
 
         `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.
+        and not a raised `NotFoundError`. An id that names no customer answers
+        `None` too: the engine reads it as a customer holding no plan.
         """
         try:
             return self._api.request(

{meterbase-0.1.0 → meterbase-0.1.2}/src/meterbase/_sync/resources/customers.py

@@ -100,7 +100,9 @@ class Customers:
         return found.data[0] if found.data else None
 
     def entitlement(self, id: str) -> CustomerEntitlement | None:
-        """`None` for a customer holding no plan, as `plan.retrieve` answers."""
+        """`None` for a customer holding no plan, as `plan.retrieve` answers,
+        and for an id that names no customer, which the engine reads the same
+        way."""
         try:
             return self._api.request(
                 "GET",

{meterbase-0.1.0 → meterbase-0.1.2}/src/meterbase/_sync/resources/plans.py

@@ -36,6 +36,7 @@ class PlanAllowances:
         amount: int | NotGiven = NOT_GIVEN,
         no_cap: bool | NotGiven = NOT_GIVEN,
         allow_overage: bool | NotGiven = NOT_GIVEN,
+        rollover: bool | NotGiven = NOT_GIVEN,
         kind: PlanAllowanceKind | NotGiven = NOT_GIVEN,
         valid_for: ValidityParam | Validity | NotGiven = NOT_GIVEN,
         apply_mode: ApplyMode | NotGiven = NOT_GIVEN,
@@ -45,9 +46,11 @@ class PlanAllowances:
         cycle. Give exactly one of `amount` or `no_cap`.
 
         `allow_overage` is a soft cap: past `amount`, admit rather than refuse.
-        Defaults to `False`; refused beside `no_cap` and on `one_time`. `kind`
-        defaults to `recurring`. `valid_for` is `one_time` only. `apply_mode`
-        defaults to `next_cycle`, except `one_time` which is always immediate.
+        `rollover` carries what a period leaves of `amount` into the next one,
+        which spends it first. Both default to `False` and are refused beside
+        `no_cap` and on `one_time`. `kind` defaults to `recurring`. `valid_for`
+        is `one_time` only. `apply_mode` defaults to `next_cycle`, except
+        `one_time` which is always immediate.
         """
         return self._api.request(
             "POST",
@@ -58,6 +61,7 @@ class PlanAllowances:
                 "amount": amount,
                 "no_cap": no_cap,
                 "allow_overage": allow_overage,
+                "rollover": rollover,
                 "kind": kind,
                 "valid_for": valid_for,
                 "apply_mode": apply_mode,

meterbase-0.1.2/src/meterbase/_version.py

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

{meterbase-0.1.0 → meterbase-0.1.2}/src/meterbase/errors.py

@@ -162,11 +162,11 @@ class ReservationMismatchError(InvalidRequestError):
 class CycleChangeRequiresResetError(InvalidRequestError):
     """
     `422 cycle_change_requires_reset`: the two plans measure different cycles,
-    so a `next_cycle` change has no shared boundary to wait for and a
-    `prorate` no shared period to weight. The move is `customers.plan.restart`,
-    which closes the current period and opens a fresh one on the new cycle —
-    or `change_now` with the default `reconciliation="none"` to keep the
-    period that is running. The engine's `message` says as much.
+    so the change has no period to keep. An immediate change between them is
+    refused unless it resets, and a `next_cycle` change is refused between a
+    weekly plan and a month-based one, which share no boundary to wait for.
+    The move is `customers.plan.restart`, which closes the current period and
+    opens a fresh one on the new cycle. The engine's `message` says as much.
 
     An `InvalidRequestError` still, so an existing `except` keeps working.
     """

{meterbase-0.1.0 → meterbase-0.1.2}/src/meterbase/types.py

@@ -190,9 +190,10 @@ class CheckResult(Model):
     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.
+    floored at 0, plus what is left of a rollover carry, 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
@@ -353,6 +354,9 @@ class PlanAllowance(Model):
     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."""
+    rollover: bool
+    """What a period leaves unused of `amount` carries into the next, which
+    spends it first. The carry lasts that one period."""
     kind: PlanAllowanceKind
     valid_for: Validity | None
     """`one_time` only; `None` is a grant that never expires."""
@@ -415,14 +419,22 @@ class _MeterFigures(Model):
     no_cap: bool
     allow_overage: bool
     """The version in effect's; `False` while `awaiting`."""
+    rollover: bool
+    """The version in effect's; `False` while `awaiting`."""
     used: int
     """What counts toward `amount`."""
     total: int
-    """`used`, plus what grants paid for."""
+    """`used`, plus what the carry and grants paid for."""
     remaining: int | None
     overage_used: int | None
     """`max(used - amount, 0)`, under a hard cap too. `None` where `remaining`
     is."""
+    carried_in: int | None
+    """What the period before left of its amount, when both versions roll
+    over; `0` otherwise. `None` where `remaining` is."""
+    carried_used: int | None
+    """What this period has spent of `carried_in`, which goes first and is not
+    in `used`. `None` where `remaining` is."""
 
 
 class MeterEntitlement(_MeterFigures):
@@ -449,7 +461,11 @@ class CustomerEntitlement(Model):
 
 class ClosedPeriodMeter(_MeterFigures):
     """The entitlement meter at the period's last instant, less what describes
-    now. `total - used` is what grants absorbed."""
+    now. `total - used - carried_used` is what grants absorbed."""
+
+    carried_out: int | None
+    """What it passed on: `max(amount - used, 0)` under a version that rolled
+    over, `0` otherwise and after a reset. `None` where `remaining` is."""
 
 
 class ClosedPeriod(Model):

meterbase-0.1.0/src/meterbase/_version.py

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