@criapix/saas-assinaturas-client/src/types/Subscription.ts

SDK JavaScript/TypeScript para o AssinaturasService - Sistema de gestão de assinaturas SaaS com processamento de pagamentos de faturas (cartão, PIX, débito), gerenciamento de métodos de pagamento, pagamentos recorrentes e análise de falhas de pagamento

import { SubscriptionStatus, BillingCycle } from '../enums';

export interface SubscriptionResponse {
  id: string;
  customerId: string;
  customerName: string;
  subscriptionPlanId: string;
  subscriptionPlanName: string;
  startDate: string;
  endDate?: string;
  status: SubscriptionStatus;
  billingCycle: BillingCycle;
  quantity: number;
  totalAmount: number;
  defaultInvoiceDueDayOfMonth: number;
  trialExpiresAt?: string;
  suspendedAt?: string;
  suspensionReason?: string;
  cancellationReason?: string;
  createdAt: string;
  updatedAt?: string;
}

export interface CreateSubscriptionRequest {
  customerId: string;
  subscriptionPlanId: string;
  quantity: number;
  billingCycle: BillingCycle;
  startTrial: boolean;
  defaultInvoiceDueDayOfMonth?: number;
}

export interface UpdateSubscriptionRequest {
  quantity?: number;
  defaultInvoiceDueDayOfMonth?: number;
}

export interface SubscriptionFilterRequest {
  customerId?: string;
  subscriptionPlanId?: string;
  status?: SubscriptionStatus;
  page?: number;
  pageSize?: number;
}

/**
 * Customer payment information for invoice processing
 */
export interface CustomerPaymentInfo {
  name: string;
  email: string;
  documentNumber: string;
  phone?: string;
  address?: string;
  city?: string;
  state?: string;
  zipCode?: string;
}

/**
 * Request to activate subscription with payment
 */
export interface ActivateSubscriptionWithPaymentRequest {
  invoiceId: string;
  cardToken: string;
  cardHolderName: string;
  cardExpiryDate: string;
  customer: CustomerPaymentInfo;
}

/**
 * Response after subscription activation with payment
 */
export interface SubscriptionActivationResponse {
  success: boolean;
  subscriptionId: string;
  paymentId?: string;
  invoiceId: string;
  paymentStatus: string;
  message: string;
  activatedAt: string;
}

/**
 * Request to update payment method for a subscription
 */
export interface UpdatePaymentMethodRequest {
  /**
   * Optional invoice ID to process payment while updating payment method
   * If not provided, will only update the payment method without charging
   */
  invoiceId?: string;

  /**
   * New card token from MercadoPago
   */
  cardToken: string;

  /**
   * Card holder name
   */
  cardHolderName: string;

  /**
   * Card expiry date - supports multiple formats:
   * - MM/YY (e.g., "11/30") - Recommended for user input
   * - MM/YYYY (e.g., "11/2030")
   * - ISO 8601 (e.g., "2030-11-30T00:00:00Z")
   *
   * The SDK automatically normalizes the date to ISO 8601 format before sending to the API.
   */
  cardExpiryDate: string;

  /**
   * Customer payment information
   */
  customer: CustomerPaymentInfo;
}