import Stripe from "stripe";
import { StripeService } from "../../stripe/services/stripe.service";
/**
 * Stripe Subscription API Service
 *
 * Manages Stripe subscription operations including creation, updates, cancellations, pausing/resuming,
 * and proration previews. Handles subscription lifecycle and billing changes.
 *
 * @example
 * ```typescript
 * const subscription = await stripeSubscriptionApiService.createSubscription({
 *   stripeCustomerId: 'cus_abc123',
 *   priceId: 'price_xyz789',
 *   paymentMethodId: 'pm_def456',
 * });
 * ```
 */
export declare class StripeSubscriptionApiService {
    private readonly stripeService;
    constructor(stripeService: StripeService);
    /**
     * Create a new subscription for a customer
     *
     * @param params - Subscription creation parameters
     * @param params.stripeCustomerId - The Stripe customer ID
     * @param params.priceId - The Stripe price ID to subscribe to
     * @param params.paymentMethodId - Default payment method ID (optional)
     * @param params.trialPeriodDays - Number of trial days (optional, ignored if trialEnd is set)
     * @param params.trialEnd - Unix timestamp for trial end (optional, takes precedence over trialPeriodDays)
     * @param params.metadata - Additional metadata (optional)
     * @returns Promise resolving to the created subscription with expanded invoice and payment intent
     * @throws {StripeError} If subscription creation fails
     *
     * @example
     * ```typescript
     * const subscription = await service.createSubscription({
     *   stripeCustomerId: 'cus_abc123',
     *   priceId: 'price_xyz789',
     *   trialPeriodDays: 14,
     * });
     * ```
     */
    createSubscription(params: {
        stripeCustomerId: string;
        priceId: string;
        paymentMethodId?: string;
        trialPeriodDays?: number;
        trialEnd?: number;
        metadata?: Record<string, string>;
        promotionCode?: string;
    }): Promise<Stripe.Subscription>;
    /**
     * Retrieve a subscription by ID
     *
     * @param subscriptionId - The Stripe subscription ID
     * @returns Promise resolving to the subscription with expanded invoice and payment method
     * @throws {StripeError} If retrieval fails
     *
     * @example
     * ```typescript
     * const subscription = await service.retrieveSubscription('sub_abc123');
     * ```
     */
    retrieveSubscription(subscriptionId: string): Promise<Stripe.Subscription>;
    /**
     * Update an existing subscription
     *
     * @param params - Subscription update parameters
     * @param params.subscriptionId - The subscription ID to update
     * @param params.priceId - New price ID to change plan (optional)
     * @param params.prorationBehavior - How to handle proration (optional)
     * @param params.metadata - Updated metadata (optional)
     * @returns Promise resolving to the updated subscription
     * @throws {StripeError} If update fails
     *
     * @example
     * ```typescript
     * const subscription = await service.updateSubscription({
     *   subscriptionId: 'sub_abc123',
     *   priceId: 'price_new789',
     *   prorationBehavior: 'create_prorations',
     * });
     * ```
     */
    updateSubscription(params: {
        subscriptionId: string;
        priceId?: string;
        prorationBehavior?: Stripe.SubscriptionUpdateParams.ProrationBehavior;
        metadata?: Record<string, string>;
        promotionCode?: string;
        trialEnd?: "now";
    }): Promise<Stripe.Subscription>;
    /**
     * Cancel a subscription
     *
     * @param subscriptionId - The subscription ID to cancel
     * @param cancelAtPeriodEnd - If true, cancels at period end; if false, cancels immediately (default: true)
     * @returns Promise resolving to the updated/canceled subscription
     * @throws {StripeError} If cancellation fails
     *
     * @example
     * ```typescript
     * // Cancel at end of billing period
     * const subscription = await service.cancelSubscription('sub_abc123', true);
     *
     * // Cancel immediately
     * const subscription = await service.cancelSubscription('sub_abc123', false);
     * ```
     */
    cancelSubscription(subscriptionId: string, cancelAtPeriodEnd?: boolean): Promise<Stripe.Subscription>;
    /**
     * Pause a subscription
     *
     * @param subscriptionId - The subscription ID to pause
     * @param resumeAt - Optional date to automatically resume the subscription
     * @returns Promise resolving to the paused subscription
     * @throws {StripeError} If pausing fails
     *
     * @example
     * ```typescript
     * const resumeDate = new Date('2025-02-01');
     * const subscription = await service.pauseSubscription('sub_abc123', resumeDate);
     * ```
     */
    pauseSubscription(subscriptionId: string, resumeAt?: Date): Promise<Stripe.Subscription>;
    /**
     * Resume a paused subscription
     *
     * @param subscriptionId - The subscription ID to resume
     * @returns Promise resolving to the resumed subscription
     * @throws {StripeError} If resuming fails
     *
     * @example
     * ```typescript
     * const subscription = await service.resumeSubscription('sub_abc123');
     * ```
     */
    resumeSubscription(subscriptionId: string): Promise<Stripe.Subscription>;
    /**
     * Preview proration amounts for a subscription plan change
     *
     * @param subscriptionId - The subscription ID
     * @param newPriceId - The new price ID to preview
     * @returns Promise resolving to the upcoming invoice preview with proration details
     * @throws {StripeError} If preview fails
     *
     * @example
     * ```typescript
     * const preview = await service.previewProration('sub_abc123', 'price_new789');
     * console.info('Proration amount:', preview.amount_due);
     * ```
     */
    previewProration(subscriptionId: string, newPriceId: string): Promise<Stripe.Invoice>;
    /**
     * List all subscriptions for a customer
     *
     * @param stripeCustomerId - The Stripe customer ID
     * @param status - Filter by subscription status (optional)
     * @returns Promise resolving to array of subscriptions
     * @throws {StripeError} If listing fails
     *
     * @example
     * ```typescript
     * // List all subscriptions
     * const subscriptions = await service.listSubscriptions('cus_abc123');
     *
     * // List only active subscriptions
     * const activeSubscriptions = await service.listSubscriptions('cus_abc123', 'active');
     * ```
     */
    listSubscriptions(stripeCustomerId: string, status?: Stripe.SubscriptionListParams.Status): Promise<Stripe.Subscription[]>;
}
//# sourceMappingURL=stripe-subscription-api.service.d.ts.map