/**
 * TrialUiState types — trial-expiry-conversion-ui spec (Task 2).
 *
 * Defines the client-side state union and derivation contract for the trial
 * lifecycle UI. The pure deriveTrialState() function is implemented in
 * apps/zync-app/src/hooks/use-trial-state.ts.
 *
 * Precedence (highest first):
 *   past_due → grace → expired → ending_soon → trial_active → none
 *
 * 'grace' and 'past_due' are yielded to upstream zync-subscription banners;
 * this spec renders UI only for 'ending_soon', 'expired', 'trial_active', and 'none'.
 */
import type { TenantTier } from './enums'

// ---------------------------------------------------------------------------
// ZyncSubscriptionStatus — canonical status values matching schema.ts CHECK
// ---------------------------------------------------------------------------

export type ZyncSubscriptionStatus = 'active' | 'trialing' | 'past_due' | 'canceled'

// ---------------------------------------------------------------------------
// TrialUiState union
// ---------------------------------------------------------------------------

export type TrialUiState =
  | 'none'          // not trialing, not expired, not grace, not past_due
  | 'trial_active'  // status='trialing', trial_ends_at > now()+3d
  | 'ending_soon'   // status='trialing', now() < trial_ends_at <= now()+3d
  | 'grace'         // upstream-owned: grace_period_started_at IS NOT NULL (yield)
  | 'past_due'      // upstream-owned: status='past_due' (yield)
  | 'expired'       // status='active', tier='freelancer', trial_ends_at set, ack not stamped

// ---------------------------------------------------------------------------
// TrialStateInput — normalized input shape consumed by the derivation function
// ---------------------------------------------------------------------------

export interface TrialStateInput {
  /** Upstream union: 'active'|'trialing'|'past_due'|'canceled' */
  status: ZyncSubscriptionStatus
  /** 'freelancer'|'business'|'enterprise'|'white_label' */
  tier: TenantTier
  /** ISO timestamp; upstream trial_ends_at */
  trialEndsAt: string | null
  /** ISO timestamp; upstream grace_period_started_at */
  gracePeriodStartedAt: string | null
  /** ISO timestamp; this spec's trial_expiry_ack_at column */
  trialExpiryAckAt: string | null
  /** Date.now() injected for testability */
  now: number
}

// ---------------------------------------------------------------------------
// TrialStateResult — the derived output
// ---------------------------------------------------------------------------

export interface TrialStateResult {
  state: TrialUiState
  /** ceil((trialEndsAt - now)/86_400_000) for trial states; null otherwise */
  daysLeft: number | null
  /** true when state==='ending_soon' (drives amber+bold banner styling) */
  urgent: boolean
}