@carrierllc/mcp 0.11.16 → 0.12.0

package/templates/storefront/src/app/shop/ShopClient.tsx

@@ -1,18 +1,72 @@
 "use client";
+/**
+ * ShopClient — pick a plan, see what it costs, pay.
+ *
+ * Selecting a card used to navigate straight to /checkout, so the shopper was
+ * handed to Stripe without ever seeing the total they were about to be charged.
+ * The order summary is that missing beat: name, price, what is included, total.
+ *
+ * On a wide screen the summary is a sticky column and is always in view. On a
+ * phone it is stacked underneath the plans, which is where the real defect was:
+ * tapping a card changed something the customer could not see, so the tap read
+ * as dead. `scrollSummaryIntoView` answers the tap by bringing the summary —
+ * and the pay button in it — on screen.
+ */
 
+import { useCallback, useRef, useState } from "react";
 import { useRouter } from "next/navigation";
 import { PlanCard } from "@/components/landing/PlanCard";
 import { conversionEvents } from "@/lib/conversion-events";
+import { formatDataAllowance, formatPrice, formatValidity } from "@/vendor/geo";
 import type { SkuTemplate } from "@/vendor/carrier/types";
 
+/** Above this width the summary is a sticky column and never leaves the fold. */
+const WIDE_VIEWPORT = "(min-width: 1024px)";
+
+function prefersReducedMotion(): boolean {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return false;
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
+function isWideViewport(): boolean {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return false;
+  return window.matchMedia(WIDE_VIEWPORT).matches;
+}
+
 export function ShopClient({ plans }: { plans: SkuTemplate[] }) {
   const router = useRouter();
+  const [selected, setSelected] = useState<SkuTemplate | null>(null);
+  const summaryRef = useRef<HTMLElement | null>(null);
+
+  /**
+   * Bring the summary on screen after a selection, on narrow viewports only.
+   *
+   * `scrollIntoView` is missing in some engines and in jsdom, so the call is
+   * optional-chained: a browser that cannot scroll must still select the plan.
+   */
+  const scrollSummaryIntoView = useCallback(() => {
+    if (isWideViewport()) return;
+    requestAnimationFrame(() => {
+      summaryRef.current?.scrollIntoView?.({
+        behavior: prefersReducedMotion() ? "auto" : "smooth",
+        block: "start",
+      });
+    });
+  }, []);
 
   function handleSelect(plan: SkuTemplate) {
     conversionEvents.selectPlan(plan.name);
-    router.push(`/checkout/${plan.id}`);
+    setSelected(plan);
+    scrollSummaryIntoView();
+  }
+
+  function handleContinue() {
+    if (!selected) return;
+    router.push(`/checkout/${selected.id}`);
   }
 
+  const total = selected ? formatPrice(selected.price_cents, selected.currency) : null;
+
   return (
     <div className="mx-auto max-w-6xl px-4 py-16">
       <h1 className="text-4xl font-semibold tracking-tight text-sand-900 dark:text-sand-50">
@@ -21,10 +75,77 @@ export function ShopClient({ plans }: { plans: SkuTemplate[] }) {
       <p className="mt-2 mb-12 text-sand-600 dark:text-sand-400">
         Instant activation. No contracts. Price next to the limit.
       </p>
-      <div className="grid grid-cols-1 gap-8 sm:grid-cols-2 lg:grid-cols-3">
-        {plans.map((plan, i) => (
-          <PlanCard key={plan.id} plan={plan} featured={i === 1} onSelect={handleSelect} />
-        ))}
+
+      <div className="grid grid-cols-1 items-start gap-8 lg:grid-cols-[minmax(0,1fr)_320px]">
+        <div className="grid grid-cols-1 gap-8 sm:grid-cols-2">
+          {plans.map((plan, i) => (
+            <PlanCard
+              key={plan.id}
+              plan={plan}
+              featured={i === 1}
+              selected={selected?.id === plan.id}
+              onSelect={handleSelect}
+            />
+          ))}
+        </div>
+
+        <section
+          ref={summaryRef}
+          aria-label="Order summary"
+          aria-live="polite"
+          className="scroll-mt-24 rounded-2xl border border-sand-200 bg-white p-6 lg:sticky lg:top-24 dark:border-sand-800 dark:bg-sand-900"
+        >
+          <p className="text-xs font-semibold tracking-widest text-sand-500 uppercase">
+            Your order
+          </p>
+          <h2 className="mt-3 text-xl font-semibold tracking-tight text-sand-900 dark:text-sand-50">
+            {selected?.name ?? "Pick a plan"}
+          </h2>
+          <p className="mt-1 text-sm text-sand-500">
+            {selected
+              ? `${formatDataAllowance(selected.dataGb)} · ${formatValidity(selected.validityDays)}`
+              : "Choose a plan on the left and the total appears here."}
+          </p>
+
+          <dl className="my-5 grid gap-3 border-y border-sand-200 py-5 text-sm dark:border-sand-800">
+            <div className="flex items-baseline justify-between gap-3">
+              <dt className="text-sand-500">Plan</dt>
+              <dd className="font-mono tabular-nums text-sand-900 dark:text-sand-50">
+                {total ?? "—"}
+              </dd>
+            </div>
+            <div className="flex items-baseline justify-between gap-3">
+              <dt className="text-sand-500">eSIM activation</dt>
+              <dd className="font-mono tabular-nums text-leaf-600">Free</dd>
+            </div>
+            <div className="flex items-baseline justify-between gap-3">
+              <dt className="text-sand-500">Tax</dt>
+              <dd className="font-mono tabular-nums text-sand-900 dark:text-sand-50">Included</dd>
+            </div>
+          </dl>
+
+          <div className="flex items-baseline justify-between gap-3">
+            <span className="text-sm font-semibold text-sand-900 dark:text-sand-50">
+              Total today
+            </span>
+            <span className="font-mono text-2xl font-medium tabular-nums tracking-tight text-sand-900 dark:text-sand-50">
+              {total ?? "—"}
+            </span>
+          </div>
+
+          <button
+            type="button"
+            onClick={handleContinue}
+            disabled={!selected}
+            className="mt-6 w-full rounded-full px-6 py-3 text-sm font-semibold text-white transition-opacity hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-40"
+            style={{ background: "var(--brand-accent)" }}
+          >
+            {selected ? "Continue to payment" : "Select a plan first"}
+          </button>
+          <p className="mt-3 text-xs leading-relaxed text-sand-400">
+            Your QR code is ready the moment the payment clears. Install it before you fly.
+          </p>
+        </section>
       </div>
     </div>
   );

package/templates/storefront/src/app/sign-up/[[...sign-up]]/StorefrontSignUpClient.tsx

@@ -2,7 +2,7 @@
 /**
  * StorefrontSignUpClient
  *
- * MANGO-6/7: Custom email + password sign-up for the storefront.
+ * Custom email + password sign-up for the storefront.
  * Phone number is NEVER required. It is collected optionally on /activate/[orderId].
  *
  * Clerk v6 API (storefront uses @clerk/nextjs ^6):

package/templates/storefront/src/app/sign-up/[[...sign-up]]/page.tsx

@@ -2,7 +2,7 @@ export const dynamic = "force-dynamic";
 /**
  * /sign-up — Custom email + password sign-up flow for the storefront.
  *
- * MANGO-6/7: Phone number is never required here. It is collected optionally
+ * Phone number is never required here. It is collected optionally
  * on /activate/[orderId] after purchase.
  */
 import { Suspense } from "react";

package/templates/storefront/src/brand.config.ts

@@ -6,10 +6,29 @@ const brand = {
   name: process.env.NEXT_PUBLIC_BRAND_NAME ?? "Carrier",
   legalName: "Lifecycle Innovations Limited",
   tagline: "Programmable connectivity, on demand.",
+  /** One sentence. Used for <meta name="description"> and social cards. */
+  description: "Data that works in 200+ countries. Instant QR activation. Human support.",
   domain: "carrier.llc",
   supportUrl: "https://carrier.llc/help",
   supportEmail: "support@carrier.llc",
   supportWhatsapp: "+17864604829",
+  /** Display name on transactional mail. */
+  emailFromName: "Carrier",
+  /**
+   * Mailbox that transactional mail is sent from. The address is this plus
+   * `domain`, never a literal: a from-address that drifts off the brand domain
+   * is mail the operator cannot authenticate, which is mail that bounces.
+   */
+  emailFromMailbox: "hello",
+  /**
+   * Public origin of this storefront, no trailing slash.
+   *
+   * Every absolute URL the server builds — Stripe return URLs, the activation
+   * link in an email — is derived from this. `carrier site deploy` writes the
+   * deployed origin into NEXT_PUBLIC_APP_URL, so the literal below is only the
+   * fallback for a scaffold that has not been deployed yet.
+   */
+  appUrl: process.env.NEXT_PUBLIC_APP_URL ?? "https://carrier.llc",
   colors: {
     bg: "#FAFAF7",
     accent: "#FF6B35",

package/templates/storefront/src/components/checkout/EmbeddedStripeCheckout.tsx

@@ -0,0 +1,191 @@
+"use client";
+/**
+ * Stripe's embedded Checkout, mounted inside this storefront's own page.
+ *
+ * The alternative is `window.location.href = session.url`, which hands the
+ * customer to checkout.stripe.com and back: one full page load out of the
+ * brand and one back in, and every step between a plan and an installed eSIM
+ * is a step people drop out on. Embedded keeps the form here; Stripe still
+ * owns the iframe, so no card data touches this app.
+ *
+ * Stripe.js is loaded from js.stripe.com at runtime rather than bundled. That
+ * is Stripe's own requirement — the library must be served from their origin
+ * to stay PCI-compliant — and it keeps the template free of the @stripe/*
+ * packages, so a scaffolded storefront installs exactly what it did before.
+ *
+ * `onComplete` is the point of this component. The session is created with
+ * `redirect_on_completion=if_required`, so a card that needs no redirect
+ * finishes inside the iframe and leaves the customer looking at a done screen
+ * that goes nowhere. onComplete is where we take them onward.
+ */
+
+import { useEffect, useRef, useState } from "react";
+
+const STRIPE_JS_SRC = "https://js.stripe.com/v3/";
+
+/**
+ * Empty when the deploy has no publishable key. The caller checks this before
+ * asking for an embedded session, so an unconfigured storefront falls back to
+ * the hosted redirect instead of mounting a form that can never load.
+ */
+const PUBLISHABLE_KEY = process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY ?? "";
+
+export const canEmbedStripeCheckout = PUBLISHABLE_KEY.length > 0;
+
+interface EmbeddedCheckoutInstance {
+  mount: (selector: string | HTMLElement) => void;
+  unmount: () => void;
+  destroy: () => void;
+}
+
+interface StripeInstance {
+  createEmbeddedCheckoutPage?: (options: {
+    fetchClientSecret: () => Promise<string>;
+    onComplete?: () => void;
+  }) => Promise<EmbeddedCheckoutInstance>;
+  /** Name this method carried before `createEmbeddedCheckoutPage`. */
+  initEmbeddedCheckout?: (options: {
+    fetchClientSecret: () => Promise<string>;
+    onComplete?: () => void;
+  }) => Promise<EmbeddedCheckoutInstance>;
+}
+
+type StripeConstructor = (key: string) => StripeInstance;
+
+declare global {
+  interface Window {
+    Stripe?: StripeConstructor;
+  }
+}
+
+/**
+ * Load Stripe.js once per document, sharing one in-flight load between mounts.
+ *
+ * The promise is cached rather than the script tag. Attaching listeners to a
+ * tag that has already finished is the trap here: a script that failed fires
+ * neither `load` nor `error` again, so a second attempt would wait forever and
+ * the customer would sit on a spinner on the payment step. On failure the tag
+ * and the cached promise are both dropped, so a retry starts genuinely fresh.
+ */
+let stripeJsPromise: Promise<StripeConstructor> | null = null;
+
+function loadStripeJs(): Promise<StripeConstructor> {
+  if (typeof window === "undefined") {
+    return Promise.reject(new Error("Stripe.js cannot load on the server"));
+  }
+  if (window.Stripe) return Promise.resolve(window.Stripe);
+  if (stripeJsPromise) return stripeJsPromise;
+
+  stripeJsPromise = new Promise<StripeConstructor>((resolve, reject) => {
+    const script = document.createElement("script");
+    const fail = (message: string) => {
+      script.remove();
+      reject(new Error(message));
+    };
+    script.addEventListener(
+      "load",
+      () => {
+        if (window.Stripe) resolve(window.Stripe);
+        else fail("Stripe.js loaded without exposing Stripe");
+      },
+      { once: true },
+    );
+    script.addEventListener("error", () => fail("Stripe.js failed to load"), { once: true });
+    script.src = STRIPE_JS_SRC;
+    script.async = true;
+    document.head.appendChild(script);
+  });
+
+  // Drop the cache on failure so the next mount retries instead of replaying
+  // the rejection for the rest of the session.
+  stripeJsPromise.catch(() => {
+    stripeJsPromise = null;
+  });
+
+  return stripeJsPromise;
+}
+
+interface Props {
+  /** `client_secret` of a Checkout Session created with ui_mode=embedded. */
+  clientSecret: string;
+  /**
+   * Called once the session completes without a redirect. This is what stops
+   * the customer stranded on Stripe's "payment received" panel.
+   */
+  onComplete: () => void;
+  /** Stripe.js could not load or mount. The caller falls back to hosted. */
+  onUnavailable?: (reason: string) => void;
+}
+
+export function EmbeddedStripeCheckout({ clientSecret, onComplete, onUnavailable }: Props) {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const [mounted, setMounted] = useState(false);
+
+  // onComplete and onUnavailable are read through refs so that a caller who
+  // passes inline closures does not re-run this effect and open a second
+  // Checkout instance against one session.
+  const onCompleteRef = useRef(onComplete);
+  onCompleteRef.current = onComplete;
+  const onUnavailableRef = useRef(onUnavailable);
+  onUnavailableRef.current = onUnavailable;
+
+  useEffect(() => {
+    if (!canEmbedStripeCheckout || !clientSecret) return;
+    let cancelled = false;
+    let instance: EmbeddedCheckoutInstance | null = null;
+
+    void (async () => {
+      try {
+        const Stripe = await loadStripeJs();
+        if (cancelled) return;
+        const stripe = Stripe(PUBLISHABLE_KEY);
+        const create = stripe.createEmbeddedCheckoutPage ?? stripe.initEmbeddedCheckout;
+        if (!create) throw new Error("Stripe.js has no embedded Checkout constructor");
+
+        instance = await create.call(stripe, {
+          // A pure getter. Stripe re-reads this when it remounts, and fetching
+          // a fresh session here would charge one customer against two orders.
+          fetchClientSecret: () => Promise.resolve(clientSecret),
+          onComplete: () => onCompleteRef.current(),
+        });
+        if (cancelled || !containerRef.current) {
+          instance.destroy();
+          return;
+        }
+        instance.mount(containerRef.current);
+        setMounted(true);
+      } catch (error) {
+        if (cancelled) return;
+        onUnavailableRef.current?.(error instanceof Error ? error.message : String(error));
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+      // destroy() rather than unmount(): React may remount this component, and
+      // a stale instance holding the same session would render twice.
+      try {
+        instance?.destroy();
+      } catch {
+        // The iframe is already gone. Nothing to clean up.
+      }
+    };
+  }, [clientSecret]);
+
+  if (!canEmbedStripeCheckout) return null;
+
+  return (
+    <div
+      data-testid="embedded-stripe-checkout"
+      className="rounded-2xl border border-sand-200 bg-white p-4 dark:border-sand-800 dark:bg-sand-900"
+    >
+      {!mounted && (
+        <div className="py-12 text-center">
+          <div className="mx-auto mb-4 h-8 w-8 animate-spin rounded-full border-2 border-[var(--brand-accent)] border-t-transparent" />
+          <p className="text-sm text-sand-600 dark:text-sand-400">Loading the payment form…</p>
+        </div>
+      )}
+      <div ref={containerRef} />
+    </div>
+  );
+}

package/templates/storefront/src/components/landing/PlanCard.tsx

@@ -10,9 +10,15 @@ interface PlanCardProps {
   href?: string;
   onSelect?: (plan: SkuTemplate) => void;
   featured?: boolean;
+  /**
+   * This plan is the one currently in the order summary. Only meaningful on
+   * the select-then-continue flow; a card that links straight to checkout is
+   * never in a selected state.
+   */
+  selected?: boolean;
 }
 
-export function PlanCard({ plan, href, onSelect, featured }: PlanCardProps) {
+export function PlanCard({ plan, href, onSelect, featured, selected }: PlanCardProps) {
   const destination = href ?? (onSelect ? undefined : `/checkout/${plan.id}`);
 
   function handleSelect() {
@@ -50,19 +56,20 @@ export function PlanCard({ plan, href, onSelect, featured }: PlanCardProps) {
       <span
         className={cn(
           "mt-auto block rounded-full py-2 text-center text-sm font-semibold transition-colors",
-          featured
+          featured || selected
             ? "text-white"
             : "border border-sand-300 text-sand-900 hover:bg-sand-100 dark:border-sand-700 dark:text-sand-50 dark:hover:bg-sand-800",
         )}
-        style={featured ? { background: "var(--brand-accent)" } : undefined}
+        style={featured || selected ? { background: "var(--brand-accent)" } : undefined}
       >
-        Select plan
+        {selected ? "Selected" : "Select plan"}
       </span>
     </>
   );
 
   const cardClass = cn(
     "relative flex flex-col gap-4 rounded-2xl border p-6 pt-8 transition-colors",
+    selected && "ring-2 ring-[var(--brand-accent)] ring-offset-2 ring-offset-sand-50 dark:ring-offset-sand-950",
     featured
       ? "border-[var(--brand-accent)] bg-[color-mix(in_srgb,var(--brand-accent)_6%,white)] dark:bg-[color-mix(in_srgb,var(--brand-accent)_12%,#0F0E0A)]"
       : "border-sand-200 bg-white hover:border-sand-300 dark:border-sand-800 dark:bg-sand-900 dark:hover:border-sand-700",
@@ -81,6 +88,7 @@ export function PlanCard({ plan, href, onSelect, featured }: PlanCardProps) {
   return (
     <motion.button
       type="button"
+      aria-pressed={selected ?? undefined}
       whileHover={{ y: -4 }}
       className={cn(cardClass, "w-full text-left")}
       onClick={handleSelect}

package/templates/storefront/src/lib/checkout-order-claim.ts

@@ -61,18 +61,44 @@ function sessionPurchaserEmail(session: StripeSession): string | null {
   return session.customer_details?.email ?? session.customer_email ?? null;
 }
 
-async function userMatchesSessionPurchaser(session: StripeSession, userId: string): Promise<boolean> {
+/**
+ * Does this Clerk user own the address that paid for the session?
+ *
+ * `requireVerified` is the difference between two very different questions.
+ * Claiming an unclaimed order only needs the addresses on the account, because
+ * nobody loses anything. Taking an order off another account needs a verified
+ * address, because an unverified one is a string the claimant typed.
+ */
+async function userMatchesSessionPurchaser(
+  session: StripeSession,
+  userId: string,
+  opts: { requireVerified?: boolean } = {},
+): Promise<boolean> {
   const purchaserEmail = sessionPurchaserEmail(session);
-  if (!purchaserEmail) return true;
+  if (!purchaserEmail) return !opts.requireVerified;
 
   const client = await clerkClient();
   const user = await client.users.getUser(userId);
   const normalizedPurchaserEmail = purchaserEmail.toLowerCase();
   return user.emailAddresses.some(
-    (address) => address.emailAddress.toLowerCase() === normalizedPurchaserEmail,
+    (address) =>
+      address.emailAddress.toLowerCase() === normalizedPurchaserEmail &&
+      (!opts.requireVerified || address.verification?.status === "verified"),
   );
 }
 
+/** Drop an order id from a user's claimed list. Used when the order moves away. */
+async function removeClaimedOrderFromUser(userId: string, orderId: string): Promise<void> {
+  const client = await clerkClient();
+  const user = await client.users.getUser(userId);
+  const existing = claimedOrderIds(user.privateMetadata as Record<string, unknown> | undefined);
+  if (!existing.includes(orderId)) return;
+
+  await client.users.updateUserMetadata(userId, {
+    privateMetadata: { claimedOrderIds: existing.filter((id) => id !== orderId) },
+  });
+}
+
 async function addClaimedOrderToUser(userId: string, orderId: string): Promise<void> {
   const client = await clerkClient();
   const user = await client.users.getUser(userId);
@@ -108,7 +134,45 @@ export async function claimCheckoutOrder(
 
     const claimedBy = session.metadata?.claimedByUserId;
     if (claimedBy && claimedBy !== userId) {
-      return { ok: false, status: 403, error: "This order is linked to another account" };
+      /*
+       * The order is already on another account. That is the normal shape of a
+       * guest purchase that has since become a real account: pay signed out,
+       * the order lands on whichever account first claimed it, and then the
+       * buyer signs in — or signs up — as themselves.
+       *
+       * Refusing here made the person who paid for the eSIM the one who could
+       * not see it. So the order moves to the account that owns the paying
+       * address, rather than the claim being rewritten to point at an identity
+       * nobody verified. The address is the fact Stripe recorded at payment
+       * time; a Clerk id is just who got here first.
+       *
+       * The bar for a move is a *verified* address on the signed-in account.
+       * Without that, anyone who learned a session id could take someone
+       * else's order by typing their email into a new account.
+       */
+      const ownsPayingAddress = await userMatchesSessionPurchaser(session, userId, {
+        requireVerified: true,
+      });
+      if (!ownsPayingAddress) {
+        return { ok: false, status: 403, error: "This order is linked to another account" };
+      }
+
+      const moved = await setStripeClaimedBy(sessionId, userId);
+      if (!moved) {
+        return { ok: false, status: 502, error: "Failed to claim order" };
+      }
+      const afterMove = await fetchStripeSession(sessionId);
+      if (afterMove?.metadata?.claimedByUserId !== userId) {
+        return { ok: false, status: 403, error: "This order is linked to another account" };
+      }
+
+      // Best-effort tidy-up. The order is already on the right account; a
+      // stale id left on the old one shows a dashboard row that no longer
+      // resolves, which is untidy, not broken.
+      await removeClaimedOrderFromUser(claimedBy, orderId).catch(() => {});
+
+      await addClaimedOrderToUser(userId, orderId);
+      return { ok: true, orderId };
     }
     if (!claimedBy) {
       const updated = await setStripeClaimedBy(sessionId, userId);

package/templates/storefront/src/lib/order-route-guard.ts

@@ -0,0 +1,85 @@
+/**
+ * The gate every order-scoped route handler stands behind.
+ *
+ * Signed in, and the order is one this user has claimed. Both checks belong
+ * here rather than in each handler because a route handler is reachable
+ * directly, and an ownership check that only three of four routes perform is
+ * the one an attacker uses.
+ *
+ * Refusals are deliberately indistinguishable: an order that does not exist
+ * and an order belonging to somebody else both answer 404, so the route cannot
+ * be used to find out which order ids are real.
+ */
+import { auth } from "@clerk/nextjs/server";
+import { NextResponse } from "next/server";
+import { userOwnsOrder } from "@/lib/checkout-order-claim";
+import type { OrderLookupError } from "@/vendor/carrier/client";
+
+export type OrderRouteGuard =
+  | { ok: true; userId: string; orderId: string }
+  | { ok: false; response: NextResponse };
+
+export async function guardOrderRoute(
+  params: Promise<{ orderId: string }>,
+): Promise<OrderRouteGuard> {
+  const { userId } = await auth();
+  if (!userId) {
+    return { ok: false, response: NextResponse.json({ error: "Unauthorized" }, { status: 401 }) };
+  }
+
+  const { orderId } = await params;
+  if (!orderId) {
+    return {
+      ok: false,
+      response: NextResponse.json({ error: "orderId is required" }, { status: 400 }),
+    };
+  }
+
+  if (!(await userOwnsOrder(userId, orderId))) {
+    return {
+      ok: false,
+      response: NextResponse.json({ error: "Order not found" }, { status: 404 }),
+    };
+  }
+
+  return { ok: true, userId, orderId };
+}
+
+/**
+ * One fulfilment failure, as customer copy plus a status.
+ *
+ * `action` names the thing that did not happen ("read your usage", "cancel
+ * this plan"), because "something went wrong" tells the reader nothing about
+ * whether their eSIM is still working.
+ */
+export function fulfilmentFailureResponse(
+  reason: OrderLookupError,
+  action: string,
+  orderId: string,
+): NextResponse {
+  if (reason === "not-found") {
+    return NextResponse.json({ error: "Order not found", code: "not_found" }, { status: 404 });
+  }
+
+  if (reason === "unconfigured") {
+    console.error(
+      `[orders] NEXT_PUBLIC_CARRIER_API_URL is unset — cannot ${action} for ${orderId}`,
+    );
+    return NextResponse.json(
+      {
+        error: `We can't ${action} yet. Please contact support with your order number.`,
+        code: "fulfilment_unconfigured",
+      },
+      { status: 503 },
+    );
+  }
+
+  console.error(`[orders] failed to ${action} for ${orderId}: ${reason}`);
+  return NextResponse.json(
+    {
+      error: `We couldn't ${action} right now. Please try again in a moment.`,
+      code: "fulfilment_unavailable",
+    },
+    { status: 502 },
+  );
+}

package/templates/storefront/src/middleware.ts

@@ -9,7 +9,7 @@ const isPublicRoute = createRouteMatcher([
   "/sign-in(.*)",
   "/sign-up(.*)",
   "/api/health",
-  // MANGO-8/9: guest checkout API and post-payment success page are public
+  // Guest checkout API and post-payment success page are public
   // (user has not yet created an account at this point in the purchase flow)
   "/api/checkout/guest",
   "/checkout/success(.*)",