free -> trialing -> active
free -> active
active -> cancelled_at_period_end -> free
trialing -> free (trial revoked)
active -> active (paid upgrade/same-tier change)

active -> used (via order.paid or reconciliation)
active -> expired (via timeout or reconciliation)
active -> revoked (via manual revoke or reconciliation)
active -> failed (via Polar creation failure)

export async function evaluateAndCreateDiscount(userId, trigger, context = {}) {
  if (!config.discount?.enabled) {
    return { created: false, reason: "system_disabled" };
  }

  // Check eligibility
  const eligibilityResult = await checkEligibility(userId, trigger, context);
  if (!eligibilityResult.eligible) {
    return { created: false, reason: eligibilityResult.reason };
  }

  // Check for existing active discount (race condition guard)
  const existingActive = await getActiveDiscount(userId);
  if (existingActive) {
    return { created: false, reason: "already_exists", discount: existingActive };
  }

  const rule = getDiscountRule(trigger);
  const targetPlan = rule.targetPlan || "growth";
  const percentOff = rule.percentOff ?? 20;
  const expiresAt = calculateExpirationDate(DISCOUNT_VALIDITY_DAYS);

  // Step 1: Create Polar discount first
  let paymentDiscountId;
  try {
    paymentDiscountId = await createPolarDiscountWithMetadata({
      percentOff,
      targetPlan,
      expiresAt,
      description: `User discount: ${trigger} (${percentOff}% off ${targetPlan})`,
      userId,
      trigger,
      version: "1.0"
    });
  } catch (err) {
    return { created: false, reason: "polar_discount_failed" };
  }

  // Step 2: Create DB record
  let discount;
  try {
    discount = await createDiscountRecord({
      userId,
      paymentProvider: "polar",
      paymentDiscountId,
      trigger,
      targetPlan,
      discountType: rule.percentOff ? "percent_off" : "amount_off",
      discountValue: percentOff,
      expiresAt,
      status: DISCOUNT_STATUS_ACTIVE,
      metadata: context
    });
  } catch (err) {
    // Compensation: Polar discount exists but DB failed
    logger.error({ userId, trigger, paymentDiscountId, err }, "DB creation failed after Polar success");
    return { created: false, reason: "creation_failed", polarDiscountId: paymentDiscountId };
  }

  // Step 3: Send email notification
  if (paymentDiscountId && discount.status === DISCOUNT_STATUS_ACTIVE) {
    try {
      const user = await User.findById(userId).select("email name").lean();
      if (user?.email) {
        const { html, text, subject } = discountOfferEmail(user, trigger, rule, context);
        await enqueueEmailEvent({
          eventId: `discount-offer:${userId}:${discount._id}`,
          type: "discount-offer",
          to: user.email,
          subject,
          text,
          html
        });
      }
    } catch (err) {
      logger.warn({ userId, discountId: discount._id, err }, "Failed to send discount email");
    }
  }

  return { created: true, discount };
}

export async function resolveApplicableDiscount(userId, selectedPlan) {
  const activeDiscount = await getActiveDiscount(userId);

  if (!activeDiscount) {
    return { discount: null, discountId: null, shouldAttach: false };
  }

  // Discount is restricted to its target plan in Polar (restrict_to)
  const discountAppliesToSelectedPlan = String(activeDiscount.targetPlan) === String(selectedPlan);

  if (!discountAppliesToSelectedPlan) {
    return { discount: activeDiscount, discountId: null, shouldAttach: false };
  }

  const paymentDiscountId = activeDiscount.paymentDiscountId || null;
  if (!paymentDiscountId) {
    return { discount: activeDiscount, discountId: null, shouldAttach: false };
  }

  return {
    discount: activeDiscount,
    discountId: paymentDiscountId,
    shouldAttach: true
  };
}

export async function handleExhaustedDiscountRetry(err, userId, discount) {
  const code = err?.payload?.error?.code;
  if (code === "discount_usage_limit_exceeded" && discount?._id) {
    await markDiscountUsedSafe(userId, discount._id.toString(), DISCOUNT_TRANSITION_SOURCE.CHECKOUT_ATTACH);
    return { shouldRetry: true, retryDiscountId: null };
  }
  return { shouldRetry: false, retryDiscountId: null };
}

export async function transitionDiscountStatus(discountId, toStatus, source, options = {}) {
  const discount = await UserDiscount.findById(discountId);
  if (!discount) return null;

  const fromStatus = discount.status;

  // No-op if already in target status
  if (fromStatus === toStatus) return discount;

  // Check if transition is valid
  if (!isValidTransition(fromStatus, toStatus, source)) {
    logger.warn({ discountId, fromStatus, toStatus, source }, "Invalid discount transition");
    return null;
  }

  // Prevent transitions from final states
  if (FINAL_DISCOUNT_STATUSES.includes(fromStatus)) {
    return null;
  }

  const update = {
    status: toStatus,
    lastTransitionSource: source,
    lastTransitionAt: new Date()
  };

  if (toStatus === DISCOUNT_STATUS_USED && !discount.usedAt) {
    update.usedAt = new Date();
  }

  // Atomic update with status check
  const updated = await UserDiscount.findOneAndUpdate(
    { _id: discountId, status: fromStatus },
    update,
    { new: true }
  );

  return updated;
}

