feat(billing): Add deposit ledger protos to the contract service

proto/sentry_protos/billing/v1/services/contract/ledger/v1/endpoint_get_ledger_balance.proto

@@ -0,0 +1,16 @@
+syntax = "proto3";
+
+package sentry_protos.billing.v1.services.contract.ledger.v1;
+
+message GetLedgerBalanceRequest {
+  uint64 organization_id = 1;
+  string account_id = 2;
+}
+
+message GetLedgerBalanceResponse {
+  // Paid deposits minus withdrawals, plus adjustments. Zero for an account
+  // with no entries.
+  int64 balance_cents = 1;
+  // Deposits whose invoices are not paid yet. Not part of balance_cents.
+  int64 pending_deposit_cents = 2;
+}

proto/sentry_protos/billing/v1/services/contract/ledger/v1/endpoint_list_ledger_entries.proto

@@ -0,0 +1,22 @@
+syntax = "proto3";
+
+package sentry_protos.billing.v1.services.contract.ledger.v1;
+
+import "sentry_protos/billing/v1/services/contract/ledger/v1/ledger_entry.proto";
+
+// Lists an account's entries, newest first.
+message ListLedgerEntriesRequest {
+  uint64 organization_id = 1;
+  string account_id = 2;
+  // Return only entries older than this one. Pass next_cursor from the
+  // previous page.
+  optional uint64 before_entry_id = 3;
+  // Defaults to 100 when zero; capped at 1000.
+  uint32 limit = 4;
+}
+
+message ListLedgerEntriesResponse {
+  repeated LedgerEntry entries = 1;
+  // Unset on the last page.
+  optional uint64 next_cursor = 2;
+}

proto/sentry_protos/billing/v1/services/contract/ledger/v1/endpoint_record_ledger_adjustment.proto

@@ -0,0 +1,29 @@
+syntax = "proto3";
+
+package sentry_protos.billing.v1.services.contract.ledger.v1;
+
+import "sentry_protos/billing/v1/services/contract/ledger/v1/ledger_entry.proto";
+
+// Records a manual correction. A refund is a negative adjustment: the refunded
+// invoice stays paid, so its deposit still counts and the adjustment cancels
+// it.
+message RecordLedgerAdjustmentRequest {
+  uint64 organization_id = 1;
+  string account_id = 2;
+  // Must not be zero.
+  int64 amount_cents = 3;
+  // Unique per organization and account_id. A repeated key writes nothing
+  // and returns the existing entry with created=false.
+  string idempotency_key = 4;
+  // Required, so that the ledger shows why the balance changed.
+  string description = 5;
+  // The invoice the adjustment refers to, e.g. the refunded one.
+  optional uint64 invoice_id = 6;
+}
+
+message RecordLedgerAdjustmentResponse {
+  LedgerEntry entry = 1;
+  bool created = 2;
+  // The balance after the adjustment.
+  int64 balance_cents = 3;
+}

proto/sentry_protos/billing/v1/services/contract/ledger/v1/endpoint_record_ledger_withdrawal.proto

@@ -0,0 +1,28 @@
+syntax = "proto3";
+
+package sentry_protos.billing.v1.services.contract.ledger.v1;
+
+import "sentry_protos/billing/v1/services/contract/ledger/v1/ledger_entry.proto";
+
+// Takes credit out of an account. The full amount is always withdrawn, even
+// when that makes the balance negative.
+message RecordLedgerWithdrawalRequest {
+  uint64 organization_id = 1;
+  string account_id = 2;
+  // Must be positive.
+  uint64 amount_cents = 3;
+  // Unique per organization and account_id. A repeated key writes nothing
+  // and returns the existing entry with created=false.
+  string idempotency_key = 4;
+  // The contract whose usage the withdrawal pays for. Defaults to the
+  // organization's current contract.
+  optional uint64 contract_id = 5;
+  optional string description = 6;
+}
+
+message RecordLedgerWithdrawalResponse {
+  LedgerEntry entry = 1;
+  bool created = 2;
+  // The balance after the withdrawal.
+  int64 balance_cents = 3;
+}

proto/sentry_protos/billing/v1/services/contract/ledger/v1/ledger_deposit.proto

@@ -0,0 +1,16 @@
+syntax = "proto3";
+
+package sentry_protos.billing.v1.services.contract.ledger.v1;
+
+// Credit that an off-cycle invoice buys. The deposit is written in the same
+// transaction as the invoice, so a crash can not leave a charge without its
+// credit. It counts toward the balance once the invoice is paid.
+message LedgerDeposit {
+  // 1 to 64 characters.
+  string account_id = 1;
+  // The credit bought. Must be positive and at most the invoice's total
+  // before tax.
+  uint64 amount_cents = 2;
+  // At most 256 characters.
+  optional string description = 3;
+}

