Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Billing simplification — DX-focused refactor (umbrella tracker)

Aperta
  • Qualcosa non va?
#1,540 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Refactoring
Chiarezza
Abbastanza chiara
Stato di attività
Tranquilla
Stack tecnologico
go
Ambito
api, backend, developer-experience, payments

Direzione di ricerca

Consideralo un tracker ombrello, non una singola modifica: scegli un'attività indipendente come T3–T8, quindi inizia dai servizi di billing, dagli handler o dall'area billing/provider indicati e pertinenti per quell'attività. Usa l'obiettivo dichiarato come definizione di completato; la catena di provider più ampia, i test e le modifiche RPC sono attività dipendenti separate.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Goal

Make Frontier's Stripe billing easy to read, modify, and integrate with — for new contributors, existing devs, and microservice / SDK integrators. This is a developer-experience pass, not a feature-completeness pass.

Why now

A new dev currently has to internalise 17 domain types, ~38 billing handler RPCs, two checkout codepaths that produce subscriptions through different logic, Stripe SubscriptionSchedule phase arithmetic, plan inference from Stripe subscription items, and a tangled admin-vs-tenant surface — before they can confidently modify anything. Service-layer unit-test coverage for the four largest billing services (subscription, customer, invoice, checkout) is zero today because Stripe is tightly coupled.

What changes (high-level)

  • Provider interface. All Stripe calls move behind billing/provider.Provider. A NoopProvider ships so contributors can run billing locally without a Stripe key, signing secret, or webhook tunnel.
  • Single subscription activation path. CreateCheckout and DelegatedCheckout collapse to one internal SubscriptionService.Activate(); checkout becomes a payment-collection method, not a subscription-creation method.
  • Local plan_id authoritative. Subscription stops inferring its plan by intersecting Stripe subscription-item product IDs (the most fragile code in the system).
  • Flat subscription state. Stripe SubscriptionSchedule arithmetic moves behind the Provider; service layer deals in CurrentPlanID / NextPlanID / ChangeEffectiveAt.
  • Admin vs tenant taxonomy. Six catalogue-mutation RPCs that live on FrontierService but check IsSuperUser move to AdminService. Every billing RPC gets an @auth proto comment.
  • RPC consolidation. ~8–10 duplicate RPCs deprecated, then removed.
  • Data-modelling fixes. Explicit provider_registered_at state replaces the ProviderID == \"\" sentinel; billing_prices becomes append-only (immutable prices); pending_invoice_items flush queue prevents lost line items on Stripe outages.
  • Docs. Stripe ownership diagram, integration cookbook, subscription state machine, authorization table.
  • Service-layer tests. ≥ 60 % coverage for the four big services, enabled by NoopProvider.

Tasks (23 total)

Independent — startable now:

  • T3. Magic strings → typed constants (\"frontier\", seat behaviours, intervals, metadata keys)
  • T4. Fix four known billing TODOs + emit audit records on subscription mutations
  • T5. Authorization audit — document required role per RPC; add @auth proto comments
  • T6. Stripe ownership boundary doc — what Frontier owns vs Stripe vs dual
  • T7a. Move handler business logic to services (non-checkout pieces); dedupe duplicate transforms
  • T8. `billing/provider` interface — Phase 1: `CustomerProvider` extraction

Startable after one open-question check:

  • T1. RPC inventory + deprecation annotations (verify `CreatePlan` upsert behaviour first)
  • T2. Stop `PlanID` inference from Stripe items (audit groups-deprecation overlap first)

Provider-interface chain:

  • T9. `billing/provider` interface — Phase 2: Subscription / Invoice / Checkout providers
  • T10. `NoopProvider` + `billing.provider=noop` config
  • T11. Unify `CreateCheckout` + `DelegatedCheckout` into one activation path
  • T12. Flatten subscription state machine (CurrentPlanID / NextPlanID / ChangeEffectiveAt)
  • T13. Break up `checkout.Create()` (282 lines) and `checkout.Apply()` (187 lines)
  • T14. Break up `ChangePlan()` (182) / `UpdateProductQuantity()` (134); dedupe `shouldChange*Quantity`
  • T18. Service-layer unit tests via NoopProvider (≥ 60 % coverage)
  • T20. State-machine + checkout-flow + reconciliation diagrams
  • T21. Explicit `provider_registered_at` state for Customer / Subscription
  • T22. Immutable Prices — treat updates as new rows
  • T23. `pending_invoice_items` flush queue (durable line-item enqueue)

Gated behind RPC inventory or other deps:

  • T7b. Move plan-change conflict validation from handler to service (after T11)
  • T15. Merge `Usage` into `Credit.Transaction` (decision-gated: usage strategic?)
  • T16. Remove deprecated RPCs (after T1 + one SDK release cycle)
  • T17. Admin vs Non-Admin taxonomy — rename / split service; move misclassified RPCs
  • T19. Integration cookbook — six common jobs, Go + JS snippets

Quantified targets

Artefact Today Target
`billing/subscription/service.go` 1,194 lines < 600
`billing/checkout/service.go` 1,066 lines < 600
Service files importing `*stripe.Client` 5 0
Stripe-schedule helpers in service layer 6 0
`"frontier"` magic strings in billing service code 17 0
Service-layer unit-test coverage (4 services) 0 % ≥ 60 %
`FrontierService` billing RPCs checking `IsSuperUser` 6 0
Handler RPCs in `billing_*.go` ~38 ≤ 30

Out of scope (deferred to follow-up milestones)

Materialised entitlements (perf), outbound billing webhooks (after `core/webhook/` spike), explicit entitlement model, usage event pipeline, billing event-sourcing, currency on Transaction, credit expiry, dunning, MRR / churn reporting, inbound webhook DLQ, swapping Stripe for another production provider.

Open questions to resolve

  1. `CreatePlan` actually upsert safely today? (gates T1)
  2. Any billing code touching `core/group/` that breaks on group deprecation? (gates T2 / T12)
  3. Backwards-compat policy: rename RPCs through deprecation, or alias forever? (sizes T17)
  4. Usage-based billing strategic in next two quarters? (gates T15)
  5. Multi-currency on roadmap in next two quarters? (currently out of scope)
  6. `AdminService/RevertBillingUsage` uses `IsAuthorized(Platform, …)` instead of `IsSuperUser` like sibling admin RPCs — intentional or oversight? (resolved as part of T17)
Lingua principale
Go
Stelle
344
Fork
47
Merge medio
2g 16h
PR unite (30g)
33

Preparare l'ambiente

Non abbiamo ancora controllato i file di configurazione di questo progetto. Parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di raystack/frontier

Tutte le issue di raystack/frontier

Issue simili

Altre issue su Go

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.