Documentation
¶
Overview ¶
Package costs is commerce's vendor-cost / COGS surface — the mirror of the revenue/usage billing package. Where api/billing answers "what our customers owe US", api/costs answers "what WE owe our vendors" (DigitalOcean compute, the LLM providers we resell) so admin.hanzo.ai can show COGS beside revenue and compute MARGIN.
It reuses commerce's billing primitives verbatim — the same admin gate (middleware.TokenRequired(permission.Admin)), the same per-org datastore namespace (org.Namespaced), the same usage ledger (transaction rows tagged "api-usage") — so cost and revenue read the SAME source of truth and margin is self-consistent.
The HTTP contract, mounted under /v1 (api/api/api.go), admin-gated:
GET /v1/costs?period=YYYY-MM -> {period, vendors:[...], totalCents}
GET /v1/costs/margin?period=YYYY-MM -> {period, revenueCents, cogsCents, marginCents, grossMarginPct, vendors:[...]}
Every credential is read from the environment (KMS-injected — the DO token from the `shared-credentials` secret, the LLM provider keys from `cloud-api-llm-keys`) and NEVER inlined, logged, or returned. When a credential is absent or a vendor API is unreachable the vendor is reported HONESTLY (source label + a zero or estimated amount) — a cost figure is never fabricated.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetCosts ¶
GetCosts returns the per-vendor COGS breakdown for a period.
GET /v1/costs?period=YYYY-MM
Response: {period, vendors:[{vendor,service,amountCents,period,source,note}], totalCents, currency}.
func GetMargin ¶
GetMargin returns revenue (the usage ledger) minus COGS (this package) plus the gross-margin percentage — the MARGIN view for admin.hanzo.ai.
GET /v1/costs/margin?period=YYYY-MM
Revenue is the sum of api-usage charges in the period (what customers paid); COGS is the vendor total. Kept DRY with GetCosts: buildReport returns both the vendor lines and the ledger aggregate, so revenue and cost come from one walk.
func Route ¶
func Route(r router.Router, args ...gin.HandlerFunc)
Route registers the vendor-cost (COGS) endpoints. These are a PLATFORM god-view (what WE pay our vendors across the whole business), so on top of the route-level token gate every handler ALSO enforces requireCostsAdmin — see its doc for why the middleware alone is not enough.
Types ¶
type CostReport ¶
type CostReport struct {
Period string `json:"period"`
Vendors []VendorCost `json:"vendors"`
TotalCents int64 `json:"totalCents"`
Currency string `json:"currency"`
}
CostReport is the /v1/costs response: every vendor line for a period + the total.
type MarginReport ¶
type MarginReport struct {
Period string `json:"period"`
RevenueCents int64 `json:"revenueCents"`
COGSCents int64 `json:"cogsCents"`
MarginCents int64 `json:"marginCents"`
GrossMarginPct float64 `json:"grossMarginPct"`
Vendors []VendorCost `json:"vendors"`
Currency string `json:"currency"`
}
MarginReport is the /v1/costs/margin response: revenue (the usage ledger) minus COGS (this package), plus the gross-margin percentage.
type Source ¶
type Source string
Source labels the provenance of a vendor cost figure.
SourceActual — pulled from the vendor's own billing/usage API (ground truth).
SourceEstimated — computed from our metering ledger x a cost-basis table, or a
placeholder for a vendor not yet wired (amount 0). Honest, not
fabricated: an estimate is labeled as one.
type VendorCost ¶
type VendorCost struct {
Vendor string `json:"vendor"` // e.g. "digitalocean", "openai".
Service string `json:"service"` // e.g. "compute", "llm-inference".
AmountCents int64 `json:"amountCents"` // what WE pay, in cents (>= 0).
Period string `json:"period"` // the billing period, YYYY-MM.
Source Source `json:"source"` // actual | estimated.
Note string `json:"note,omitempty"` // honest context (e.g. "no DO_API_TOKEN configured").
Currency string `json:"currency"` // always "usd" today.
}
VendorCost is one line of what we paid a vendor for a service in a period.
Source Files