export async function reconcileDiscountUsage(userId, discountId, polarDiscountId) {
  // Try internal discountId first (most reliable)
  if (discountId) {
    try {
      const marked = await markDiscountUsedSafe(
        userId,
        discountId,
        DISCOUNT_TRANSITION_SOURCE.ORDER_PAID
      );
      if (marked) {
        return { marked: true, discountId };
      }
    } catch (err) {
      logger.warn({ userId, discountId, err }, "Failed to mark discount via internal ID");
    }
  }

  // Fallback to Polar discount_id
  if (polarDiscountId) {
    try {
      const existing = await getDiscountByPaymentId(userId, polarDiscountId);
      if (existing) {
        if (existing.status === DISCOUNT_STATUS_USED || existing.status === DISCOUNT_STATUS_EXPIRED) {
          return { marked: false, discountId: existing._id.toString(), reason: "already_finalized" };
        }
      }

      const marked = await markDiscountUsedByPaymentIdSafe(
        userId,
        polarDiscountId,
        DISCOUNT_TRANSITION_SOURCE.ORDER_PAID
      );
      if (marked) {
        const discount = await getDiscountByPaymentId(userId, polarDiscountId);
        return { marked: true, discountId: discount?._id?.toString() || null };
      }
    } catch (err) {
      logger.warn({ userId, polarDiscountId, err }, "Failed to mark discount via Polar ID");
    }
  }

  return { marked: false, discountId: null, reason: discountId || polarDiscountId ? "reconciliation_failed" : "no_discount_ids" };
}

export async function createCheckoutForNewSubscription(
  billingUserId,
  customerId,
  paidProductId,
  targetPlanId,
  interval,
  userEmail,
  userName
) {
  // Resolve applicable discount using centralized helper
  const { discount: activeDiscount, discountId, shouldAttach } = await resolveApplicableDiscount(
    billingUserId,
    targetPlanId
  );

  // Build checkout metadata with discount ID mapping
  const customData = buildCheckoutMetadata(billingUserId, targetPlanId, interval, activeDiscount);

  const allowTrial = billingUser?.trialUsedAt == null;

  let transaction;
  try {
    transaction = await createPolarCheckout({
      customerId,
      productId: paidProductId,
      metadata: customData,
      discountId: shouldAttach ? discountId : null,
      allowTrial,
      successUrl: `${config.app.frontendBaseUrl}/subscription?success=1`,
      cancelUrl: `${config.app.frontendBaseUrl}/subscription?canceled=1`
    });
  } catch (err) {
    // Handle exhausted discount retry using centralized helper
    const retryResult = await handleExhaustedDiscountRetry(err, billingUserId, activeDiscount);
    if (retryResult.shouldRetry) {
      delete customData.discountId;
      transaction = await createPolarCheckout({
        customerId,
        productId: paidProductId,
        metadata: customData,
        discountId: null,
        allowTrial,
        successUrl: `${config.app.frontendBaseUrl}/subscription?success=1`,
        cancelUrl: `${config.app.frontendBaseUrl}/subscription?canceled=1`
      });
    } else {
      throw err;
    }
  }

  return { checkoutUrl: transaction?.checkout_url || transaction?.url };
}

// In order.paid handler:
const discountId = customData?.discountId ?? null;
const polarDiscountId = data?.discount_id ?? null;

// Reconcile discount usage using unified helper (idempotent)
const reconciliationResult = await reconcileDiscountUsage(userId, discountId, polarDiscountId);
if (reconciliationResult.marked) {
  analyticsTrack(userId, "coupon_used", {
    discountId: reconciliationResult.discountId,
    plan
  });
}

