// --- ASA GENERATED START ---
// Billing types for payments-basic module.
// --- ASA GENERATED END ---

// --- USER CODE START ---

/**
 * Subscription State Machine (research-validated)
 *
 * States and their access implications:
 * - active:     ✅ Full access
 * - past_due:   ✅ Still has access (Stripe retrying payment)
 * - trialing:   ✅ Full access (trial period)
 * - incomplete: ⚠️  Limited access (initial payment pending)
 * - canceled:   ❌ Access revoked
 * - unpaid:     ❌ Access revoked (all retries failed)
 *
 * IMPORTANT: past_due = "still has access". Most apps incorrectly
 * check only for 'active' and lock out paying users during dunning.
 */
export type SubscriptionStatus =
  | 'active'
  | 'past_due'
  | 'trialing'
  | 'incomplete'
  | 'canceled'
  | 'unpaid';

export const ACCESS_GRANTED_STATUSES: SubscriptionStatus[] = [
  'active',
  'past_due',
  'trialing',
];

export const ACCESS_REVOKED_STATUSES: SubscriptionStatus[] = [
  'canceled',
  'unpaid',
];

export function hasActiveAccess(status: SubscriptionStatus): boolean {
  return ACCESS_GRANTED_STATUSES.includes(status);
}

export interface Subscription {
  id: string;
  user_id: string;
  stripe_customer_id: string | null;
  stripe_subscription_id: string | null;
  plan: string;
  status: SubscriptionStatus;
  current_period_end: string | null;
  cancel_at_period_end: boolean;
  created_at: string;
  updated_at: string;
}

export interface PlanLimitCheck {
  allowed: boolean;
  currentUsage: number;
  limit: number;
  plan: string;
}

/**
 * Stripe webhook event types handled by payments-basic.
 */
export type HandledStripeEvent =
  | 'checkout.session.completed'
  | 'customer.subscription.created'
  | 'customer.subscription.updated'
  | 'customer.subscription.deleted'
  | 'invoice.paid'
  | 'invoice.payment_failed';

/**
 * Processed webhook event record for idempotency.
 */
export interface WebhookEventRecord {
  event_id: string;
  event_type: string;
  processed_at: string;
}

// --- USER CODE END ---
