Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

8.7 KB
Raw Blame
//! Subscription checkout policy, independent of HTTP and the payment provider.

use std::{collections::HashMap, future::Future};

use macro_user_id::user_id::MacroUserIdStr;
use teams::domain::model::SeatPlan;
use thiserror::Error;

#[cfg(test)]
mod test;

/// The introductory offer is granted by the server, never supplied as a duration by clients.
pub const ONBOARDING_TRIAL_DAYS: u8 = 30;

/// Facts across the customer's entire subscription history, including canceled subscriptions.
#[derive(Debug, Default, Clone, Copy)]
pub struct SubscriptionHistory {
    /// A nonterminal subscription must be recovered or managed, never replaced.
    pub has_existing_subscription: bool,
    /// Any previous subscription makes the customer ineligible for an introductory trial.
    pub has_previous_subscription: bool,
}

impl SubscriptionHistory {
    pub(crate) fn trial_eligible(self) -> bool {
        !self.has_existing_subscription && !self.has_previous_subscription
    }
}

/// Whether the authenticated customer can receive the introductory Pro trial.
#[derive(Debug, serde::Serialize, utoipa::ToSchema)]
#[serde(rename_all = "camelCase")]
pub struct TrialEligibility {
    /// Confirmed against the same subscription history used during checkout.
    pub eligible: bool,
    /// An existing subscription requires management instead of a new checkout.
    pub existing_subscription: bool,
}

/// Authenticated purchase intent; the caller cannot choose a customer or price ID.
pub struct CheckoutRequest<'a> {
    /// Identity established by the authentication boundary.
    pub user_id: MacroUserIdStr<'a>,
    /// Requested seat plan.
    pub plan: SeatPlan,
    /// Request the introductory Premium trial instead of immediate billing.
    pub onboarding_trial: bool,
    /// Return destination after successful checkout.
    pub success_url: String,
    /// Return destination after cancellation.
    pub cancel_url: String,
    /// Optional promotion for a standard paid checkout.
    pub discount: Option<String>,
    /// Team ownership and attribution supplied by the authenticated boundary.
    pub metadata: HashMap<String, String>,
}

/// Billing terms approved by the service.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CheckoutTerms {
    /// Charge the configured plan price immediately.
    Paid,
    /// Collect a payment method now and begin billing after the introductory period.
    Trial,
}

/// Confirms the granted terms as well as the hosted destination.
pub struct CheckoutResult {
    /// Opaque hosted checkout URL.
    pub url: String,
    /// The trial duration actually granted by the server.
    pub trial_days: Option<u8>,
}

/// Errors that callers can distinguish without understanding the provider.
#[derive(Debug, Error)]
pub enum CheckoutError<E> {
    /// The account has no billing customer.
    #[error("User does not have a stripe id")]
    MissingCustomer,
    /// A second subscription must not be created.
    #[error("You already have a subscription. Open Manage in Settings → Billing to update it.")]
    AlreadySubscribed,
    /// Never silently replace an advertised trial with an immediate charge.
    #[error("The 30-day trial is only available for your first Premium subscription")]
    TrialUnavailable,
    /// The requested plan is not currently sold.
    #[error("This plan is not available yet")]
    PlanUnavailable,
    /// An explicitly supplied promotion must be valid.
    #[error("Invalid promo code")]
    PromoCodeNotFound,
    /// Persistence or provider failure, preserving its original type and cause.
    #[error(transparent)]
    Gateway(E),
}

/// Billing capabilities used by the checkout service. Provider IDs stay opaque.
pub trait CheckoutGateway: Send + Sync {
    /// Validated provider customer identity.
    type Customer: Send + Sync;
    /// Validated provider promotion identity.
    type Promotion: Send + Sync;
    /// Adapter error retaining the original failure.
    type Error: std::error::Error + Send + Sync + 'static;