const upgrade = asyncHandler(async (req, res) => {
  const { billingUserId, isSharedContext } = await resolveBillingContext(req);
  if (isSharedContext || String(billingUserId) !== String(req.user._id)) {
    throw new AppError("Only the workspace owner can change subscription", StatusCodes.FORBIDDEN);
  }

  const { interval } = validatePlanChangeInput(req.body.plan, req.body.interval, plans);

  const existingSubscription = await Subscription.findOne({ userId: billingUserId }).lean();
  const currentPlanName = getPlanName(existingSubscription?.plan) || "starter";
  const currentStatus = existingSubscription?.status || "active";

  const { isUpgrade, isDowngrade } = computePlanChangeDirection(currentPlanName, req.body.plan);
  const hasEffectivePolarSub = hasEffectivePolarSubscription(existingSubscription, currentStatus, currentPlanName);

  if (req.body.plan === "starter") {
    const result = await handleSwitchToFree(billingUserId, existingSubscription, hasEffectivePolarSub, req.body.keepChannelId);
    return ok(res, result.data, result.message);
  }

  const billingUser = await User.findById(billingUserId).select("isFoundingMember").lean();
  let useFoundingPricing = billingUser?.isFoundingMember ?? false;

  if (!useFoundingPricing && req.body.plan === "growth") {
    const { checkFoundingMemberEligibility } = await import("../foundingMember/foundingMember.service.js");
    useFoundingPricing = await checkFoundingMemberEligibility("growth", billingUserId, req.user.email);
  }

  const paidProductId = getPaidProductId(req.body.plan, interval, useFoundingPricing);
  if (!paidProductId) {
    throw new AppError("Polar product is not configured", StatusCodes.INTERNAL_SERVER_ERROR);
  }

  if (hasEffectivePolarSub && existingSubscription?.polarSubscriptionId) {
    const subId = existingSubscription.polarSubscriptionId;

    // Trial plan changes are direct patch transitions now
    if (String(currentStatus) === SUBSCRIPTION_STATUS_TRIALING) {
      const result = await handleTrialPlanChange(billingUserId, subId, paidProductId, req.body.plan, interval, currentPlanName);
      return ok(res, result.data, result.message);
    }

    if (String(currentStatus) === "active" && isUpgrade) {
      const result = await handlePaidUpgrade(billingUserId, subId, paidProductId, req.body.plan, interval);
      return ok(res, result.data, result.message);
    }

    if (String(currentStatus) === "active" && isDowngrade) {
      const result = await handlePaidDowngrade(
        billingUserId,
        existingSubscription,
        paidProductId,
        req.body.plan,
        interval,
        currentPlanName
      );
      return ok(res, result.data, result.message);
    }

    const result = await handleSameTierChange(billingUserId, subId, paidProductId, req.body.plan, interval);
    return ok(res, result.data, result.message);
  }

  const customerId = await ensurePolarCustomer(billingUserId, req.user.email, req.user.name);
  const { checkoutUrl } = await createCheckoutForNewSubscription(
    billingUserId,
    customerId,
    paidProductId,
    req.body.plan,
    interval,
    req.user.email,
    req.user.name
  );

  return ok(res, { checkoutUrl }, "Checkout session created");
});

export async function handleTrialPlanChange(
  billingUserId,
  subscriptionId,
  paidProductId,
  targetPlanId,
  interval,
  currentPlanName
) {
  if (String(currentPlanName) === String(targetPlanId)) {
    throw new AppError(
      "You are already on this plan. Your trial will automatically convert to paid when it ends.",
      StatusCodes.BAD_REQUEST
    );
  }

  const existingSub = await Subscription.findOne({ userId: billingUserId }).select("plan currentPeriodEnd status interval polarSubscriptionId").lean();
  const previousPeriod = await getCreditPeriodForUser(billingUserId, existingSub, true);

  // trial_end: "now" ends the trial immediately — Polar charges the new plan price right away.
  // Only sent on trial plan changes; paid upgrade/downgrade/same-tier never include this field.
  await updatePolarSubscription(subscriptionId, { product_id: paidProductId, trial_end: "now" });
  const newPlan = normalizePlan(targetPlanId, paidProductId, interval, getProductIdForPlan);
  await updateSubscriptionPlan(billingUserId, newPlan, interval, null);
  await initializeCreditsForUser(billingUserId, targetPlanId, currentPlanName, { sourcePeriod: previousPeriod }).catch((err) => {
    logger.warn({ userId: billingUserId, planId: targetPlanId, error: err?.message }, "Failed to initialize credits on trial plan change");
  });
  await User.findByIdAndUpdate(billingUserId, { subscriptionPlan: targetPlanId });
  await reconcileChannelEntitlements(billingUserId);

  return { success: true, message: "Plan updated", data: { plan: targetPlanId } };
}

export async function handlePaidDowngrade(
  billingUserId,
  existingSubscription,
  paidProductId,
  targetPlanId,
  interval,
  currentPlanName
) {
  let periodEnd = existingSubscription?.currentPeriodEnd ? new Date(existingSubscription.currentPeriodEnd) : null;
  const now = new Date();

  if (!periodEnd || periodEnd <= now) {
    if (!existingSubscription?.polarSubscriptionId) {
      throw new AppError("Cannot schedule downgrade without active subscription", StatusCodes.BAD_REQUEST);
    }

    try {
      const polarSub = await getPolarSubscription(existingSubscription.polarSubscriptionId);
      const polarPeriodEnd = polarSub?.current_period_end ? new Date(polarSub.current_period_end) : null;
      if (polarPeriodEnd && polarPeriodEnd > now) {
        periodEnd = polarPeriodEnd;
        await updatePeriodEnd(billingUserId, polarPeriodEnd);
      }
    } catch (err) {
      logger.warn(
        { userId: billingUserId, subscriptionId: existingSubscription.polarSubscriptionId, err },
        "Failed to fetch period end from Polar, using DB value"
      );
    }
  }

  if (!periodEnd || periodEnd <= now) {
    throw new AppError("Cannot schedule downgrade: current billing period has ended or is invalid", StatusCodes.BAD_REQUEST);
  }

  const nextPlan = normalizePlan(targetPlanId, paidProductId, interval, getProductIdForPlan);
  await setScheduledDowngrade(billingUserId, nextPlan, periodEnd);
  return {
    success: true,
    message: "Downgrade scheduled for next billing cycle",
    data: { currentPlan: currentPlanName, nextPlan: targetPlanId }
  };
}

