meterbase 0.1.1__tar.gz → 0.1.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: meterbase
-Version: 0.1.1
+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
@@ -506,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.
@@ -520,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.
@@ -856,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.1 → 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
@@ -479,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.
@@ -493,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.
@@ -829,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.1 → 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.1 → 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.1 → 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.1/src/meterbase/_version.py

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