Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! Plans, billing periods, settings, and the API-facing snapshot.
use super::pricing::AiPricing;
pub use ai_usage::NON_BILLABLE_AI_FEATURES;
use chrono::{DateTime, Datelike, Months, TimeZone, Utc};
use macro_user_id::user_id::MacroUserIdStr;
use macro_uuid::Uuid;
use roles_and_permissions::domain::model::RoleId;
use serde::{Deserialize, Serialize};
use std::collections::HashSet;
use thiserror::Error;
use utoipa::ToSchema;
/// Whether usage past a payer's allowance is settled: prepaid credits consumed
/// and automatic credit reloads collected through Stripe. Hosts load it from
/// `ENABLE_AI_USAGE_BILLING` at startup. It is independent of quota admission
/// ([`AiUsageEnforcement`](ai_usage::AiUsageEnforcement)) and of the deployment
/// environment.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub enum AiUsageBilling {
/// Never consume credits, reserve overage, or collect payment.
#[default]
Disabled,
/// Settle uncovered usage from credits, with optional automatic reloads.
Enabled,
}
impl AiUsageBilling {
/// Whether settlement is enabled.
pub const fn is_enabled(self) -> bool {
matches!(self, Self::Enabled)
}
}
/// Persisted usage-policy identity, independent of purchase availability or today's roles.
/// A verified period activation selects this value; legacy records are never repriced.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum UsagePolicy {
/// Aggregate per-period settlement in [`super::ledger`]: the at-cost
/// allowance, then prepaid credits at the markup.
Legacy,
/// Per-attempt exact-money policy in [`super::policy`]: the same allowance
/// at public price, then public usage at the same markup.
PublicAllowanceV1,
}
/// One-off credit packs a payer may buy, in customer cents.
pub const CREDIT_PACKS_CENTS: [i64; 4] = [1_000, 2_500, 5_000, 10_000];
/// Smallest per-period overage cap a payer may set.
pub const OVERAGE_LIMIT_MIN_CENTS: i64 = 500;
/// Largest per-period overage cap a payer may set.
pub const OVERAGE_LIMIT_MAX_CENTS: i64 = 500_000;
/// Credit balance below which an automatic reload fires, unless the payer
/// has set their own minimum.
pub const AUTO_RELOAD_DEFAULT_MINIMUM_CENTS: i64 = 500;
/// Credit balance an automatic reload tops up to, unless the payer has set
/// their own target.
pub const AUTO_RELOAD_DEFAULT_TARGET_CENTS: i64 = 2_500;
/// Largest automatic reload target a payer may set.
pub const AUTO_RELOAD_TARGET_MAX_CENTS: i64 = 500_000;
/// Accrued overage is charged once it reaches this much (or when the period
/// ends), so a payer sees a few predictable charges rather than one per
/// completion.
pub const OVERAGE_CHARGE_THRESHOLD_CENTS: i64 = 1_000;
/// Stripe rejects charges under $0.50; a smaller period-end remainder is
/// forgiven rather than retried forever.
pub const MIN_STRIPE_CHARGE_CENTS: i64 = 50;
/// The plans a user can be on, cheapest first.
#[derive(
Debug,
Clone,
Copy,
PartialEq,
Eq,
PartialOrd,
Ord,
Hash,
Serialize,
Deserialize,
ToSchema,
strum::Display,
strum::EnumString,
)]
#[serde(rename_all = "snake_case")]
#[strum(serialize_all = "snake_case")]
pub enum PlanTier {
/// No subscription. AI on the free model only, hard-capped at the
/// configured free allowance each calendar month; no credits or overage.
Free,
/// The $40/seat/month plan (recorded as the legacy `sub_opus` role).
Premium,
/// The $200/seat/month plan, with its own configured AI allowance.
Max,
}
impl PlanTier {
/// Monthly subscription price per seat, in cents.
pub const fn monthly_price_cents(self) -> i64 {
match self {
PlanTier::Free => 0,
PlanTier::Premium => 4_000,
PlanTier::Max => 20_000,
}
}
/// Monthly automatic reload limit a payer on this tier starts from, in
/// customer cents. `None` for tiers that cannot reload.
pub const fn default_auto_reload_monthly_limit_cents(self) -> Option<i64> {
match self {
PlanTier::Free => None,
PlanTier::Premium => Some(20_000),
PlanTier::Max => Some(100_000),
}
}
/// AI usage included per seat per period, in cents at provider cost: this
/// tier's configured allowance ([`AiPricing::included_allowance_cents_for`]).
/// For Free this is the whole monthly cap.
pub const fn included_ai_cents_per_seat(self, pricing: AiPricing) -> i64 {
pricing.included_allowance_cents_for(self)
}
/// Whether this tier pays for AI beyond its allowance (credits and overage
/// need a plan). Free is hard-capped at its allowance instead.
pub const fn is_paid(self) -> bool {
!matches!(self, PlanTier::Free)
}
/// Derive the tier from a user's roles. `sub_max` wins over every other
/// paid role; any other paid subscription role is Premium.
pub fn from_roles(roles: &HashSet<RoleId>) -> Self {
if roles.contains(&RoleId::SubMax) {
PlanTier::Max
} else if roles.iter().any(RoleId::is_paid_subscription) {
PlanTier::Premium
} else {
PlanTier::Free
}
}
}
impl From<teams::domain::model::SeatPlan> for PlanTier {
fn from(plan: teams::domain::model::SeatPlan) -> Self {
match plan {
teams::domain::model::SeatPlan::Premium => PlanTier::Premium,
teams::domain::model::SeatPlan::Max => PlanTier::Max,
}
}
}
/// A half-open `[start, end)` window that usage is metered against.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct BillingPeriod {
/// Inclusive start.
pub start: DateTime<Utc>,
/// Exclusive end.
pub end: DateTime<Utc>,
}
impl BillingPeriod {
/// The period containing `now`.
///
/// With a Stripe anchor (the subscription's most recently synced
/// `current_period_start/end`) the window is the anchor itself, rolled
/// forward by its own length in months when the webhook that would have
/// moved it has not landed yet. Without an anchor, the UTC calendar month.
pub fn current(anchor: Option<(DateTime<Utc>, DateTime<Utc>)>, now: DateTime<Utc>) -> Self {
if let Some((start, end)) = anchor
&& start < end
{
if now < end {
return Self { start, end };
}
let anchor_days = (end - start).num_days().max(1) as f64;
let months_per_period = (anchor_days / 30.44).round().max(1.0) as u32;
let mut index = 1u32;
// A stale anchor is at most a few periods old; cap the walk so a
// pathological anchor can never spin.
while index <= 1_200 {
let candidate = start
.checked_add_months(Months::new(index * months_per_period))
.zip(start.checked_add_months(Months::new((index + 1) * months_per_period)));
match candidate {
Some((s, e)) if now < e => return Self { start: s, end: e },
Some(_) => index += 1,
None => break,
}
}
}
Self::calendar_month(now)
}
/// The stored anchor when it contains `now`.
pub fn covering(
anchor: Option<(DateTime<Utc>, DateTime<Utc>)>,
now: DateTime<Utc>,
) -> Option<Self> {
let (start, end) = anchor?;
(start <= now && now < end).then_some(Self { start, end })
}
/// The part of this subscription window to store and meter after the
/// stored anchor.
///
/// The start moves up to the anchor's end because the store refuses a start
/// that overlaps the stored window. `None` when that part does not contain
/// `now`, because it is then not a period to meter.
pub fn adopted(
self,
anchor: Option<(DateTime<Utc>, DateTime<Utc>)>,
now: DateTime<Utc>,
) -> Option<Self> {
let start = match anchor {
Some((_, stored_end)) => self.start.max(stored_end),
None => self.start,
};
Self::covering(Some((start, self.end)), now)
}
/// The period immediately before this one, assuming the same length in
/// whole months (one month for calendar periods).
pub fn previous(&self) -> Self {
let anchor_days = (self.end - self.start).num_days().max(1) as f64;
let months = Months::new((anchor_days / 30.44).round().max(1.0) as u32);
let start = self.start.checked_sub_months(months).unwrap_or(self.start);
Self {
start,
end: self.start,
}
}
/// The UTC calendar month containing `now`.
pub fn calendar_month(now: DateTime<Utc>) -> Self {
let start = Utc
.with_ymd_and_hms(now.year(), now.month(), 1, 0, 0, 0)
.single()
.unwrap_or(now);
let end = start.checked_add_months(Months::new(1)).unwrap_or(start);
Self { start, end }
}
/// Whether `now` is at or past the end of this period.
pub fn has_ended(&self, now: DateTime<Utc>) -> bool {
now >= self.end
}
/// `Some` while `now` is inside `[start, end)`.
pub fn open_start(self, now: DateTime<Utc>) -> Option<OpenPeriodStart> {
if self.has_ended(now) {
None
} else {
Some(OpenPeriodStart(self.start))
}
}
}
/// Start of the period that contains `now`.
///
/// Closed periods cannot be named by this type, so open-period writers cannot
/// target them.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct OpenPeriodStart(DateTime<Utc>);
impl OpenPeriodStart {
/// Inclusive start of the open period.
pub const fn start(self) -> DateTime<Utc> {
self.0
}
}
/// Monotonic generation of a payer's open-seat roster.
///
/// A missing `ai_billing_account` row is generation zero. Releasing a seat
/// moves it forward so a roster read from before the release cannot be stored.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct SeatGeneration(i64);
impl SeatGeneration {
/// The generation stored in Postgres.
pub const fn from_raw(raw: i64) -> Self {
Self(raw)
}
/// The generation stored in Postgres.
pub const fn raw(self) -> i64 {
self.0
}
}
/// Outcome of a conditional open-period allowance store.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AllowanceStore {
/// The open-period row matches the supplied seats.
Stored,
/// `seat_generation` moved after it was observed. The arrays were not written.
Conflict,
}
/// Which of the payer's subscriptions funds an overage charge.
///
/// A payer may hold a personal subscription and a team subscription at the
/// same time. Team owners and team members both use the team subscription.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SubscriptionScope {
/// The subscription that is not tied to a team.
Personal,
/// The subscription for this team.
Team {
/// The team.
team_id: Uuid,
},
}
impl From<&PayerScope> for SubscriptionScope {
fn from(scope: &PayerScope) -> Self {
match scope {
PayerScope::Personal => Self::Personal,
PayerScope::TeamOwner { team_id } | PayerScope::TeamMember { team_id } => {
Self::Team { team_id: *team_id }
}
}
}
}
/// Who pays for a user's AI, and through what.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum PayerScope {
/// A personal subscription (or no subscription).
Personal,
/// The user owns a paying team and pays for members' shared credits and
/// overage.
TeamOwner {
/// The team.
team_id: Uuid,
},
/// The user's paid access comes through a team; the owner pays.
TeamMember {
/// The team.
team_id: Uuid,
},
}
/// The included AI assigned to one billed seat for a period.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SeatAllowance {
/// The user occupying the seat.
pub user: MacroUserIdStr<'static>,
/// Included AI for this seat, in cents at provider cost.
pub included_cents: i64,
}
/// AI usage attributed to one billed seat in a period.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SeatUsage {
/// The user occupying the seat.
pub user: MacroUserIdStr<'static>,
/// Usage in cents at provider cost.
pub used_cents: i64,
/// Total historical overage across paid allowance intervals, when plan
/// history exists. Earlier included costs never become debt on downgrade;
/// upgrades preserve old overage and previously consumed credits.
/// Without history, the service applies the current seat allowance.
pub chargeable_cost_cents: Option<i64>,
}
/// A user's resolved plan and payer.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Entitlement {
/// The plan the user's own seat is on.
pub tier: PlanTier,
/// The plan of every billed seat, in the same order as [`Self::billed_users`].
/// A team may mix Premium and Max seats.
pub seat_tiers: Vec<PlanTier>,
/// Enterprise teams are billed out of band and never metered.
pub unlimited: bool,
/// The account that owns credits, overage settings, and the Stripe
/// customer. The user themself unless they are a team member.
pub payer: MacroUserIdStr<'static>,
/// Every user whose usage can consume the payer's shared credits and
/// overage. Contains at least the payer.
pub billed_users: Vec<MacroUserIdStr<'static>>,
/// How the payer relates to the user.
pub scope: PayerScope,
}
impl Entitlement {
/// A user with no team, paying (or not) for themself.
pub fn personal(user: MacroUserIdStr<'static>, tier: PlanTier) -> Self {
Self {
tier,
seat_tiers: vec![tier],
unlimited: false,
payer: user.clone(),
billed_users: vec![user],
scope: PayerScope::Personal,
}
}
/// Seats billed to the payer.
pub fn seats(&self) -> u32 {
self.billed_users.len().max(1) as u32
}
/// Included AI for this user's seat, in cents at provider cost.
pub fn included_ai_cents(&self, pricing: AiPricing) -> i64 {
self.tier.included_ai_cents_per_seat(pricing)
}
/// Each billed seat with its own included AI. Unused allowance never moves
/// between seats; only credits and overage are shared by the payer.
pub fn seat_allowances(&self, pricing: AiPricing) -> Vec<SeatAllowance> {
self.billed_users
.iter()
.enumerate()
.map(|(index, user)| {
let tier = self.seat_tiers.get(index).copied().unwrap_or(self.tier);
SeatAllowance {
user: user.clone(),
included_cents: tier.included_ai_cents_per_seat(pricing),
}
})
.collect()
}
/// Whether `user` is the payer (and may change billing settings).
pub fn is_payer(&self, user: &MacroUserIdStr<'_>) -> bool {
self.payer.as_ref() == user.as_ref()
}
/// Paid and finite: usage is metered against a subscription period.
pub fn is_metered(&self) -> bool {
self.tier.is_paid() && !self.unlimited
}
}
/// When and how far a payer's credit balance is automatically reloaded.
///
/// The legacy `overage_enabled` storage field now controls only automatic reloads.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AutoReloadThresholds {
/// Reload once the effective balance drops below this, in customer cents.
pub minimum_cents: i64,
/// Reload the balance back up to this, in customer cents.
pub target_cents: i64,
/// Most a payer will be reloaded per UTC calendar month, in customer
/// cents. `None` means no limit.
pub monthly_limit_cents: Option<i64>,
}
impl Default for AutoReloadThresholds {
fn default() -> Self {
Self {
minimum_cents: AUTO_RELOAD_DEFAULT_MINIMUM_CENTS,
target_cents: AUTO_RELOAD_DEFAULT_TARGET_CENTS,
monthly_limit_cents: None,
}
}
}
impl AutoReloadThresholds {
/// Reject thresholds that could never produce a chargeable reload or
/// that exceed the offered range.
pub fn validate(&self) -> Result<()> {
if self.minimum_cents <= 0 {
return Err(BillingError::InvalidAutoReload(
"minimum balance must be positive",
));
}
if self.target_cents < self.minimum_cents + MIN_STRIPE_CHARGE_CENTS {
return Err(BillingError::InvalidAutoReload(
"target balance must be at least $0.50 above the minimum balance",
));
}
if self.target_cents > AUTO_RELOAD_TARGET_MAX_CENTS {
return Err(BillingError::InvalidAutoReload(
"target balance exceeds the largest offered reload",
));
}
// Keep the offered minimum monthly reload budget.
if self
.monthly_limit_cents
.is_some_and(|limit| limit < OVERAGE_LIMIT_MIN_CENTS)
{
return Err(BillingError::InvalidAutoReload(
"monthly spend limit must be at least $5",
));
}
Ok(())
}
}
/// The payer's overage settings, Stripe period anchor, and open-seat generation.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct BillingSettings {
/// Legacy storage name for the automatic reload opt-in. Never authorizes direct charges.
pub overage_enabled: bool,
/// Per-period cap on overage, in customer cents.
pub overage_limit_cents: i64,
/// Set when an overage charge failed to collect.
pub overage_suspended_at: Option<DateTime<Utc>>,
/// When and how far credits are automatically reloaded.
pub auto_reload: AutoReloadThresholds,
/// Set when an automatic reload failed to collect.
pub auto_reload_suspended_at: Option<DateTime<Utc>>,
/// The subscription period last observed from Stripe (webhook or read-through).
pub period_anchor: Option<(DateTime<Utc>, DateTime<Utc>)>,
/// Generation of the payer's open-seat roster. Zero when no account row exists.
pub seat_generation: SeatGeneration,
}
impl BillingSettings {
/// Direct usage charges are permanently disabled, regardless of stored legacy settings.
pub fn overage_active(&self) -> bool {
false
}
/// Whether credits are automatically reloaded: the payer opted in and no
/// reload has failed since the payer last re-enabled it.
pub fn auto_reload_active(&self) -> bool {
self.overage_enabled && self.auto_reload_suspended_at.is_none()
}
}
/// What has already been settled against a period.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct PeriodLedger {
/// Credits applied to this period's usage, in cents (positive).
pub credits_consumed_cents: i64,
/// Overage charged for this period, in cents. Includes pending and paid
/// charges, plus failed charges whose Stripe invoice may still collect.
pub overage_charged_cents: i64,
}
/// The allowance observed for a payer while a period was still open.
///
/// Closed-period settlement uses this instead of the live entitlement so a
/// later plan or seat change cannot skip last period's overage (upgrade) or
/// charge usage that was included (downgrade).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PeriodAllowance {
/// Included AI frozen for each seat in the period.
pub seats: Vec<SeatAllowance>,
}
/// Lifecycle of an overage charge pushed to Stripe.
#[derive(
Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, strum::Display, strum::EnumString,
)]
#[serde(rename_all = "snake_case")]
#[strum(serialize_all = "snake_case")]
pub enum OverageChargeStatus {
/// Reserved in the ledger; Stripe not yet confirmed.
Pending,
/// Collected.
Paid,
/// Collection failed and overage is suspended. The charge stops covering
/// usage only when no Stripe invoice was opened for it.
Failed,
}
/// What a card-on-file credit charge is for. Both kinds count against the
/// payer's monthly credit limit.
#[derive(Debug, Clone, Copy, PartialEq, Eq, strum::Display, strum::EnumString)]
#[strum(serialize_all = "snake_case")]
pub enum CreditReloadKind {
/// Bought by Auto-Reload when the balance fell under the minimum.
Automatic,
/// Bought once by the payer or a team member.
Purchase,
}
/// How a one-time credit purchase charged to the card on file ended.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, ToSchema)]
#[serde(rename_all = "snake_case")]
pub enum CreditPurchaseStatus {
/// Collected and booked as credits.
Paid,
/// The card was declined. The invoice stays open for the provider's
/// retries; buying again retries it instead of charging twice.
Declined,
/// The payer has no card on file. Nothing was reserved or charged; the
/// payer can buy the same pack through checkout instead.
PaymentMethodRequired,
/// The card needs the cardholder to authenticate (3-D Secure), which an
/// off-session charge can't do. The invoice was voided, so nothing was
/// charged; the payer can buy the same pack through checkout instead.
AuthenticationRequired,
}
/// A one-time credit purchase charged to the payer's card on file.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CreditPurchase {
/// Amount charged, customer cents. A retry of an earlier declined
/// purchase charges that purchase's amount.
pub amount_cents: i64,
/// How the charge ended.
pub status: CreditPurchaseStatus,
}
/// The monthly credit limit that applies to this user's one-time purchases.
#[derive(Debug, Clone, Serialize, ToSchema)]
pub struct CreditPurchaseSnapshot {
/// Most credits charged to the card on file per UTC calendar month, from
/// automatic reloads and one-time purchases together, in customer cents.
/// `null` when the payer set no limit; team members always have one.
pub monthly_limit_cents: Option<i64>,
/// Charged this month so far, including charges that may still collect.
pub committed_cents: i64,
/// Start of the next UTC calendar month.
pub resets_at: DateTime<Utc>,
}
/// Lifecycle of an automatic credit reload pushed to Stripe.
#[derive(
Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, strum::Display, strum::EnumString,
)]
#[serde(rename_all = "snake_case")]
#[strum(serialize_all = "snake_case")]
pub enum CreditReloadStatus {
/// Reserved; Stripe not yet confirmed.
Pending,
/// Collected and booked as credits.
Paid,
/// Collection failed and automatic reloads are suspended.
Failed,
}
/// Why a request was refused.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, ToSchema, strum::Display)]
#[serde(rename_all = "snake_case")]
#[strum(serialize_all = "snake_case")]
pub enum DenyReason {
/// The plan's included AI is used up and no credits or overage remain.
AllowanceExhausted,
/// The free plan's monthly AI is used up. Free has no credits or overage;
/// only an upgrade (or the next month) lifts it.
FreeAllowanceExhausted,
/// Overage is on but the payer's per-period cap has been reached.
OverageLimitReached,
/// An overage charge failed; overage is paused until the payer re-enables it.
OveragePaymentFailed,
}
impl DenyReason {
/// A stable machine-readable code for API error bodies.
pub fn code(self) -> &'static str {
match self {
DenyReason::AllowanceExhausted => "ai_allowance_exhausted",
DenyReason::FreeAllowanceExhausted => "ai_free_allowance_exhausted",
DenyReason::OverageLimitReached => "ai_overage_limit_reached",
DenyReason::OveragePaymentFailed => "ai_overage_payment_failed",
}
}
/// A short human-readable explanation.
pub fn message(self) -> &'static str {
match self {
DenyReason::AllowanceExhausted => {
"You've used this period's included AI. Add credits or turn on automatic reload to keep going."
}
DenyReason::FreeAllowanceExhausted => {
"You've used this month's free AI. Upgrade to a paid plan to keep going."
}
DenyReason::OverageLimitReached => {
"You've reached your AI spending limit for this period. Raise the limit or add credits to keep going."
}
DenyReason::OveragePaymentFailed => {
"Your last automatic credit reload didn't go through. Update your payment method and re-enable automatic reload."
}
}
}
}
/// The gate's verdict for one request.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AllowanceDecision {
/// Proceed.
Allow,
/// Refuse, for the given reason.
Deny(DenyReason),
}
/// Calendar-month commitments that consume the payer's automatic reload cap.
#[derive(Debug, Clone, Serialize, ToSchema)]
pub struct AutoReloadMonthlyBudget {
/// Reloads and one-time card purchases paid, pending, or failed with an
/// invoice that can still collect. Customer cents; Checkout purchases do
/// not count.
pub committed_cents: i64,
/// Start of the next UTC calendar month, independently of subscription renewal.
pub resets_at: DateTime<Utc>,
/// Remaining cap cannot fund the minimum automatic reload charge.
pub limit_reached: bool,
}
/// The payer's automatic reload settings, as shown in Billing settings.
#[derive(Debug, Clone, Serialize, ToSchema)]
pub struct AutoReloadSnapshot {
/// Reload once the effective balance drops below this, in customer cents.
pub minimum_balance_cents: i64,
/// Reload the balance back up to this, in customer cents.
pub target_balance_cents: i64,
/// Most reloaded per UTC calendar month, in customer cents. `null` when
/// there is no limit.
pub monthly_spend_limit_cents: Option<i64>,
/// Present for paid finite accounts with a configured monthly cap.
pub monthly_budget: Option<AutoReloadMonthlyBudget>,
/// Whether reloads are paused after a failed reload charge.
pub suspended: bool,
/// Whether reloads will fire: the payer opted in and reloads are not suspended.
pub active: bool,
}
/// The payer's current-period position, as shown in Billing settings and used
/// by the gate.
#[derive(Debug, Clone, Serialize, ToSchema)]
pub struct UsageSnapshot {
/// The plan.
pub tier: PlanTier,
/// Enterprise: never metered.
pub unlimited: bool,
/// The payer for this user's AI.
#[schema(value_type = String)]
pub payer: MacroUserIdStr<'static>,
/// Whether the requesting user is the payer.
pub can_manage_billing: bool,
/// Seats billed to the payer.
pub seats: u32,
/// Period start.
pub period_start: DateTime<Utc>,
/// Period end (exclusive).
pub period_end: DateTime<Utc>,
/// Included AI for this user's seat this period, in cents at provider cost.
pub included_cents: i64,
/// AI used by this user this period, in cents at provider cost.
pub used_cents: i64,
/// Shared payer credits already applied to this period, in customer cents.
pub credits_consumed_cents: i64,
/// Shared prepaid credit balance, in customer cents.
pub credit_balance_cents: i64,
/// Whether prepaid credits belong to the team, including a team with one seat.
pub credits_shared_with_team: bool,
/// Legacy API name for the automatic reload opt-in. Never authorizes direct charges.
pub overage_enabled: bool,
/// Per-period overage cap, in customer cents.
pub overage_limit_cents: i64,
/// Shared overage charged so far this period, in customer cents.
pub overage_charged_cents: i64,
/// Whether overage is paused after a failed charge.
pub overage_suspended: bool,
/// Automatic credit reload settings. `active` means the payer opted in and
/// reloads are not suspended.
pub auto_reload: AutoReloadSnapshot,
/// Team-wide usage beyond per-seat allowances, at the overage markup, that
/// is not yet covered by shared credits or charges (awaiting settlement).
/// Customer cents.
pub uncovered_cents: i64,
/// Cost cents of usage this seat may still consume: its remaining allowance
/// plus whatever shared credit and overage headroom pays for at the markup.
/// 0 when blocked.
pub remaining_cents: i64,
/// Why requests are refused right now, if they are.
#[serde(skip_serializing_if = "Option::is_none")]
pub blocked_reason: Option<DenyReason>,
/// The monthly credit limit for one-time purchases charged to the card on
/// file. Present for paid, metered users, payer and team members alike.
#[serde(skip_serializing_if = "Option::is_none")]
pub credit_purchase: Option<CreditPurchaseSnapshot>,
}
/// Errors raised by the billing domain.
#[derive(Debug, Error)]
pub enum BillingError {
/// Only the payer may change billing settings or buy credits.
#[error("only the account that pays for this plan can change its billing")]
NotPayer,
/// Credits and overage need a paid plan.
#[error("a paid plan is required")]
FreePlan,
/// Not one of [`CREDIT_PACKS_CENTS`].
#[error("credit amount is not an offered pack")]
InvalidCreditAmount,
/// Outside the allowed overage cap range.
#[error("overage limit must be between ${} and ${}", OVERAGE_LIMIT_MIN_CENTS / 100, OVERAGE_LIMIT_MAX_CENTS / 100)]
InvalidOverageLimit,
/// Direct usage billing has been retired; only prepaid credits fund extra usage.
#[error("direct usage billing is no longer available; use automatic credit reload")]
DirectUsageBillingDisabled,
/// Automatic reload thresholds that could never charge or exceed the
/// offered range ([`AutoReloadThresholds::validate`]).
#[error("invalid automatic reload settings: {0}")]
InvalidAutoReload(&'static str),
/// The purchase would take this month's card charges past the monthly
/// credit limit.
#[error("this purchase would exceed the monthly credit limit")]
CreditLimitExceeded {
/// What can still be charged this month, customer cents.
remaining_cents: i64,
},
/// An earlier purchase is still with the payment provider.
#[error("an earlier credit purchase is still being processed")]
PurchaseInProgress,
/// The payer has no Stripe customer to bill.
#[error("no payment account on file")]
NoStripeCustomer,
/// The payment provider failed.
#[error("payment provider error: {0}")]
Payment(anyhow::Error),
/// Storage failed.
#[error("storage error: {0}")]
Storage(anyhow::Error),
/// Entitlement lookup failed.
#[error("entitlement lookup failed: {0}")]
Entitlement(anyhow::Error),
}
/// Convenience result alias for the crate.
pub type Result<T> = std::result::Result<T, BillingError>;