proto/sentry_protos/billing/v1/services/contract/ledger/v1/ledger_entry.proto

@@ -0,0 +1,37 @@
+syntax = "proto3";
+
+package sentry_protos.billing.v1.services.contract.ledger.v1;
+
+import "google/protobuf/timestamp.proto";
+
+enum LedgerEntryType {
+  LEDGER_ENTRY_TYPE_UNSPECIFIED = 0;
+  // Credit bought through an invoice. It adds to the balance only after the
+  // invoice is paid.
+  LEDGER_ENTRY_TYPE_DEPOSIT = 1;
+  // Credit used, e.g. the credit-only usage tallied at contract rollover.
+  LEDGER_ENTRY_TYPE_WITHDRAWAL = 2;
+  // A manual correction, such as a refund. It can be positive or negative.
+  LEDGER_ENTRY_TYPE_ADJUSTMENT = 3;
+}
+
+// One row of an account's transaction history. Entries are append-only.
+message LedgerEntry {
+  uint64 id = 1;
+  uint64 organization_id = 2;
+  // Identifies one balance among the organization's accounts, e.g. "seer".
+  string account_id = 3;
+  // The organization's contract when the entry was written, if it had one.
+  optional uint64 contract_id = 4;
+  // Signed: deposits are positive, withdrawals are negative.
+  int64 amount_cents = 5;
+  LedgerEntryType entry_type = 6;
+  // The invoice that pays for a deposit, or that an adjustment refers to.
+  optional uint64 invoice_id = 7;
+  google.protobuf.Timestamp date_added = 8;
+  optional string idempotency_key = 9;
+  optional string description = 10;
+  // False only for a deposit whose invoice is not paid yet. Such an entry
+  // does not count toward the balance.
+  bool counts_toward_balance = 11;
+}

proto/sentry_protos/billing/v1/services/contract/v2/endpoint_create_off_cycle_invoice.proto

@@ -3,6 +3,7 @@ syntax = "proto3";
 package sentry_protos.billing.v1.services.contract.v2;
 
 import "sentry_protos/billing/v1/common/v1/address.proto";
+import "sentry_protos/billing/v1/services/contract/ledger/v1/ledger_deposit.proto";
 import "sentry_protos/billing/v1/services/contract/v1/invoice.proto";
 
 // Writes an organization-scoped invoice outside of any contract, ready for the
@@ -29,6 +30,9 @@ message CreateOffCycleInvoiceRequest {
   // The tax document the provider opened for this invoice, if any.
   optional string tax_transaction_code = 8;
   bool is_reverse_charge = 9;
+  // Required. The credit the invoice buys. A repeated idempotency_key returns
+  // the existing invoice and writes no second deposit.
+  sentry_protos.billing.v1.services.contract.ledger.v1.LedgerDeposit ledger_deposit = 10;
 }
 
 message CreateOffCycleInvoiceResponse {

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

@@ -3,6 +3,7 @@ syntax = "proto3";
 package sentry_protos.billing.v1.services.invoicer.v1;
 
 import "sentry_protos/billing/v1/common/v1/stripe_verification.proto";
+import "sentry_protos/billing/v1/services/contract/ledger/v1/ledger_deposit.proto";
 import "sentry_protos/billing/v1/services/contract/v1/invoice.proto";
 
 // Bills an organization for line items another service has priced, outside of
@@ -26,6 +27,9 @@ message BillOffCycleInvoiceRequest {
   // requesting service chooses: FAILURE_POLICY_RETRY_ONLY leaves account
   // status alone and makes the service responsible for non-payment.
   sentry_protos.billing.v1.services.contract.v1.FailurePolicy failure_policy = 6;
+  // Required. The credit the invoice buys. The deposit exists before the
+  // charge starts.
+  sentry_protos.billing.v1.services.contract.ledger.v1.LedgerDeposit ledger_deposit = 7;
 }
 
 message BillOffCycleInvoiceResponse {

rust/src/_include.rs

@@ -35,6 +35,11 @@ pub mod sentry_protos {
                     }
                 }
                 pub mod contract {
+                    pub mod ledger {
+                        pub mod v1 {
+                            include!("sentry_protos.billing.v1.services.contract.ledger.v1.rs");
+                        }
+                    }
                     pub mod v1 {
                         include!("sentry_protos.billing.v1.services.contract.v1.rs");
                     }