    /// Resolve the authenticated account's billing customer.
    fn customer(
        &self,
        user: &MacroUserIdStr<'_>,
    ) -> impl Future<Output = Result<Option<Self::Customer>, Self::Error>> + Send;
    /// Include every page and every subscription status.
    fn history(
        &self,
        customer: &Self::Customer,
    ) -> impl Future<Output = Result<SubscriptionHistory, Self::Error>> + Send;
    /// Read the offer already granted by the invite domain.
    fn invite_promotion(
        &self,
        user: &MacroUserIdStr<'_>,
    ) -> impl Future<Output = Result<Option<String>, Self::Error>> + Send;
    /// Resolve an active promotion code.
    fn promotion(
        &self,
        code: &str,
    ) -> impl Future<Output = Result<Option<Self::Promotion>, Self::Error>> + Send;
    /// Create a checkout with exactly the approved terms and optional promotion.
    fn create_session(
        &self,
        customer: Self::Customer,
        request: CheckoutRequest<'_>,
        terms: CheckoutTerms,
        promotion: Option<Self::Promotion>,
    ) -> impl Future<Output = Result<String, Self::Error>> + Send;
}

/// Orchestrates eligibility, existing invite offers, and provider checkout creation.
pub struct CheckoutService<G> {
    gateway: G,
}

impl<G: CheckoutGateway> CheckoutService<G> {
    /// Compose a service with its billing adapter.
    pub fn new(gateway: G) -> Self {
        Self { gateway }
    }

    /// Read eligibility without creating a checkout or granting an offer.
    #[tracing::instrument(skip_all, err)]
    pub async fn trial_eligibility(
        &self,
        user: &MacroUserIdStr<'_>,
    ) -> Result<TrialEligibility, CheckoutError<G::Error>> {
        let customer = self
            .gateway
            .customer(user)
            .await
            .map_err(CheckoutError::Gateway)?
            .ok_or(CheckoutError::MissingCustomer)?;
        let history = self
            .gateway
            .history(&customer)
            .await
            .map_err(CheckoutError::Gateway)?;
        Ok(TrialEligibility {
            eligible: history.trial_eligible(),
            existing_subscription: history.has_existing_subscription,
        })
    }

    /// Create a paid checkout or a code-free first-subscription trial.
    pub async fn create(
        &self,
        request: CheckoutRequest<'_>,
    ) -> Result<CheckoutResult, CheckoutError<G::Error>> {
        if !SeatPlan::PURCHASABLE.contains(&request.plan) {
            return Err(CheckoutError::PlanUnavailable);
        }
        let customer = self
            .gateway
            .customer(&request.user_id)
            .await
            .map_err(CheckoutError::Gateway)?
            .ok_or(CheckoutError::MissingCustomer)?;
        let history = self
            .gateway
            .history(&customer)
            .await
            .map_err(CheckoutError::Gateway)?;
        if history.has_existing_subscription {
            return Err(CheckoutError::AlreadySubscribed);
        }
        let terms = if request.onboarding_trial {
            if request.plan != SeatPlan::Premium || !history.trial_eligible() {
                return Err(CheckoutError::TrialUnavailable);
            }
            CheckoutTerms::Trial
        } else {
            CheckoutTerms::Paid
        };

        // The introductory trial is automatic and does not stack with discount codes.
        // Preserve existing invite/explicit-promotion behavior for standard purchases.
        let promotion = if terms == CheckoutTerms::Trial {
            None
        } else if let Some(code) = request.discount.as_deref() {
            Some(
                self.gateway
                    .promotion(code)
                    .await
                    .map_err(CheckoutError::Gateway)?
                    .ok_or(CheckoutError::PromoCodeNotFound)?,
            )
        } else {
            self.invite_promotion(&request.user_id).await
        };
        let url = self
            .gateway
            .create_session(customer, request, terms, promotion)
            .await
            .map_err(CheckoutError::Gateway)?;
        Ok(CheckoutResult {
            url,
            trial_days: (terms == CheckoutTerms::Trial).then_some(ONBOARDING_TRIAL_DAYS),
        })
    }

    async fn invite_promotion(&self, user: &MacroUserIdStr<'_>) -> Option<G::Promotion> {
        let offer = async {
            match self.gateway.invite_promotion(user).await? {
                Some(code) => self.gateway.promotion(&code).await,
                None => Ok(None),
            }
        }
        .await;
        match offer {
            Ok(promotion) => promotion,
            Err(error) => {
                tracing::error!(error=?error, "failed to apply optional invite promotion");
                None
            }
        }
    }
}