export async function handleSoftCancel(billingUserId, subscriptionId) {
  try {
    await cancelPolarSubscription(subscriptionId, { effectiveFrom: "next_billing_period" });
  } catch (err) {
    if (err?.status === 404) {
      logger.warn({ userId: billingUserId, subscriptionId }, "Subscription not found in Polar when canceling");
      throw new AppError("Subscription not found", StatusCodes.NOT_FOUND);
    }
    throw err;
  }

  await updateSubscriptionStatus(billingUserId, {
    status: SUBSCRIPTION_STATUS_CANCELLED_AT_PERIOD_END,
    nextPlan: normalizePlan("starter")
  });
  await cancelScheduledDowngradeJob(billingUserId);
  return { success: true, message: "Subscription scheduled to cancel at period end" };
}

export async function handleResumeSubscription(billingUserId, subscription) {
  const currentPlanName = getPlanName(subscription.plan);
  const currentPlanProductId = getPlanProductId(subscription.plan);
  const interval = subscription.interval || "monthly";

  const now = new Date();
  const trialingEndsAt = subscription.trialingEndsAt ? new Date(subscription.trialingEndsAt) : null;
  const shouldRestoreToTrialing = !!trialingEndsAt && trialingEndsAt > now;

  const productIdToRestore = currentPlanProductId || getProductIdForPlan(currentPlanName, interval);

  if (productIdToRestore && currentPlanName !== "starter") {
    await updatePolarSubscription(subscription.polarSubscriptionId, {
      cancel_at_period_end: false,
      product_id: productIdToRestore
    });
  } else {
    await updatePolarSubscription(subscription.polarSubscriptionId, { cancel_at_period_end: false });
  }

  const update = {
    status: shouldRestoreToTrialing ? SUBSCRIPTION_STATUS_TRIALING : SUBSCRIPTION_STATUS_ACTIVE,
    nextPlan: null,
    scheduledDowngradeAt: null
  };

  if (shouldRestoreToTrialing) {
    update.trialingEndsAt = trialingEndsAt;
  } else {
    update.trialingEndsAt = null;
  }

  if (currentPlanName !== "starter") {
    update.plan = currentPlanProductId
      ? normalizePlan(currentPlanName, currentPlanProductId)
      : normalizePlan(currentPlanName, productIdToRestore, interval, getProductIdForPlan);
  }

  await Subscription.findOneAndUpdate({ userId: billingUserId }, update, { new: true });
  await cancelScheduledDowngradeJob(billingUserId);
  return { success: true, message: "Subscription resumed" };
}

/**
 * Validate subscription state invariants before write
 * @param {object} state - Subscription state to validate
 * @returns {object} { valid: boolean, error: string|null }
 */
function validateSubscriptionState(state, deps) {
  const { getPlanName } = deps;
  const planName = state.plan ? getPlanName(state.plan) : "starter";
  const status = state.status;
  const polarSubscriptionId = state.polarSubscriptionId;
  const price = state.price;

  if (status === "active" && planName !== "starter" && !polarSubscriptionId) {
    return {
      valid: false,
      error: `Invalid state: active paid plan (${planName}) must have polarSubscriptionId`
    };
  }

  if (planName === "starter" || status === "free") {
    if (price !== 0 && price !== null && price !== undefined) {
      return {
        valid: false,
        error: `Invalid state: free plan must have price = 0, got ${price}`
      };
    }
    if (polarSubscriptionId !== null && polarSubscriptionId !== undefined) {
      return {
        valid: false,
        error: "Invalid state: free plan must have polarSubscriptionId = null"
      };
    }
  }

  if (status === "cancelled_at_period_end") {
    if (!polarSubscriptionId) {
      return {
        valid: false,
        error: "Invalid state: cancelled_at_period_end must have polarSubscriptionId"
      };
    }
    if (!state.currentPeriodEnd) {
      return {
        valid: false,
        error: "Invalid state: cancelled_at_period_end must have currentPeriodEnd"
      };
    }
  }

  return { valid: true, error: null };
}

/**
 * Build next subscription state from current state and webhook event
 * This is the single source of truth for state transitions
 * @param {object} currentState - Current subscription state from DB
 * @param {string} eventType - Webhook event type
 * @param {object} eventData - Webhook event data
 * @param {object} derived - Derived values (plan, interval, price, etc.)
 * @returns {object} Next subscription state
 */
