Arcadia/arcadia-cloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Phase 3: quote engine

Browse Source 
ArcadiaCloud.Quoting.quote/3 — turns a plan version + addons + usage into
itemized pricing. The same function serves both provisioning-time
projection (with projected usage) and month-end invoicing (with actual
metered usage), so the two can never disagree on the math.

A quote has:
- recurring     — plan base + addon lines (fixed monthly)
- first_invoice — recurring prorated to a mid-month start date
                  (fraction = days_remaining / days_in_month)
- overage       — usage beyond plan+addon allowance, billed in arrears
- all_in_monthly_cents

Overage computation: per plan_item, effective allowance =
included_qty + summed addon qty for the same resource_kind. Overage =
max(0, used - allowance), clamped by hard_cap_qty. overage_price_cents
is per overage_unit; a @unit_factor map converts base-unit usage to
overage units (e.g. 1k_tokens divides token counts by 1000).

Lines are uniform maps (kind/resource_kind/description/qty/unit/
unit_price_cents/amount_cents/meta) — the invoice rollup chunk will
persist them near-verbatim as invoice_lines.

addon_fields/1 accepts either a catalog Addon (projection from the
catalog) or a SubscriptionAddon (actual, using snapshotted price/qty).

API: POST /api/v1/quote { plan_code, addons[], projected_usage{},
starts_on } — tenant-facing pre-provisioning price preview.

Smoke verified against seeded plans:
- Studio bare: $50/mo, no overage.
- Studio + storage_50gb, mid-month start 2026-05-20, projected usage:
  recurring $57.50; first invoice prorated 12/31 -> $22.25; overage
  LLM 500k-token $5.00 + Spaces 50GB $1.00 (the addon correctly lifted
  the Spaces allowance 100->150 GB); droplet_hours exactly at allowance
  produced no line; all-in $63.50/mo.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Giuliano Silvestro
2026-05-20 15:15:48 +10:00
parent aee5e07b26
commit 33e604b84a
3 changed files with 253 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

199
lib/arcadia_cloud/quoting.ex Normal file
View File

