The full-stack Python and Next.js starter kit for solo founders

@dataclass(frozen=True, slots=True)
class PricingTerms:
    """What prices a cycle: the included allowance (may be 0) and the overage tiers."""

    included_bytes: int
    tiers: tuple[PriceTier, ...]
    discount_percent: int = 0  # launch period: percent off the overage price (0..100)


def overage_numerator(billable_bytes: int, terms: PricingTerms) -> int:
    """Exact cost x GiB (unit: cent*byte/GiB). Python ints never overflow."""
    overage = max(billable_bytes - terms.included_bytes, 0)
    total = lower = 0
    for tier in terms.tiers:
        if overage <= lower:
            break
        upper = overage if tier.up_to_bytes is None else min(overage, tier.up_to_bytes)
        total += (upper - lower) * tier.cents_per_gb
        if tier.up_to_bytes is None:
            break
        lower = tier.up_to_bytes
    return total


def cost_cents(billable_bytes: int, terms: PricingTerms) -> int:
    """``f``: the cycle's overage cost in cents at ``billable_bytes``, rounded half up once. A
    discount scales the exact numerator, so it is applied before the single rounding."""
    kept = 100 - terms.discount_percent
    return (overage_numerator(billable_bytes, terms) * kept + 50 * GB) // (100 * GB)


def debit_cents(settled_bytes: int, call_bytes: int, terms: PricingTerms) -> int:
    """Cents to debit for a call of ``call_bytes`` settled at cumulative ``settled_bytes`` (>= 0)."""
    return cost_cents(settled_bytes + call_bytes, terms) - cost_cents(settled_bytes, terms)

def _check_cycle_limit_locked(ctx, terms, wallet, cycle, hold, reserve) -> None:
    """Refuse (402 ``cycle_limit_reached``) a call that would take the cycle past a limit the user set:
    billable data in bytes (the included data counts) or overage charged in cents."""
    limits = metering_settings.get(ctx.user_id)
    if limits is None:
        return
    over_bytes = limits.cycle_limit_bytes is not None and cycle.billable_bytes + hold > limits.cycle_limit_bytes
    over_cents = limits.cycle_limit_cents is not None and cycle.charged_cents + reserve > limits.cycle_limit_cents
    if over_bytes or over_cents:
        ...
        raise _denied(ctx, terms, 402, "cycle_limit_reached", message, reserve=reserve, wallet=wallet, cycle=cycle)

def _debit_locked(user_id, wallet, cycle, terms, api_key_id, billable, now) -> int:
    """Price ``billable`` bytes from the cycle's position, debit the balance and add the debit to
    the open hourly bucket; returns the cents debited."""
    settled, included = cycle.billable_bytes, terms.included_bytes
    debit = debit_cents(settled, billable, terms.pricing)
    usage_cycles.update(cycle.id, billable_bytes=settled + billable, charged_cents=cycle.charged_cents + debit)
    # ... per-key and per-day totals, pending hourly bucket, wallet balance update ...
    return debit