function buildNextSubscriptionState(currentState, eventType, eventData, derived, deps) {
  const {
    getPlanName,
    getProductIdForPlan,
    normalizePlan,
    getEffectivePrice
  } = deps;
  const {
    plan,
    interval,
    productId,
    price: webhookPrice,
    currentPeriodEnd,
    trialingEndsAt,
    incomingPolarSubscriptionId
  } = derived;

  const existingPlanName = currentState?.plan ? getPlanName(currentState.plan) : null;
  const existingStatus = currentState?.status;
  const existingNextPlanName = currentState?.nextPlan ? getPlanName(currentState.nextPlan) : null;

  const nextState = {
    ...(currentState || {}),
    _id: undefined,
    __v: undefined
  };

  if (eventType === "order.paid") {
    const planObject = normalizePlan(plan, productId, interval, getProductIdForPlan);
    const subscriptionStatusFromOrder = eventData?.subscription?.status ?? null;
    const isTrialOrder = subscriptionStatusFromOrder === "trialing";
    const orderTrialEnd =
      eventData?.subscription?.trial_end != null ? new Date(eventData.subscription.trial_end) : null;
    const isZeroPrice = webhookPrice === null || webhookPrice === 0;

    const PLAN_HIERARCHY = { starter: 0, go: 1, growth: 2, scale: 3 };
    const incomingPlanName = plan ? getPlanName(planObject) : null;
    const currentTier = existingPlanName ? (PLAN_HIERARCHY[existingPlanName] ?? 0) : 0;
    const incomingTier = incomingPlanName ? (PLAN_HIERARCHY[incomingPlanName] ?? 0) : 0;
    const isDowngrade = incomingTier > 0 && currentTier > 0 && incomingTier < currentTier;
    const isCredit = (webhookPrice !== null && webhookPrice < 0) || (isDowngrade && existingPlanName !== null);

    const shouldApplyNextPlan =
      !isZeroPrice && !isCredit && existingNextPlanName && String(existingNextPlanName) === String(plan);

    const hasScheduledDowngrade = existingNextPlanName && existingNextPlanName !== "starter";
    const periodEnd = currentState?.currentPeriodEnd ? new Date(currentState.currentPeriodEnd) : null;
    const now = new Date();
    const periodNotEnded = periodEnd && periodEnd > now;
    const shouldPreserveCurrentPlan = hasScheduledDowngrade && periodNotEnded && !shouldApplyNextPlan;

    const shouldUpdatePlan = !shouldPreserveCurrentPlan && !isCredit;

    if (shouldUpdatePlan) {
      nextState.plan = planObject;
      nextState.interval = interval ?? undefined;
    }

    const isScheduledToCancel = existingStatus === "cancelled_at_period_end";
    const periodEndForCancel = currentState?.currentPeriodEnd ? new Date(currentState.currentPeriodEnd) : null;
    const cancelPeriodNotEnded = periodEndForCancel && periodEndForCancel > now;
    const shouldPreserveCancellation = isScheduledToCancel && cancelPeriodNotEnded;

    if (!shouldPreserveCancellation) {
      nextState.status = isTrialOrder ? "trialing" : "active";
    } else {
      nextState.status = "cancelled_at_period_end";
    }

    nextState.trialingEndsAt = isTrialOrder
      ? (trialingEndsAt ?? orderTrialEnd ?? currentState?.trialingEndsAt ?? null)
      : null;

    if (shouldPreserveCurrentPlan || isCredit) {
      // Keep existing price when preserving the current plan or when this event is a credit.
    } else if (isTrialOrder) {
      nextState.price = 0;
    } else if (webhookPrice !== null && Number.isFinite(webhookPrice) && webhookPrice > 0) {
      nextState.price = webhookPrice;
    } else {
      const planName = getPlanName(planObject);
      nextState.price = getEffectivePrice(planName, interval);
    }

    const subscriptionId = eventData?.subscription_id ?? eventData?.subscription?.id ?? incomingPolarSubscriptionId;
    if (subscriptionId) {
      nextState.polarSubscriptionId = subscriptionId;
    }
    if (eventData?.id) {
      nextState.polarTransactionId = eventData.id;
    }
    if (currentPeriodEnd) {
      nextState.currentPeriodEnd = currentPeriodEnd;
    }
    if (shouldApplyNextPlan) {
      nextState.nextPlan = null;
    }
    if (shouldPreserveCancellation && currentState?.nextPlan) {
      nextState.nextPlan = currentState.nextPlan;
    }
  } else if (eventType === "subscription.created") {
    if (incomingPolarSubscriptionId) {
      nextState.polarSubscriptionId = incomingPolarSubscriptionId;
    }
    if (plan) {
      const planObject = normalizePlan(plan, productId, interval, getProductIdForPlan);
      const planName = getPlanName(planObject);
      nextState.plan = planObject;
      nextState.interval = interval ?? undefined;

      const hasTrialInCreated =
        eventData?.status === "trialing" ||
        !!trialingEndsAt ||
        !!eventData?.trial_end ||
        !!eventData?.trial_start;

      if (planName !== "starter") {
        nextState.status = hasTrialInCreated ? "trialing" : "active";
      }

      if (hasTrialInCreated) {
        if (trialingEndsAt) {
          nextState.trialingEndsAt = trialingEndsAt;
        }
        nextState.price = 0;
      }
    }
    if (currentPeriodEnd) {
      nextState.currentPeriodEnd = currentPeriodEnd;
    }
    if (nextState.status !== "trialing" && webhookPrice !== null && Number.isFinite(webhookPrice) && webhookPrice > 0) {
      nextState.price = webhookPrice;
    } else if (nextState.status !== "trialing" && plan) {
      const planName = getPlanName(normalizePlan(plan, productId, interval, getProductIdForPlan));
      nextState.price = getEffectivePrice(planName, interval);
    }
  } else if (eventType === "subscription.updated" && eventData?.status === "trialing") {
    if (existingStatus !== "active") {
      nextState.status = "trialing";
      nextState.trialingEndsAt = trialingEndsAt ?? currentPeriodEnd ?? currentState?.trialingEndsAt ?? null;
      if (incomingPolarSubscriptionId) {
        nextState.polarSubscriptionId = incomingPolarSubscriptionId;
      }
      if (plan) {
        nextState.plan = normalizePlan(plan, productId, interval, getProductIdForPlan);
        nextState.interval = interval ?? undefined;
      } else if (currentState?.plan) {
        nextState.plan = normalizePlan(currentState.plan, null, currentState?.interval ?? interval, getProductIdForPlan);
        nextState.interval = nextState.interval ?? currentState?.interval ?? undefined;
      }
    }
  } else if (eventType === "subscription.canceled" || eventType === "subscription.cancelled") {
    const endsAt = eventData?.ends_at ?? eventData?.current_period_end ?? null;
    const periodEndDate = endsAt ? new Date(endsAt) : (currentPeriodEnd ? new Date(currentPeriodEnd) : null);
    const now = new Date();
    const endsInFuture = periodEndDate && periodEndDate > now;

    if (endsInFuture) {
      nextState.status = "cancelled_at_period_end";
      nextState.nextPlan = normalizePlan("starter");
      nextState.currentPeriodEnd = periodEndDate ?? currentPeriodEnd ?? null;
      if (incomingPolarSubscriptionId) {
        nextState.polarSubscriptionId = incomingPolarSubscriptionId;
      }
    } else {
      nextState.plan = normalizePlan("starter");
      nextState.status = "free";
      nextState.nextPlan = null;
      nextState.price = 0;
      nextState.currentPeriodEnd = null;
      nextState.trialingEndsAt = null;
      nextState.polarSubscriptionId = null;
      nextState.polarTransactionId = null;
    }
  } else if (eventType === "subscription.updated" && eventData?.status !== "trialing") {
    const cancelAtPeriodEnd = eventData?.cancel_at_period_end === true;

    if (cancelAtPeriodEnd) {
      const endsAt = eventData?.ends_at ?? eventData?.current_period_end ?? null;
      const periodEndDate = endsAt ? new Date(endsAt) : (currentPeriodEnd ? new Date(currentPeriodEnd) : null);
      const now = new Date();
      const endsInFuture = periodEndDate && periodEndDate > now;

      if (endsInFuture) {
        nextState.status = "cancelled_at_period_end";
        nextState.nextPlan = normalizePlan("starter");
        nextState.currentPeriodEnd = periodEndDate ?? currentPeriodEnd ?? null;
        if (incomingPolarSubscriptionId) {
          nextState.polarSubscriptionId = incomingPolarSubscriptionId;
        }
      }
    } else if (eventData?.status === "active" && incomingPolarSubscriptionId) {
      nextState.status = "active";
      nextState.trialingEndsAt = null;
      nextState.polarSubscriptionId = incomingPolarSubscriptionId;
      if (currentPeriodEnd) {
        nextState.currentPeriodEnd = currentPeriodEnd;
      }
      if (webhookPrice !== null && Number.isFinite(webhookPrice) && webhookPrice > 0) {
        nextState.price = webhookPrice;
      }
      const existingNextPlanNameInner = currentState?.nextPlan ? getPlanName(currentState.nextPlan) : null;
      if (!existingNextPlanNameInner || !["go", "growth", "scale"].includes(existingNextPlanNameInner)) {
        nextState.nextPlan = null;
      }
    }
  } else if (eventType === "subscription.active") {
    const hasTrialSignal =
      eventData?.status === "trialing" ||
      !!trialingEndsAt ||
      !!eventData?.trial_end ||
      !!eventData?.trial_start ||
      existingStatus === "trialing";

    nextState.status = hasTrialSignal ? "trialing" : "active";
    nextState.nextPlan = null;
    nextState.trialingEndsAt = hasTrialSignal ? (trialingEndsAt ?? currentState?.trialingEndsAt ?? null) : null;
    if (incomingPolarSubscriptionId) {
      nextState.polarSubscriptionId = incomingPolarSubscriptionId;
    }
    if (currentPeriodEnd) {
      nextState.currentPeriodEnd = currentPeriodEnd;
    }
    if (!hasTrialSignal && webhookPrice !== null && Number.isFinite(webhookPrice) && webhookPrice > 0) {
      nextState.price = webhookPrice;
    } else if (hasTrialSignal) {
      nextState.price = 0;
    }
  } else if (eventType === "subscription.uncanceled") {
    const now = new Date();
    const existingTrialingEndsAt = currentState?.trialingEndsAt ? new Date(currentState.trialingEndsAt) : null;
    const wasTrialing = !!existingTrialingEndsAt;
    const trialNotEnded = existingTrialingEndsAt && existingTrialingEndsAt > now;
    const shouldRestoreToTrialing = wasTrialing && trialNotEnded;

    nextState.status = shouldRestoreToTrialing ? "trialing" : "active";
    nextState.nextPlan = null;

    if (shouldRestoreToTrialing) {
      nextState.trialingEndsAt = existingTrialingEndsAt;
      nextState.price = 0;
    } else {
      nextState.trialingEndsAt = null;
      if (webhookPrice !== null && Number.isFinite(webhookPrice) && webhookPrice > 0) {
        nextState.price = webhookPrice;
      }
    }

    if (incomingPolarSubscriptionId) {
      nextState.polarSubscriptionId = incomingPolarSubscriptionId;
    }
    if (currentPeriodEnd) {
      nextState.currentPeriodEnd = currentPeriodEnd;
    }
  } else if (eventType === "subscription.revoked") {
    nextState.plan = normalizePlan("starter");
    nextState.status = "free";
    nextState.nextPlan = null;
    nextState.price = 0;
    nextState.currentPeriodEnd = null;
    nextState.trialingEndsAt = null;
    nextState.polarSubscriptionId = null;
    nextState.polarTransactionId = null;
  }

  if (nextState.status === "trialing" && !nextState.trialingEndsAt && nextState.currentPeriodEnd) {
    nextState.trialingEndsAt = nextState.currentPeriodEnd;
  }

  Object.keys(nextState).forEach((key) => {
    if (nextState[key] === undefined) {
      delete nextState[key];
    }
  });

  return nextState;
}

