refactor(payment): centralize route lifecycle

src/app/tip/page.tsx

@@ -1,4 +1,8 @@
-import type { PayChannel } from "@/data/dto/payment";
+import {
+  getFirstPaymentSearchParam,
+  parsePaymentReturnSearchParams,
+  type PaymentSearchParams,
+} from "@/lib/payment/payment_search_params";
 import {
   DEFAULT_TIP_COFFEE_TYPE,
   resolveTipCoffeeType,
@@ -7,31 +11,24 @@ import {
 
 import { TipScreen } from "./tip-screen";
 
-type TipSearchParams = Record<string, string | string[] | undefined>;
-
 export default async function TipPage({
   searchParams,
 }: {
-  searchParams: Promise<TipSearchParams>;
+  searchParams: Promise<PaymentSearchParams>;
 }) {
   const query = await searchParams;
+  const paymentReturn = parsePaymentReturnSearchParams(query);
   const coffeeType =
-    resolveTipCoffeeType(firstSearchParam(query[TIP_COFFEE_TYPE_PARAM])) ??
+    resolveTipCoffeeType(
+      getFirstPaymentSearchParam(query[TIP_COFFEE_TYPE_PARAM]),
+    ) ??
     DEFAULT_TIP_COFFEE_TYPE;
 
   return (
     <TipScreen
       coffeeType={coffeeType}
-      shouldResumePendingOrder={firstSearchParam(query.paymentReturn) === "1"}
-      initialPayChannel={toPayChannel(firstSearchParam(query.payChannel))}
+      shouldResumePendingOrder={paymentReturn.shouldResumePendingOrder}
+      initialPayChannel={paymentReturn.initialPayChannel}
     />
   );
 }
-
-function firstSearchParam(value: string | string[] | undefined): string | null {
-  return Array.isArray(value) ? (value[0] ?? null) : (value ?? null);
-}
-
-function toPayChannel(value: string | null): PayChannel | null {
-  return value === "ezpay" || value === "stripe" ? value : null;
-}

src/app/tip/tip-screen.tsx

@@ -1,13 +1,13 @@
 "use client";
 
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import Image from "next/image";
 import { ArrowLeft, Heart, Sparkles } from "lucide-react";
 
 import { CharacterAvatar } from "@/app/_components";
 import { MobileShell } from "@/app/_components/core";
-import { usePaymentOrderLifecycle } from "@/app/_hooks/use-payment-order-lifecycle";
 import { usePaymentPlanAnalytics } from "@/app/_hooks/use-payment-plan-analytics";
+import { usePaymentRouteFlow } from "@/app/_hooks/use-payment-route-flow";
 import type { PayChannel } from "@/data/dto/payment";
 import {
   behaviorAnalytics,
@@ -22,10 +22,6 @@ import {
 } from "@/lib/tip/tip_coffee";
 import { useAppNavigator } from "@/router/use-app-navigator";
 import { useAuthState } from "@/stores/auth/auth-context";
-import {
-  usePaymentDispatch,
-  usePaymentState,
-} from "@/stores/payment/payment-context";
 
 import { TipCheckoutButton } from "./tip-checkout-button";
 import {
@@ -57,15 +53,18 @@ export function TipScreen({
 }: TipScreenProps) {
   const navigator = useAppNavigator();
   const authState = useAuthState();
-  const payment = usePaymentState();
-  const paymentDispatch = usePaymentDispatch();
-  const initialPayChannelAppliedRef = useRef(false);
   const [selectedCoffeeType, setSelectedCoffeeType] =
     useState<TipCoffeeType>(coffeeType);
   const coffeeOption = getTipCoffeeOption(selectedCoffeeType);
   const returnPath = buildTipCoffeePath(selectedCoffeeType);
   const resolvedInitialPayChannel =
     initialPayChannel ?? navigator.getDefaultPayChannel();
+  const { payment, paymentDispatch } = usePaymentRouteFlow({
+    catalog: "tip",
+    initialPayChannel: resolvedInitialPayChannel,
+    paymentType: "tip",
+    shouldResumePendingOrder,
+  });
 
   const coffeeTiers = useMemo(
     () =>
@@ -113,39 +112,6 @@ export function TipScreen({
     payment.status !== "ready" || payment.isLoadingPlans || isPaymentBusy;
   const isAuthLoading = !authState.hasInitialized || authState.isLoading;
 
-  usePaymentOrderLifecycle({
-    payment,
-    paymentDispatch,
-    paymentType: "tip",
-    shouldResumePendingOrder,
-  });
-
-  useEffect(() => {
-    if (payment.status === "idle") {
-      initialPayChannelAppliedRef.current = true;
-      paymentDispatch({
-        type: "PaymentInit",
-        catalog: "tip",
-        payChannel: resolvedInitialPayChannel,
-      });
-      return;
-    }
-
-    if (!initialPayChannelAppliedRef.current && payment.status === "ready") {
-      initialPayChannelAppliedRef.current = true;
-      if (payment.payChannel === resolvedInitialPayChannel) return;
-      paymentDispatch({
-        type: "PaymentPayChannelChanged",
-        payChannel: resolvedInitialPayChannel,
-      });
-    }
-  }, [
-    payment.payChannel,
-    payment.status,
-    paymentDispatch,
-    resolvedInitialPayChannel,
-  ]);
-
   useEffect(() => {
     if (payment.isLoadingPlans || payment.isCreatingOrder || payment.isPollingOrder) {
       return;