BusDK Update

Billing-integraatio valvoo entitlementit ja quota-ikkunat

bus-integration-billing omistaa Busin provider-neutralin billing-tilan: status-vastaukset, checkout- ja portal-orchestrationin, subscription-päivitykset, entitlement-päätökset ja usage export -tilan.

Maksupalvelu jää event-boundaryn taakse. Sama worker voi käyttää paikallista deterministic-taustaa tai julkaista provider-pyynnöt erilliselle Stripe-integraatiolle.

28.4.2026bus-integration-billingentitlementsquotas

Tiiviisti

TL;DR

Worker kuuntelee bus.billing.*.request-eventtejä ja vastaa korreloiduilla response-eventeillä.
bus.billing.subscription.update aktivoi tai sulkee paid featuret provider-neutralista subscription-tilasta.
bus.billing.entitlement.check.request palauttaa billing_required- tai quota_exceeded-päätöksen ennen paid API -backendin herätystä.
Usage export käyttää idempotency keytä, joten retry ei lähetä samaa meter-eventtiä eikä kasvata quota-laskuria kahdesti.
PostgreSQL-tausta luo taulut account-, entitlement-, provider-event-, usage-export- ja quota-tilalle.

Billing workerin self-test näyttää, että moduuli on ajettava itsenäisenä prosessina ilman ulkoista maksupalvelua:

$ bus-integration-billing --self-test

bus-integration-billing self-test OK

Event-sopimus on provider-neutralin billing-kerroksen ydin:

bus.billing.status.request             -> bus.billing.status.response
bus.billing.checkout_session.request   -> bus.billing.checkout_session.response
bus.billing.portal_session.request     -> bus.billing.portal_session.response
bus.billing.entitlement.check.request  -> bus.billing.entitlement.check.response
bus.billing.usage.export.request       -> bus.billing.usage.export.response

Status-vastaus voi palauttaa suoraan loppukäyttäjän komennolle tarvittavan ohjeen. Kun billing puuttuu, response sisältää billing_required-tilan ja komennon bus billing setup. Kun planin quota ylittyy, entitlement-vastaus palauttaa quota_exceeded-syyn, käyttöikkunan tiedot ja mahdollisen upgrade-planin.

{
  "allowed": false,
  "reason": "quota_exceeded",
  "command": "bus billing setup",
  "recommended_plan": "llm_plus"
}

Quota-konfiguraatio on oma provider-neutral JSON-tiedosto. Sama plan voi sisältää useita yhtäaikaisia ikkunoita, esimerkiksi minuutti- ja kuukausirajan samalle llm:proxy-featurelle:

{
  "plans": {
    "llm_basic": [
      {"feature": "llm:proxy", "meter_event_name": "bus_llm_tokens", "window": "minute", "limit": 1200, "upgrade_plan_id": "llm_plus"},
      {"feature": "llm:proxy", "meter_event_name": "bus_llm_tokens", "window": "month", "limit": 1000000, "upgrade_plan_id": "llm_plus"}
    ]
  }
}

Subscription-päivitys on myös provider-neutral. Stripe tai muu maksupalvelu julkaisee lopulta bus.billing.subscription.update -eventin, jossa on event_id, account_id, providerin nimi, providerin asiakas- ja subscription-tunnisteet, subscriptionin tila ja enabled feature -scopet. active avaa listatut featuret. past_due, canceled, incomplete ja tuntemattomat tilat sulkevat paid-feature-pääsyn.

Usage export yhdistää billingin ja quota-laskennan. LLM usage voi tulla usage_recorded-tapahtumana, jossa määrä saadaan joko suoraan quantity-kentästä tai OpenAI-tyylisen datan token-kentistä. Onnistunut export kasvattaa kaikki planiin sopivat quota bucketit. Sama idempotency key ei lähetä providerille uutta meter-eventtiä eikä kasvata bucketia uudelleen.

Provider-backend valitaan asetuksella BUS_BILLING_PROVIDER_BACKEND=local|events. events-tilassa checkout, portal ja meter export kääntyvät provider-kohtaisiksi tapahtumiksi, kuten bus.stripe.checkout_session.create.request ja bus.stripe.meter_event.record.request. Näin entitlement-politiikka pysyy Busin omassa billing-workerissä, vaikka maksupalvelun protokolla vaihtuisi myöhemmin.

Workerin nykyinen sopimus on kuvattu bus-integration-billing-dokumentaatiossa. Loppukäyttäjän HTTP- ja CLI-pinta on erikseen Billing API -providerin ja bus-billing-komennon dokumentaatiossa.