export { validateSubscriptionState, buildNextSubscriptionState };

import crypto from "crypto";

/**
 * Generate unique event key for idempotency.
 * Prefer provider event identity (event.id/event.timestamp). Fallback to
 * payload-derived hash only when provider identity is unavailable.
 */
function getEventKey(eventType, eventId, eventData = null) {
  if (eventId) {
    return `${eventType}:${eventId}`;
  }
  if (eventData) {
    const payloadKey = {
      dataId: eventData?.id ?? null,
      created_at: eventData?.created_at ?? null,
      modified_at: eventData?.modified_at ?? null,
      status: eventData?.status ?? null,
      cancel_at_period_end: eventData?.cancel_at_period_end ?? null,
      ends_at: eventData?.ends_at ?? null
    };
    const payloadHash = crypto
      .createHash("md5")
      .update(JSON.stringify(payloadKey))
      .digest("hex")
      .substring(0, 12);
    return `${eventType}:payload:${payloadHash}`;
  }
  return `${eventType}:unknown`;
}

/**
 * Check if webhook event was already processed (idempotency)
 * @returns {object|null} Existing event record or null
 */
async function checkEventIdempotency(eventType, eventId, eventData = null, deps = {}) {
  const { webhookEventModel, loggerInstance } = deps;
  if (!webhookEventModel) {
    throw new Error("webhookEventModel is required for checkEventIdempotency");
  }
  const eventKey = getEventKey(eventType, eventId, eventData);
  try {
    const existing = await webhookEventModel.findOne({ eventKey }).lean();
    return existing;
  } catch (err) {
    loggerInstance?.error?.({ err, eventKey }, "Error checking webhook idempotency");
    return null;
  }
}

