feat(tip): support tiered coffee gifts

src/app/tip/__tests__/tip-screen.helpers.test.ts

@@ -29,34 +29,51 @@ function makePlan(input: Partial<PaymentPlanInput>): PaymentPlan {
 }
 
 describe("tip screen helpers", () => {
-  it("prefers the exact tip coffee plan id", () => {
-    const byOrderType = makePlan({
-      planId: "legacy_coffee",
-      planName: "Legacy coffee",
-      orderType: "tip_coffee",
-    });
-    const byPlanId = makePlan({
+  it("uses the legacy tip coffee plan only for small", () => {
+    const plan = makePlan({
       planId: "tip_coffee",
-      planName: "Coffee",
-      orderType: "custom_tip",
     });
 
-    expect(findTipCoffeePlan([byOrderType, byPlanId])).toBe(byPlanId);
+    expect(findTipCoffeePlan([makePlan({}), plan], "small")).toBe(plan);
+    expect(findTipCoffeePlan([plan], "medium")).toBeNull();
   });
 
-  it("falls back to the tip coffee order type", () => {
-    const plan = makePlan({
-      planId: "legacy_coffee",
-      orderType: "tip_coffee",
+  it("matches medium and large coffee plans independently", () => {
+    const medium = makePlan({
+      planId: "tip_coffee_medium",
+      orderType: "tip_coffee_medium",
+      amountCents: 999,
+    });
+    const large = makePlan({
+      planId: "tip_coffee_large",
+      orderType: "tip_coffee_large",
+      amountCents: 1999,
     });
 
-    expect(findTipCoffeePlan([makePlan({}), plan])).toBe(plan);
+    expect(findTipCoffeePlan([large, medium], "medium")).toBe(medium);
+    expect(findTipCoffeePlan([medium, large], "large")).toBe(large);
+  });
+
+  it("does not infer a coffee tier from order type or amount", () => {
+    const ambiguousPlan = makePlan({
+      planId: "legacy_coffee",
+      orderType: "tip_coffee_medium",
+      amountCents: 999,
+    });
+
+    expect(findTipCoffeePlan([ambiguousPlan], "medium")).toBeNull();
   });
 
   it("formats USD prices with the product-style label", () => {
-    expect(formatTipPrice(makePlan({ amountCents: 500, currency: "USD" }))).toBe(
-      "US$ 5",
-    );
+    expect(
+      formatTipPrice(makePlan({ amountCents: 500, currency: "USD" }), "small"),
+    ).toBe("US$ 5");
+  });
+
+  it("uses the selected coffee price when its plan is unavailable", () => {
+    expect(formatTipPrice(null, "small")).toBe("US$ 4.99");
+    expect(formatTipPrice(null, "medium")).toBe("US$ 9.99");
+    expect(formatTipPrice(null, "large")).toBe("US$ 19.99");
   });
 
   it("treats guest and notLoggedIn as non-real login states", () => {

src/app/tip/tip-checkout-button.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { usePaymentLaunchFlow } from "@/app/_hooks/use-payment-launch-flow";
-import { ROUTES } from "@/router/routes";
+import type { TipCoffeeType } from "@/lib/tip/tip_coffee";
 import {
   usePaymentDispatch,
   usePaymentState,
@@ -15,15 +15,19 @@ import styles from "./tip-screen.module.css";
 const log = new Logger("TipCheckoutButton");
 
 export interface TipCheckoutButtonProps {
+  coffeeType: TipCoffeeType;
   disabled?: boolean;
   isAuthLoading?: boolean;
   onOrder: () => void;
+  returnPath: string;
 }
 
 export function TipCheckoutButton({
+  coffeeType,
   disabled = false,
   isAuthLoading = false,
   onOrder,
+  returnPath,
 }: TipCheckoutButtonProps) {
   const payment = usePaymentState();
   const paymentDispatch = usePaymentDispatch();
@@ -33,6 +37,7 @@ export function TipCheckoutButton({
     payment,
     paymentDispatch,
     subscriptionType: "tip",
+    tipCoffeeType: coffeeType,
   });
 
   const isLoading =
@@ -71,7 +76,7 @@ export function TipCheckoutButton({
       {paymentLaunch.shouldShowStripeDialog && paymentLaunch.stripeClientSecret ? (
         <StripePaymentDialog
           clientSecret={paymentLaunch.stripeClientSecret}
-          returnPath={ROUTES.tip}
+          returnPath={returnPath}
           onClose={paymentLaunch.handleStripeClose}
           onConfirmed={paymentLaunch.handleStripeConfirmed}
         />

src/app/tip/tip-page-client.tsx

@@ -3,6 +3,11 @@
 import { useSearchParams } from "next/navigation";
 
 import type { PayChannel } from "@/data/dto/payment";
+import {
+  DEFAULT_TIP_COFFEE_TYPE,
+  resolveTipCoffeeType,
+  TIP_COFFEE_TYPE_PARAM,
+} from "@/lib/tip/tip_coffee";
 
 import { TipScreen } from "./tip-screen";
 
@@ -13,9 +18,13 @@ function toPayChannel(value: string | null): PayChannel | null {
 
 export function TipPageClient() {
   const searchParams = useSearchParams();
+  const coffeeType =
+    resolveTipCoffeeType(searchParams.get(TIP_COFFEE_TYPE_PARAM)) ??
+    DEFAULT_TIP_COFFEE_TYPE;
 
   return (
     <TipScreen
+      coffeeType={coffeeType}
       shouldResumePendingOrder={searchParams.get("paymentReturn") === "1"}
       initialPayChannel={toPayChannel(searchParams.get("payChannel"))}
     />

src/app/tip/tip-screen.helpers.ts

@@ -1,27 +1,37 @@
 import type { LoginStatus } from "@/data/dto/auth";
 import type { PaymentPlan } from "@/data/dto/payment";
-
-const TIP_COFFEE_PLAN_ID = "tip_coffee";
-const TIP_COFFEE_ORDER_TYPE = "tip_coffee";
+import {
+  getTipCoffeeOption,
+  type TipCoffeeType,
+} from "@/lib/tip/tip_coffee";
 
 export function findTipCoffeePlan(
   plans: readonly PaymentPlan[],
+  coffeeType: TipCoffeeType,
 ): PaymentPlan | null {
+  const option = getTipCoffeeOption(coffeeType);
+
   return (
-    plans.find((plan) => plan.planId === TIP_COFFEE_PLAN_ID) ??
-    plans.find((plan) => plan.orderType === TIP_COFFEE_ORDER_TYPE) ??
+    plans.find((plan) => plan.planId === option.planId) ??
+    (coffeeType === "small"
+      ? (plans.find((plan) => plan.planId === "tip_coffee") ?? null)
+      : null) ??
     null
   );
 }
 
-export function formatTipPrice(plan: PaymentPlan | null): string {
-  if (!plan) return "US$ 5";
+export function formatTipPrice(
+  plan: PaymentPlan | null,
+  coffeeType: TipCoffeeType,
+): string {
+  const option = getTipCoffeeOption(coffeeType);
+  const amountCents = plan?.amountCents ?? option.amountCents;
+  const currency = plan?.currency.trim().toUpperCase() || "USD";
 
-  const amount = plan.amountCents / 100;
+  const amount = amountCents / 100;
   const formattedAmount = Number.isInteger(amount)
     ? String(amount)
     : amount.toFixed(2).replace(/\.?0+$/, "");
-  const currency = plan.currency.trim().toUpperCase();
 
   if (currency === "USD") return `US$ ${formattedAmount}`;
   if (currency.length > 0) return `${currency} ${formattedAmount}`;

src/app/tip/tip-screen.tsx

@@ -8,7 +8,12 @@ import { CharacterAvatar } from "@/app/_components";
 import { MobileShell } from "@/app/_components/core";
 import { usePaymentOrderLifecycle } from "@/app/_hooks/use-payment-order-lifecycle";
 import type { PayChannel } from "@/data/dto/payment";
-import { ROUTES } from "@/router/routes";
+import {
+  buildTipCoffeePath,
+  DEFAULT_TIP_COFFEE_TYPE,
+  getTipCoffeeOption,
+  type TipCoffeeType,
+} from "@/lib/tip/tip_coffee";
 import { useAppNavigator } from "@/router/use-app-navigator";
 import { useAuthState } from "@/stores/auth/auth-context";
 import {
@@ -25,11 +30,13 @@ import {
 import styles from "./tip-screen.module.css";
 
 export interface TipScreenProps {
+  coffeeType?: TipCoffeeType;
   shouldResumePendingOrder?: boolean;
   initialPayChannel?: PayChannel | null;
 }
 
 export function TipScreen({
+  coffeeType = DEFAULT_TIP_COFFEE_TYPE,
   shouldResumePendingOrder = false,
   initialPayChannel = null,
 }: TipScreenProps) {
@@ -38,14 +45,16 @@ export function TipScreen({
   const payment = usePaymentState();
   const paymentDispatch = usePaymentDispatch();
   const initialPayChannelAppliedRef = useRef(false);
+  const coffeeOption = getTipCoffeeOption(coffeeType);
+  const returnPath = buildTipCoffeePath(coffeeType);
   const resolvedInitialPayChannel =
     initialPayChannel ?? navigator.getDefaultPayChannel();
 
   const coffeePlan = useMemo(
-    () => findTipCoffeePlan(payment.plans),
-    [payment.plans],
+    () => findTipCoffeePlan(payment.plans, coffeeType),
+    [coffeeType, payment.plans],
   );
-  const priceLabel = formatTipPrice(coffeePlan);
+  const priceLabel = formatTipPrice(coffeePlan, coffeeType);
   const isPaymentBusy =
     payment.isCreatingOrder || payment.isPollingOrder || payment.isPaid;
   const canCreateOrder =
@@ -127,7 +136,7 @@ export function TipScreen({
   const handleOrder = () => {
     if (isAuthLoading) return;
     if (!isRealLoginStatus(authState.loginStatus)) {
-      navigator.openAuth(ROUTES.tip);
+      navigator.openAuth(returnPath);
       return;
     }
     if (!canCreateOrder) return;
@@ -198,7 +207,7 @@ export function TipScreen({
               Coffee Gift
             </span>
             <h2 className={styles.productName}>
-              {coffeePlan?.planName || "Latte"}
+              {coffeePlan?.planName || coffeeOption.fallbackName}
             </h2>
             <p className={styles.productPrice}>{priceLabel}</p>
           </div>
@@ -231,12 +240,14 @@ export function TipScreen({
 
         <div className={styles.checkoutSlot}>
           <TipCheckoutButton
+            coffeeType={coffeeType}
             disabled={
               showMissingPlan ||
               (!canCreateOrder && isRealLoginStatus(authState.loginStatus))
             }
             isAuthLoading={isAuthLoading}
             onOrder={handleOrder}
+            returnPath={returnPath}
           />
         </div>
       </main>