feat(billing): Add ApplySponsorship checkout endpoint

proto/sentry_protos/billing/v1/services/checkout/v1/endpoint_apply_sponsorship.proto

@@ -0,0 +1,17 @@
+syntax = "proto3";
+
+package sentry_protos.billing.v1.services.checkout.v1;
+
+import "sentry_protos/billing/v1/common/v1/sponsored_type.proto";
+
+// Moves an organization's contract onto the package a sponsorship grants,
+// starting a new term.
+message ApplySponsorshipRequest {
+  uint64 organization_id = 1;
+  sentry_protos.billing.v1.common.v1.SponsoredType sponsored_type = 2;
+}
+
+message ApplySponsorshipResponse {
+  // The invoice that closes the contract the sponsorship replaced.
+  uint64 invoice_id = 1;
+}

proto/sentry_protos/billing/v1/services/invoicer/v1/endpoint_bill_contract_change.proto

@@ -12,7 +12,9 @@ import "sentry_protos/billing/v1/services/contract/v1/invoice.proto";
 // the credit for unused time on the current plan itself, settles accrued
 // pay-as-you-go usage at the current contract's rates, applies monetary grants
 // and sales tax, closes the current contract immediately, and opens the new
-// contract with the supplied change applied.
+// contract with the supplied change applied. When the credit for unused time
+// exceeds the invoice's charges, as it can on a move onto a cheaper package,
+// the surplus is added to the new contract's balance rather than forgiven.
 message BillContractChangeRequest {
   uint64 contract_id = 1;
   // The plan-change line items billed alongside accrued usage; they take the

proto/sentry_protos/billing/v1/services/package/v1/package_catalog.proto

@@ -2,12 +2,22 @@ syntax = "proto3";
 
 package sentry_protos.billing.v1.services.package.v1;
 
+import "sentry_protos/billing/v1/common/v1/sponsored_type.proto";
+
 // How a customer can start on a package.
 enum AcquisitionMode {
   ACQUISITION_MODE_UNSPECIFIED = 0;
   ACQUISITION_MODE_SELF_SERVE = 1; // customer can sign up on their own
 }
 
+// The package a sponsorship grants.
+message SponsoredPackageOption {
+  sentry_protos.billing.v1.common.v1.SponsoredType sponsored_type = 1;
+
+  // uid of the granted option within the catalog's `packages`.
+  string package_uid = 2;
+}
+
 // A package a customer can subscribe to, such as the Team or Business package.
 // Carries only what a catalog needs beyond a bare reference; fetch full details
 // (title, pricing, supported intervals) with GetPackage / GetPackages.
@@ -36,4 +46,10 @@ message PackageCatalog {
 
   // uid of the default option within `packages`: the one checkout pre-selects.
   string default_package_uid = 3;
+
+  // The package each sponsorship grants, at most one per sponsored type. A
+  // sponsored type with no entry cannot be granted from this catalog, such as a
+  // partner sponsorship provisioned by the partner. Empty on catalogs of older
+  // package generations, which no longer take on new sponsorships.
+  repeated SponsoredPackageOption sponsored_packages = 4;
 }

rust/src/sentry_protos.billing.v1.services.checkout.v1.rs

@@ -1,4 +1,19 @@
 // This file is @generated by prost-build.
+/// Moves an organization's contract onto the package a sponsorship grants,
+/// starting a new term.
+#[derive(Clone, Copy, PartialEq, Eq, Hash, ::prost::Message)]
+pub struct ApplySponsorshipRequest {
+    #[prost(uint64, tag = "1")]
+    pub organization_id: u64,
+    #[prost(enumeration = "super::super::super::common::v1::SponsoredType", tag = "2")]
+    pub sponsored_type: i32,
+}
+#[derive(Clone, Copy, PartialEq, Eq, Hash, ::prost::Message)]
+pub struct ApplySponsorshipResponse {
+    /// The invoice that closes the contract the sponsorship replaced.
+    #[prost(uint64, tag = "1")]
+    pub invoice_id: u64,
+}
 /// Schedules an organization's contract to end when the current billing period
 /// closes. The contract is downgraded onto the free package at the next
 /// rollover, and the reservations, PAYG budgets, and soft caps in effect are

rust/src/sentry_protos.billing.v1.services.invoicer.v1.rs

@@ -5,7 +5,9 @@
 /// the credit for unused time on the current plan itself, settles accrued
 /// pay-as-you-go usage at the current contract's rates, applies monetary grants
 /// and sales tax, closes the current contract immediately, and opens the new
-/// contract with the supplied change applied.
+/// contract with the supplied change applied. When the credit for unused time
+/// exceeds the invoice's charges, as it can on a move onto a cheaper package,
+/// the surplus is added to the new contract's balance rather than forgiven.
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct BillContractChangeRequest {
     #[prost(uint64, tag = "1")]

rust/src/sentry_protos.billing.v1.services.package.v1.rs

@@ -222,6 +222,15 @@ pub struct GetPackageResponse {
     #[prost(message, optional, tag = "1")]
     pub package_config: ::core::option::Option<PackageConfig>,
 }
+/// The package a sponsorship grants.
+#[derive(Clone, PartialEq, Eq, Hash, ::prost::Message)]
+pub struct SponsoredPackageOption {
+    #[prost(enumeration = "super::super::super::common::v1::SponsoredType", tag = "1")]
+    pub sponsored_type: i32,
+    /// uid of the granted option within the catalog's `packages`.
+    #[prost(string, tag = "2")]
+    pub package_uid: ::prost::alloc::string::String,
+}
 /// A package a customer can subscribe to, such as the Team or Business package.
 /// Carries only what a catalog needs beyond a bare reference; fetch full details
 /// (title, pricing, supported intervals) with GetPackage / GetPackages.
@@ -253,6 +262,12 @@ pub struct PackageCatalog {
     /// uid of the default option within `packages`: the one checkout pre-selects.
     #[prost(string, tag = "3")]
     pub default_package_uid: ::prost::alloc::string::String,
+    /// The package each sponsorship grants, at most one per sponsored type. A
+    /// sponsored type with no entry cannot be granted from this catalog, such as a
+    /// partner sponsorship provisioned by the partner. Empty on catalogs of older
+    /// package generations, which no longer take on new sponsorships.
+    #[prost(message, repeated, tag = "4")]
+    pub sponsored_packages: ::prost::alloc::vec::Vec<SponsoredPackageOption>,
 }
 /// How a customer can start on a package.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, ::prost::Enumeration)]