/**
 * Mark webhook event as processed
 */
async function markEventProcessed(eventType, eventId, userId, previousState, nextState, eventData = null, deps = {}) {
  const { webhookEventModel, loggerInstance } = deps;
  if (!webhookEventModel) {
    throw new Error("webhookEventModel is required for markEventProcessed");
  }
  const eventKey = getEventKey(eventType, eventId, eventData);
  try {
    await webhookEventModel.create({
      eventKey,
      eventType,
      eventId: eventId || "unknown",
      userId: userId || null,
      previousState: previousState ? JSON.parse(JSON.stringify(previousState)) : null,
      nextState: nextState ? JSON.parse(JSON.stringify(nextState)) : null
    });
  } catch (err) {
    if (err.code === 11000) {
      loggerInstance?.warn?.({ eventKey }, "Webhook event already marked as processed");
    } else {
      loggerInstance?.error?.({ err, eventKey }, "Error marking webhook event as processed");
    }
  }
}

export { getEventKey, checkEventIdempotency, markEventProcessed };

const { data: plans = [], isLoading: isLoadingPlans } = useQuery({
  queryKey: ["subscription", "plans"],
  queryFn: fetchSubscriptionPlans,
  enabled: !!user,
});

const { data: currentSubscription, isLoading: isLoadingCurrent } = useQuery({
  queryKey: ["subscription", "current", contextChannelId ?? "me"],
  queryFn: () => fetchCurrentSubscription(contextChannelId),
  enabled: !!user,
});

