Struct SubscriptionBillingService 

pub struct SubscriptionBillingService { /* private fields */ }

High-level provider-neutral billing facade for authorized host commands.

The service owns orchestration and retry classification. Hosts retain authentication, authorization, offer rows, credentials, abuse admission, and the transaction/outbox boundary supplied at construction.

Implementations

impl SubscriptionBillingService

pub async fn enroll( &self, command: EnrollSubscription, ) -> Result<SubscriptionEnrollmentPaymentResult, SubscriptionBillingServiceError>

Runs one complete initial-subscription payment boundary.

Matching replay and conflict are resolved before host admission. No database transaction or lock is held across host admission, gateway resolution, readiness I/O, or the one provider mutation.

impl SubscriptionBillingService

pub async fn charge_host_target( &self, command: ChargeHostTarget, ) -> Result<HostChargePaymentResult, SubscriptionBillingServiceError>

Charges one host-owned target through the canonical attempt ledger.

Target eligibility and economics are supplied by the configured host extension. No transaction or target lock spans gateway I/O.

pub async fn apply_reconciled_host_charge_outcome( &self, billing_scope_id: BillingScopeId, attempt_id: PaymentAttemptId, outcome: &GatewayPaymentOutcome, ) -> Result<HostChargePaymentResult, SubscriptionBillingServiceError>

Applies an exact-query outcome to one host charge without resubmission.

impl SubscriptionBillingService

pub async fn replace_payment_method( &self, command: ReplaceSubscriptionPaymentMethod, ) -> Result<SubscriptionEnrollmentPaymentResult, SubscriptionBillingServiceError>

Runs one complete stored payment-method replacement boundary.

impl SubscriptionBillingService

pub async fn apply_reconciled_outcome( &self, billing_scope_id: BillingScopeId, attempt_id: PaymentAttemptId, outcome: &GatewayPaymentOutcome, ) -> Result<SubscriptionEnrollmentPaymentResult, SubscriptionBillingServiceError>

Applies an already-observed provider outcome without another submission.

Reconciliation enters the same application authority as foreground enrollment but reconstructs its secret-free reservation from the exact durable attempt and canonical gateway account.

impl SubscriptionBillingService

pub async fn recover( &self, command: RecoverSubscriptionPayment, ) -> Result<SubscriptionEnrollmentPaymentResult, SubscriptionBillingServiceError>

Runs one complete subscriber-initiated recovery payment boundary.

The command carries only the owner, requested plan/configuration, and memory-only token/contact. Reservation derives the exact due period, amount, subscription, and payment-state snapshot under lock.

impl SubscriptionBillingService

pub async fn renew( &self, command: ChargeRenewal, ) -> Result<SubscriptionRenewalOutcome, SubscriptionBillingServiceError>

Runs one complete automatic recurring-renewal boundary.

Stale, future, canceled, paced, and contended work is a successful no-op. A dispatch routed to a service with the wrong durable gateway account mode fails with GatewayConfigurationChanged; callers must route it to the matching service rather than silently discard it. The operation never invokes end-user admission or the live offer store and never holds a database lock across provider I/O.

impl SubscriptionBillingService

pub async fn cancel( &self, command: CancelSubscription, ) -> Result<CancelSubscriptionOutcome, SubscriptionBillingServiceError>

Cancels one exact subscriber-owned subscription lifecycle.

Admission runs before any database work. When cancellation changes canonical state, its event is appended on the same host-prepared transaction before that transaction commits. Replays and semantic blockers commit without an event. This operation performs no provider resolution or provider I/O.

pub async fn claim_discount( &self, command: SubscriptionDiscountClaim, ) -> Result<SubscriptionDiscountClaimOutcome, SubscriptionBillingServiceError>

Claims an eligible discount code for one exact subscriber aggregate.

Admission happens before database work and the offer lock, claim, and commit use one local transaction. The operation does not resolve a gateway or perform provider I/O.

pub async fn clear_discount( &self, command: ClearSubscriptionDiscount, ) -> Result<SubscriptionDiscountClearOutcome, SubscriptionBillingServiceError>

Clears the saved discount claim for one exact subscriber aggregate.

Admission happens before database work. The command has no provider identity and this operation performs neither gateway resolution nor provider I/O.

impl SubscriptionBillingService

pub fn new( pool: PgPool, offers: Arc<dyn SubscriptionOfferStore>, resolver: Arc<dyn GatewayResolver>, admission: Arc<dyn EndUserMutationAdmission>, coordinator: Arc<dyn BillingTransactionCoordinator>, ) -> Self

Creates a service without the optional host-charge target capability.

pub fn with_required_gateway_account_mode( self, mode: GatewayAccountMode, ) -> Self

Requires an exact gateway account mode before any provider mutation.

The default is GatewayAccountMode::Live. Selecting GatewayAccountMode::Test permits test-mode mutations and rejects a live account before submission. Hosts should bind this requirement to their trusted deployment environment, never to end-user input.

This service setting does not automatically partition entitlement or billing-portal reads. Test-mode subscriptions are ordinary paid subscriptions to the domain model and can satisfy Entitlement::permits_product_access; constrain EntitlementQuery and EntitlementGuard separately when modes share a database, and enforce any remaining environment isolation before granting production access.

pub fn with_host_charge_targets( self, targets: Arc<dyn HostChargeTargetStore>, ) -> Self

Adds the optional host-charge target store to this service instance.

Trait Implementations

impl Clone for SubscriptionBillingService

fn clone(&self) -> SubscriptionBillingService

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.