@@ -0,0 +1,199 @@
defmodule ArcadiaCloud.Quoting do
@moduledoc """
The quote engine — turns a plan version + addons + usage into itemized
pricing.
Used two ways:
- projection: at provisioning time, with *projected* usage, to show a
tenant what they'd likely pay.
- actual: at month-end, with *actual* metered usage, to produce the
invoice line set.
Same function, different usage input — so projection and invoicing can
never disagree on the math.
A quote has:
recurring — plan base + addon lines (fixed monthly)
first_invoice — recurring prorated to a mid-month start date
overage — usage beyond plan+addon allowance (billed arrears)
all_in_monthly_cents
Lines are maps: %{kind, resource_kind, description, qty, unit,
unit_price_cents, amount_cents, meta}.
kind ∈ "plan_base" | "addon" | "overage".
"""
alias ArcadiaCloud.Catalog.{PlanVersion, Addon}
alias ArcadiaCloud.Billing.SubscriptionAddon
# base unit → overage unit divisor. overage_price_cents is per overage
# unit; usage + included_qty are in the resource's base unit.
@unit_factor %{
"hour" => 1,
"gb_month" => 1,
"gb" => 1,
"zone" => 1,
"1k_tokens" => 1000,
"snapshot" => 1
}
@doc """
Build a quote.
plan_version — a PlanVersion preloaded with :items
addons — list of Addon or SubscriptionAddon structs
opts:
:usage — map of resource_kind => used qty (nil = skip overage)
:starts_on — Date; if set, first_invoice prorates from this date
"""
def quote(%PlanVersion{} = plan_version, addons, opts \\ []) do
currency = plan_version.currency
base_lines = [plan_base_line(plan_version) | addon_lines(addons)]
monthly_base = sum_amounts(base_lines)
overage_lines =
case opts[:usage] do
nil -> []
usage -> compute_overage(plan_version, addons, usage)
end
overage_total = sum_amounts(overage_lines)
%{
currency: currency,
recurring: %{lines: base_lines, monthly_total_cents: monthly_base},
first_invoice: first_invoice(base_lines, monthly_base, opts[:starts_on]),
overage: %{lines: overage_lines, monthly_total_cents: overage_total},
all_in_monthly_cents: monthly_base + overage_total
}
end
# ---- base lines -----------------------------------------------------------
defp plan_base_line(%PlanVersion{} = pv) do
%{
kind: "plan_base",
resource_kind: nil,
description: "Plan base",
qty: 1,
unit: "month",
unit_price_cents: pv.base_price_cents,
amount_cents: pv.base_price_cents,
meta: %{plan_version_id: pv.id, version: pv.version}
}
end
defp addon_lines(addons) do
Enum.map(addons, fn addon ->
{code, kind, qty, price} = addon_fields(addon)
%{
kind: "addon",
resource_kind: kind,
description: "Addon: #{code}",
qty: 1,
unit: "month",
unit_price_cents: price,
amount_cents: price,
meta: %{addon_code: code, included_qty: to_number(qty)}
}
end)
end
defp addon_fields(%Addon{} = a), do: {a.code, a.resource_kind, a.qty, a.price_cents}
defp addon_fields(%SubscriptionAddon{} = sa),
do: {sa.addon_id, sa.resource_kind, sa.qty, sa.price_cents}
# ---- overage --------------------------------------------------------------
defp compute_overage(%PlanVersion{items: items}, addons, usage) do
addon_allowance = addon_allowance_by_kind(addons)
items
|> Enum.flat_map(fn item ->
kind = item.resource_kind
included = to_number(item.included_qty)
allowance = included + Map.get(addon_allowance, kind, 0)
used = usage_for(usage, kind)
billable_used = apply_cap(used, item.hard_cap_qty)
overage_qty = max(billable_used - allowance, 0)
if overage_qty > 0 and is_integer(item.overage_price_cents) do
factor = Map.get(@unit_factor, item.overage_unit, 1)
units = overage_qty / factor
amount = round(units * item.overage_price_cents)
[
%{
kind: "overage",
resource_kind: kind,
description: "#{kind} overage",
qty: overage_qty,
unit: item.overage_unit,
unit_price_cents: item.overage_price_cents,
amount_cents: amount,
meta: %{
included_qty: included,
addon_qty: Map.get(addon_allowance, kind, 0),
allowance: allowance,
used: used,
capped: billable_used != used
}
}
]
else
[]
end
end)
end
defp addon_allowance_by_kind(addons) do
Enum.reduce(addons, %{}, fn addon, acc ->
{_code, kind, qty, _price} = addon_fields(addon)
Map.update(acc, kind, to_number(qty), &(&1 + to_number(qty)))
end)
end
defp apply_cap(used, nil), do: used
defp apply_cap(used, cap), do: min(used, to_number(cap))
defp usage_for(usage, kind) do
(Map.get(usage, kind) || Map.get(usage, to_string(kind)) || 0) |> to_number()
end
# ---- proration ------------------------------------------------------------
defp first_invoice(base_lines, monthly_base, nil) do
%{period_start: nil, period_end: nil, prorated_total_cents: monthly_base, lines: base_lines}
end
defp first_invoice(base_lines, _monthly_base, %Date{} = starts_on) do
days_in_month = Date.days_in_month(starts_on)
days_remaining = days_in_month - starts_on.day + 1
fraction = days_remaining / days_in_month
prorated_lines =
Enum.map(base_lines, fn line ->
prorated = round(line.amount_cents * fraction)
%{line | amount_cents: prorated, meta: Map.put(line.meta, :proration_fraction, fraction)}
end)
%{
period_start: starts_on,
period_end: Date.end_of_month(starts_on),
prorated_total_cents: sum_amounts(prorated_lines),
lines: prorated_lines
}
end
# ---- helpers --------------------------------------------------------------
defp sum_amounts(lines), do: Enum.reduce(lines, 0, &(&1.amount_cents + &2))
defp to_number(%Decimal{} = d), do: Decimal.to_float(d)
defp to_number(n) when is_number(n), do: n
defp to_number(s) when is_binary(s), do: String.to_integer(s)
defp to_number(nil), do: 0
end