const { data: usage } = useQuery({
  queryKey: ["subscription", "usage", contextChannelId ?? "me"],
  queryFn: () => fetchSubscriptionUsage(contextChannelId),
  enabled: !!user,
});

const upgradeMutation = useMutation({
  mutationFn: (vars: { plan: string; interval: BillingInterval }) =>
    upgradeSubscription(vars.plan, vars.interval),
  onSuccess: async () => {
    await queryClient.invalidateQueries({ queryKey: ["subscription"] });
    dispatch(initializeSession());
  },
});

const portalMutation = useMutation({
  mutationFn: () => createBillingPortal()
});

const resumeMutation = useMutation({
  mutationFn: () => resumeSubscription(),
  onSuccess: async () => {
    await queryClient.invalidateQueries({ queryKey: ['subscription'] });
    dispatch(initializeSession());
    toast.success('Subscription resumed. Your plan will continue as before.');
  },
});

const getPlanName = (plan: string | { name: string } | undefined): string => {
  if (!plan) return 'starter';
  if (typeof plan === 'string') return plan;
  if (typeof plan === 'object' && plan.name) return plan.name;
  return 'starter';
};

const currentPlan = getPlanName(currentSubscription?.current_plan ?? currentSubscription?.plan ?? user?.subscriptionPlan ?? 'starter');
const subscriptionStatus = (
  currentSubscription?.subscription_status ??
  (currentSubscription?.status === 'trialing'
    ? 'trialing'
    : currentSubscription?.status === 'canceled' || currentSubscription?.status === 'cancelled'
      ? 'cancelled'
      : 'active')
) as SubscriptionStatus;

const nextPlanValue = currentSubscription?.next_plan ?? currentSubscription?.nextPlan ?? null;
const nextPlan = nextPlanValue ? getPlanName(nextPlanValue) : null;
const currentPeriodEnd = currentSubscription?.current_period_end ?? currentSubscription?.currentPeriodEnd ?? null;
const trialingEndsAt = currentSubscription?.trialing_ends_at ?? null;
const currentInterval = (currentSubscription?.billing_interval ?? currentSubscription?.interval ?? 'monthly') as BillingInterval;
const trialUsedAt = currentSubscription?.trial_used_at ?? null;
const canStartTrial = trialUsedAt == null;
const activeDiscount = currentSubscription?.active_discount ?? null;

const trialEndsAtDate = trialingEndsAt ? new Date(trialingEndsAt) : null;
const isTrialActiveByDate = Boolean(
  trialEndsAtDate &&
  !Number.isNaN(trialEndsAtDate.getTime()) &&
  trialEndsAtDate.getTime() > Date.now()
);
const isTrialing = subscriptionStatus === 'trialing' || isTrialActiveByDate;
const isCancelledAtPeriodEnd = subscriptionStatus === 'cancelled_at_period_end';

const handleUpgrade = async (plan: Plan) => {
  track('upgrade_clicked', { plan: plan.id, interval: billingInterval });
  try {
    const data = await upgradeMutation.mutateAsync({ plan: plan.id, interval: billingInterval });
    if (data?.checkoutUrl) {
      if (activeDiscount) {
        track('coupon_applied_ui', { plan: plan.id, discount_target: activeDiscount.target_plan });
      }
      window.location.href = data.checkoutUrl;
      return;
    }
    if (data?.nextPlan != null && data?.currentPlan != null) {
      toast.success('Downgrade scheduled for next billing cycle. Your current plan stays active until then.');
    } else {
      toast.success(`Switched to ${plan.name} plan.`);
    }
  } catch {
    toast.error('Failed to update subscription. Please try again.');
  }
};

const handlePlanAction = async (plan: Plan) => {
  const isFreePlan = plan.id === 'starter' || plan.price === 0;
  if (isFreePlan && currentPlan !== 'starter') {
    setPendingDowngradePlan(plan);
    setShowSwitchToFreeConfirm(true);
    return;
  }

  if (isTrialing && !isFreePlan && currentPlan !== plan.id) {
    setPendingUpgradePlan(plan);
    setShowUpgradeConfirm(true);
    return;
  }

  await handleUpgrade(plan);
};

// Resume button action
await resumeMutation.mutateAsync();

// Manage billing action
const data = await portalMutation.mutateAsync();
window.location.href = data.url;

// UI behavior
// - If status is cancelled_at_period_end: show "Resume subscription"
// - Else: show "Manage billing"
// - For free plan: show upgrade CTA and trial availability based on trial_used_at