feat(billing): Add BillingService base class and service method decorator

[volokluev]

Human Stuff

This code was generated using the file in src/sentry/billing/platform/INTENTION.md. This is meant as a starting point for us to build from. No existing logic is modified, the services do not exist yet.

I checked over the implementation of the base class and tests and it seems sane to me.

Reviewer task

1. Does the intention align with what you think of as the project direction?
2. Does the interface seem reasonable enough as the primitive we will use to call services.

If yes, click approve

Robot Stuff

Implement core primitives for the new billing platform to establish the foundation for service-oriented architecture where billing services communicate through well-defined protobuf interfaces.

What's included

This PR adds:

• BillingService base class: Foundation for all billing services with uniform construction (no __init__ arguments)
• @service_method decorator: Provides observability, type validation, and structured logging for service methods
• Comprehensive test suite: 15 tests demonstrating usage patterns and validating functionality
• Documentation: README files explaining design principles and usage

Why these changes

The existing billing code in getsentry/services/billing has grown into a spaghetti codebase. This PR starts the rewrite by establishing well-defined service boundaries and interfaces.

Following the principles in INTENTION.md:

• Services have uniform construction (no __init__ arguments)
• All interfaces use protobuf messages for strong typing
• Service methods automatically log start/success/error events with timing
• Services will eventually delegate to external RPC endpoints

Architecture

The folder structure enforces separation:

• core/ - Contains core primitives, no application logic
• services/ - Each service in its own directory, no cross-service imports

Services communicate exclusively through the BillingService abstraction, making it straightforward to later move implementations to external services.

Next steps

Future PRs will:

1. Add individual billing services (contract, usage, etc.)
2. Define protobuf schemas for service interfaces
3. Gradually migrate existing billing logic to the new architecture

[volokluev]

no relative imports

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}