package com.saas.subscription.service;

import com.saas.subscription.dto.request.CreateSubscriptionPlanRequest;
import com.saas.subscription.dto.response.SubscriptionPlanResponse;

import java.util.List;

/**
 * Service interface for subscription plan management.
 * 
 * Responsibilities:
 * - CRUD operations on subscription plans
 * - Stripe Product/Price creation
 * - Validation and business logic
 */
public interface SubscriptionPlanService {

    /**
     * Create a new subscription plan.
     * 
     * Creates Stripe Product and Price automatically.
     * 
     * @param request Plan details
     * @return Created plan
     * @throws BusinessException if name already exists
     */
    SubscriptionPlanResponse createPlan(CreateSubscriptionPlanRequest request);

    /**
     * Get plan by ID.
     * 
     * @param planId Plan identifier
     * @return Plan details
     * @throws BusinessException if plan not found
     */
    SubscriptionPlanResponse getPlan(Long planId);

    /**
     * Get all active plans.
     * 
     * @return List of plans sorted by price
     */
    List<SubscriptionPlanResponse> getAllActivePlans();

    /**
     * Update existing plan.
     * 
     * Note: Stripe Product name is immutable; only features and description updated.
     * 
     * @param planId Plan to update
     * @param request New details
     * @return Updated plan
     * @throws BusinessException if plan not found
     */
    SubscriptionPlanResponse updatePlan(Long planId, CreateSubscriptionPlanRequest request);

    /**
     * Soft-delete a plan (mark as inactive).
     * 
     * Existing subscriptions continue using deleted plans; new subscriptions cannot.
     * 
     * @param planId Plan to deactivate
     * @throws BusinessException if plan not found
     */
    void deletePlan(Long planId);

    /**
     * Check if plan can be used for new subscriptions.
     * 
     * @param planId Plan to check
     * @return true if active and available
     */
    boolean isPlanAvailable(Long planId);
}