@carrierllc/mcp 0.11.16 → 0.12.0

package/templates/storefront/src/app/checkout/[templateId]/CheckoutClient.tsx

@@ -2,25 +2,34 @@
 /**
  * CheckoutClient
  *
- * MANGO-8/9: Purchase-first flow.
+ * Purchase-first flow.
  *
- * OLD behaviour: unauthenticated user → redirected to /sign-in (blocking).
- * NEW behaviour:
- *   - Unauthenticated → POST /api/checkout/guest → Stripe Checkout directly.
- *   - Authenticated   → use server-rendered session URL → Stripe Checkout.
+ *   Unauthenticated → POST /api/checkout/guest → pay.
+ *   Authenticated   → server-rendered session URL → pay.
  *
- * After Stripe payment success, the user lands on /checkout/success where they
- * are prompted to create an account (email + password, no phone) or sign in.
- * Then they are redirected to /activate/[orderId] for optional WhatsApp/phone setup.
+ * "Pay" is one of two things. With a Stripe publishable key configured the
+ * payment form is embedded in this page, and on completion we navigate to
+ * /checkout/success ourselves — Stripe's embedded form otherwise leaves the
+ * customer on a "payment received" panel with nowhere to go. Without a
+ * publishable key the browser goes to Stripe's hosted page and comes back.
+ * Both take money; the embedded one loses fewer people on the way.
+ *
+ * After payment the user lands on /checkout/success, where they create an
+ * account (email + password, no phone) or sign in, and are then sent to
+ * /activate/[orderId].
  *
  * Every string on this page is read by a customer. It names no environment
  * variable and gives no configuration instructions — an operator's deployment
  * problem is not something a shopper can act on, and printing it makes a store
  * look broken rather than busy.
  */
-import { useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { useAuth } from "@clerk/nextjs";
 import { useRouter } from "next/navigation";
+import {
+  EmbeddedStripeCheckout,
+  canEmbedStripeCheckout,
+} from "@/components/checkout/EmbeddedStripeCheckout";
 import { conversionEvents } from "@/lib/conversion-events";
 import { normalizeChannel } from "@/vendor/carrier/catalog-guard";
 import type { SkuTemplate } from "@/vendor/carrier/types";
@@ -46,13 +55,89 @@ function readChannel(): string {
   return normalizeChannel(params.get("channel") ?? params.get("utm_source"));
 }
 
+/** Internal signal: the embedded path failed but a hosted one is still worth trying. */
+class EmbedUnavailable extends Error {
+  constructor() {
+    super("embed_unavailable");
+    this.name = "EmbedUnavailable";
+  }
+}
+
 export function CheckoutClient({ plan, session }: Props) {
   const { isSignedIn, isLoaded } = useAuth();
   const router = useRouter();
   const [checkoutError, setCheckoutError] = useState<string | null>(null);
   const [loading, setLoading] = useState(false);
+  const [clientSecret, setClientSecret] = useState<string | null>(null);
+  const [sessionId, setSessionId] = useState<string | null>(null);
   const guestCheckoutPlanIdRef = useRef<string | null>(null);
   const authRefreshAttemptedRef = useRef(false);
+  /**
+   * Set once the embedded attempt has been given up on. The retry is hosted,
+   * and the flag stops a failing embed from looping through this component.
+   */
+  const embedAbandonedRef = useRef(false);
+
+  const startGuestCheckout = useCallback(
+    (wantEmbed: boolean) => {
+      // Named inner function so the hosted retry can call itself without the
+      // callback depending on its own identity.
+      const run = (embed: boolean): void => {
+        setLoading(true);
+        fetch("/api/checkout/guest", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            templateId: plan.id,
+            channel: readChannel(),
+            ...(embed ? { uiMode: "embedded" } : {}),
+          }),
+        })
+          .then(async (res) => {
+            if (!res.ok) {
+              // The route returns customer-safe copy for every refusal it knows
+              // about. Anything else (a proxy error page, say) gets the generic
+              // line rather than whatever text happened to come back.
+              const err = (await res.json().catch(() => ({}))) as { error?: string; code?: string };
+              if (embed && err.code === "embed_unavailable") throw new EmbedUnavailable();
+              throw new Error(err.code && err.error ? err.error : GENERIC_CHECKOUT_ERROR);
+            }
+            return res.json() as Promise<{
+              url?: string;
+              clientSecret?: string;
+              sessionId?: string;
+            }>;
+          })
+          .then((data) => {
+            if (embed && data.clientSecret && data.sessionId) {
+              setClientSecret(data.clientSecret);
+              setSessionId(data.sessionId);
+              setLoading(false);
+              return;
+            }
+            if (data.url) {
+              window.location.href = data.url;
+              return;
+            }
+            throw new Error(GENERIC_CHECKOUT_ERROR);
+          })
+          .catch((err: unknown) => {
+            if (err instanceof EmbedUnavailable && !embedAbandonedRef.current) {
+              // The embed could not be created. A hosted session still can be,
+              // and a customer who came here to pay should be allowed to.
+              embedAbandonedRef.current = true;
+              run(false);
+              return;
+            }
+            guestCheckoutPlanIdRef.current = null;
+            setCheckoutError(err instanceof Error ? err.message : GENERIC_CHECKOUT_ERROR);
+            setLoading(false);
+          });
+      };
+      run(wantEmbed);
+    },
+    [plan.id],
+  );
 
   useEffect(() => {
     if (!isLoaded) return;
@@ -74,44 +159,44 @@ export function CheckoutClient({ plan, session }: Props) {
       return;
     }
 
-    // Guest path (MANGO-8): call the guest checkout API — no auth required.
+    // Guest path: no auth required.
     if (guestCheckoutPlanIdRef.current === plan.id) return;
     guestCheckoutPlanIdRef.current = plan.id;
+    startGuestCheckout(canEmbedStripeCheckout);
+  }, [isLoaded, isSignedIn, plan, session, router, startGuestCheckout]);
 
-    setLoading(true);
-    fetch("/api/checkout/guest", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ templateId: plan.id, channel: readChannel() }),
-    })
-      .then(async (res) => {
-        if (!res.ok) {
-          // The route returns customer-safe copy for every refusal it knows
-          // about. Anything else (a proxy error page, say) gets the generic
-          // line rather than whatever text happened to come back.
-          const err = (await res.json().catch(() => ({}))) as { error?: string; code?: string };
-          throw new Error(err.code && err.error ? err.error : GENERIC_CHECKOUT_ERROR);
-        }
-        return res.json() as Promise<{ url: string }>;
-      })
-      .then(({ url }) => {
-        window.location.href = url;
-      })
-      .catch((err: unknown) => {
-        guestCheckoutPlanIdRef.current = null;
-        setCheckoutError(err instanceof Error ? err.message : GENERIC_CHECKOUT_ERROR);
-        setLoading(false);
-      });
-  }, [isLoaded, isSignedIn, plan, session, router]);
+  /**
+   * The payment cleared inside the iframe and no redirect was required.
+   *
+   * `replace`, not `push`: the back button must not return to a Checkout
+   * Session that has already been paid.
+   */
+  const handleComplete = useCallback(() => {
+    const params = new URLSearchParams({ templateId: plan.id });
+    if (sessionId) params.set("session_id", sessionId);
+    router.replace(`/checkout/success?${params.toString()}`);
+  }, [plan.id, router, sessionId]);
+
+  /** Stripe.js never loaded. Fall back to the page Stripe hosts itself. */
+  const handleEmbedUnavailable = useCallback(() => {
+    if (embedAbandonedRef.current) {
+      setCheckoutError(GENERIC_CHECKOUT_ERROR);
+      return;
+    }
+    embedAbandonedRef.current = true;
+    setClientSecret(null);
+    setSessionId(null);
+    startGuestCheckout(false);
+  }, [startGuestCheckout]);
 
   if (checkoutError) {
     return (
       <div className="mx-auto max-w-lg px-4 py-32 text-center">
         <p className="text-sand-700 dark:text-sand-200">{checkoutError}</p>
-        <p className="text-sm text-sand-400 mt-2">{plan.name}</p>
+        <p className="mt-2 text-sm text-sand-400">{plan.name}</p>
         <a
           href="/shop"
-          className="mt-6 inline-block rounded-full border border-sand-300 dark:border-sand-700 px-6 py-2 text-sm text-sand-900 dark:text-sand-50 hover:bg-white/10 transition-colors"
+          className="mt-6 inline-block rounded-full border border-sand-300 px-6 py-2 text-sm text-sand-900 transition-colors hover:bg-white/10 dark:border-sand-700 dark:text-sand-50"
         >
           ← Back to shop
         </a>
@@ -119,13 +204,31 @@ export function CheckoutClient({ plan, session }: Props) {
     );
   }
 
+  if (clientSecret) {
+    return (
+      <div className="mx-auto max-w-2xl px-4 py-16">
+        <h1 className="text-2xl font-semibold tracking-tight text-sand-900 dark:text-sand-50">
+          Almost there.
+        </h1>
+        <p className="mt-2 mb-8 text-sm text-sand-500">
+          {plan.name} — your QR code is ready the moment this clears.
+        </p>
+        <EmbeddedStripeCheckout
+          clientSecret={clientSecret}
+          onComplete={handleComplete}
+          onUnavailable={handleEmbedUnavailable}
+        />
+      </div>
+    );
+  }
+
   return (
     <div className="mx-auto max-w-lg px-4 py-32 text-center">
-      <div className="h-8 w-8 rounded-full border-2 border-[var(--brand-accent)] border-t-transparent animate-spin mx-auto mb-4" />
+      <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-sand-600 dark:text-sand-400">
         {loading ? "Preparing your checkout…" : "Redirecting to payment…"}
       </p>
-      <p className="text-sm text-sand-400 mt-2">{plan.name}</p>
+      <p className="mt-2 text-sm text-sand-400">{plan.name}</p>
     </div>
   );
 }

package/templates/storefront/src/app/checkout/success/CheckoutSuccessClient.tsx

@@ -2,7 +2,7 @@
 /**
  * CheckoutSuccessClient
  *
- * MANGO-8/9: Shown after Stripe payment success.
+ * Shown after Stripe payment success.
  *
  * - If already signed in: redirect immediately to /activate/[orderId].
  * - If not signed in: show email + password sign-up form (no phone).

package/templates/storefront/src/app/checkout/success/page.tsx

@@ -2,7 +2,7 @@ export const dynamic = "force-dynamic";
 /**
  * /checkout/success
  *
- * MANGO-8/9: Post-payment landing page.
+ * Post-payment landing page.
  *
  * The user arrives here after a successful Stripe Checkout payment.
  * Query params from Stripe: ?templateId=<id>&session_id=<stripe_session_id>

package/templates/storefront/src/app/dashboard/EsimControls.tsx

@@ -0,0 +1,293 @@
+"use client";
+/**
+ * Per-eSIM controls on the dashboard: how much is left, buy more, stop paying.
+ *
+ * The list on its own answered "did my purchase happen". These three answer
+ * the questions people actually come back for, and the third one is the
+ * reason: a plan that can only be cancelled by emailing support is a plan the
+ * customer cancels through their bank.
+ *
+ * Everything here loads lazily, one eSIM at a time, on expand. The dashboard
+ * already makes one fulfilment call per order to render the list; making three
+ * more per order up front would turn a slow page into an unusable one for the
+ * customer with six eSIMs, who is exactly the customer worth keeping.
+ */
+
+import { useCallback, useState } from "react";
+import {
+  daysUntil,
+  formatBytes,
+  formatDataAllowance,
+  formatPrice,
+  formatValidity,
+} from "@/vendor/geo";
+import type { EsimUsage, TopUpOption } from "@/vendor/carrier/types";
+
+interface Props {
+  orderId: string;
+  /** Already cancelled upstream. The cancel control is not offered again. */
+  cancelled: boolean;
+}
+
+type Loadable<T> =
+  | { phase: "idle" }
+  | { phase: "loading" }
+  | { phase: "ready"; value: T }
+  | { phase: "error"; message: string };
+
+const GENERIC_ERROR = "We couldn't reach your plan just now. Try again in a moment.";
+
+async function readJson<T>(res: Response): Promise<T & { error?: string }> {
+  return (await res.json().catch(() => ({}))) as T & { error?: string };
+}
+
+export function EsimControls({ orderId, cancelled: initiallyCancelled }: Props) {
+  const [open, setOpen] = useState(false);
+  const [usage, setUsage] = useState<Loadable<EsimUsage>>({ phase: "idle" });
+  const [topUps, setTopUps] = useState<Loadable<TopUpOption[]>>({ phase: "idle" });
+  const [cancelled, setCancelled] = useState(initiallyCancelled);
+  const [confirmingCancel, setConfirmingCancel] = useState(false);
+  const [cancelState, setCancelState] = useState<Loadable<true>>({ phase: "idle" });
+  const [buying, setBuying] = useState<string | null>(null);
+
+  const base = `/api/orders/${encodeURIComponent(orderId)}`;
+
+  const load = useCallback(async () => {
+    setUsage({ phase: "loading" });
+    setTopUps({ phase: "loading" });
+
+    const [usageRes, topUpRes] = await Promise.allSettled([
+      fetch(`${base}/usage`, { cache: "no-store" }),
+      fetch(`${base}/top-up-options`, { cache: "no-store" }),
+    ]);
+
+    if (usageRes.status === "fulfilled") {
+      const payload = await readJson<{ usage?: EsimUsage }>(usageRes.value);
+      setUsage(
+        usageRes.value.ok && payload.usage
+          ? { phase: "ready", value: payload.usage }
+          : { phase: "error", message: payload.error ?? GENERIC_ERROR },
+      );
+    } else {
+      setUsage({ phase: "error", message: GENERIC_ERROR });
+    }
+
+    if (topUpRes.status === "fulfilled") {
+      const payload = await readJson<{ options?: TopUpOption[] }>(topUpRes.value);
+      setTopUps(
+        topUpRes.value.ok && Array.isArray(payload.options)
+          ? { phase: "ready", value: payload.options }
+          : { phase: "error", message: payload.error ?? GENERIC_ERROR },
+      );
+    } else {
+      setTopUps({ phase: "error", message: GENERIC_ERROR });
+    }
+  }, [base]);
+
+  function toggle() {
+    const next = !open;
+    setOpen(next);
+    if (next && usage.phase === "idle") void load();
+  }
+
+  async function buyTopUp(option: TopUpOption) {
+    setBuying(option.id);
+    try {
+      const res = await fetch("/api/checkout/guest", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          templateId: option.id,
+          channel: "dashboard-topup",
+          topUpForOrderId: orderId,
+        }),
+      });
+      const payload = await readJson<{ url?: string }>(res);
+      if (!res.ok || !payload.url) throw new Error(payload.error ?? GENERIC_ERROR);
+      window.location.href = payload.url;
+    } catch (err) {
+      setBuying(null);
+      setTopUps({
+        phase: "error",
+        message: err instanceof Error ? err.message : GENERIC_ERROR,
+      });
+    }
+  }
+
+  async function doCancel() {
+    setCancelState({ phase: "loading" });
+    try {
+      const res = await fetch(`${base}/cancel`, { method: "POST" });
+      const payload = await readJson<{ cancelledAt?: string }>(res);
+      if (!res.ok) throw new Error(payload.error ?? GENERIC_ERROR);
+      setCancelled(true);
+      setConfirmingCancel(false);
+      setCancelState({ phase: "ready", value: true });
+    } catch (err) {
+      setCancelState({
+        phase: "error",
+        message: err instanceof Error ? err.message : GENERIC_ERROR,
+      });
+    }
+  }
+
+  return (
+    <div className="mt-4 border-t border-sand-200 pt-4 dark:border-sand-800">
+      <button
+        type="button"
+        onClick={toggle}
+        aria-expanded={open}
+        className="text-sm font-medium text-sand-600 hover:text-sand-900 dark:text-sand-400 dark:hover:text-sand-50"
+      >
+        {open ? "Hide plan details" : "Usage, top-up and cancel"}
+      </button>
+
+      {open && (
+        <div className="mt-4 grid gap-6">
+          <UsageMeter state={usage} />
+
+          <section>
+            <p className="mb-2 text-xs font-semibold tracking-wide text-sand-500 uppercase">
+              Add more data
+            </p>
+            {topUps.phase === "loading" && <p className="text-sm text-sand-500">Checking…</p>}
+            {topUps.phase === "error" && (
+              <p className="text-sm text-sand-500">{topUps.message}</p>
+            )}
+            {topUps.phase === "ready" && topUps.value.length === 0 && (
+              <p className="text-sm text-sand-500">
+                This plan can&apos;t be topped up. Buy another when it runs out.
+              </p>
+            )}
+            {topUps.phase === "ready" && topUps.value.length > 0 && (
+              <ul className="grid gap-2">
+                {topUps.value.map((option) => (
+                  <li
+                    key={option.id}
+                    className="flex flex-wrap items-center justify-between gap-3 rounded-xl border border-sand-200 px-4 py-3 dark:border-sand-800"
+                  >
+                    <div>
+                      <p className="text-sm font-medium text-sand-900 dark:text-sand-50">
+                        {option.name}
+                      </p>
+                      <p className="text-xs text-sand-500">
+                        {formatDataAllowance(option.dataGb)} · {formatValidity(option.validityDays)}
+                      </p>
+                    </div>
+                    <button
+                      type="button"
+                      onClick={() => void buyTopUp(option)}
+                      disabled={buying !== null}
+                      className="rounded-full px-4 py-2 text-sm font-semibold text-white transition-opacity hover:opacity-90 disabled:opacity-50"
+                      style={{ background: "var(--brand-accent)" }}
+                    >
+                      {buying === option.id
+                        ? "Opening checkout…"
+                        : formatPrice(option.price_cents, option.currency)}
+                    </button>
+                  </li>
+                ))}
+              </ul>
+            )}
+          </section>
+
+          <section>
+            <p className="mb-2 text-xs font-semibold tracking-wide text-sand-500 uppercase">
+              Cancel
+            </p>
+            {cancelled ? (
+              <p className="text-sm text-sand-500">
+                This plan is cancelled. Any data already on the eSIM stays usable until it
+                expires.
+              </p>
+            ) : confirmingCancel ? (
+              <div>
+                <p className="mb-3 text-sm text-sand-700 dark:text-sand-300">
+                  Cancel this plan? It stops renewing. Data already paid for stays on the eSIM
+                  until it expires, and this cannot be undone from here.
+                </p>
+                <div className="flex flex-wrap gap-3">
+                  <button
+                    type="button"
+                    onClick={() => void doCancel()}
+                    disabled={cancelState.phase === "loading"}
+                    className="rounded-full bg-red-600 px-5 py-2 text-sm font-semibold text-white transition-opacity hover:opacity-90 disabled:opacity-50"
+                  >
+                    {cancelState.phase === "loading" ? "Cancelling…" : "Yes, cancel it"}
+                  </button>
+                  <button
+                    type="button"
+                    onClick={() => setConfirmingCancel(false)}
+                    className="rounded-full border border-sand-300 px-5 py-2 text-sm text-sand-900 dark:border-sand-700 dark:text-sand-50"
+                  >
+                    Keep it
+                  </button>
+                </div>
+                {cancelState.phase === "error" && (
+                  <p className="mt-3 text-sm text-sand-500">{cancelState.message}</p>
+                )}
+              </div>
+            ) : (
+              <button
+                type="button"
+                onClick={() => setConfirmingCancel(true)}
+                className="text-sm font-medium text-sand-500 underline underline-offset-4 hover:text-sand-900 dark:hover:text-sand-50"
+              >
+                Cancel this plan
+              </button>
+            )}
+          </section>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function UsageMeter({ state }: { state: Loadable<EsimUsage> }) {
+  if (state.phase === "loading") {
+    return <p className="text-sm text-sand-500">Reading your usage…</p>;
+  }
+  if (state.phase === "error") {
+    return <p className="text-sm text-sand-500">{state.message}</p>;
+  }
+  if (state.phase !== "ready") return null;
+
+  const { usedBytes, totalBytes, expiresAt } = state.value;
+  const left = daysUntil(expiresAt);
+  // Only drawn when the operator stated a ceiling. A bar with an invented
+  // denominator is a number the customer plans a trip around.
+  const pct =
+    typeof totalBytes === "number" && totalBytes > 0
+      ? Math.min(100, Math.round((usedBytes / totalBytes) * 100))
+      : null;
+
+  return (
+    <section>
+      <p className="mb-2 text-xs font-semibold tracking-wide text-sand-500 uppercase">Usage</p>
+      <p className="text-sm text-sand-900 dark:text-sand-50">
+        {formatBytes(usedBytes)} used
+        {typeof totalBytes === "number" ? ` of ${formatBytes(totalBytes)}` : ""}
+      </p>
+      {pct !== null && (
+        <div
+          role="progressbar"
+          aria-valuenow={pct}
+          aria-valuemin={0}
+          aria-valuemax={100}
+          aria-label="Data used"
+          className="mt-2 h-2 w-full overflow-hidden rounded-full bg-sand-200 dark:bg-sand-800"
+        >
+          <div
+            className="h-full rounded-full"
+            style={{ width: `${pct}%`, background: "var(--brand-accent)" }}
+          />
+        </div>
+      )}
+      {left !== null && (
+        <p className="mt-2 text-xs text-sand-500">
+          {left === 0 ? "Expires today" : left === 1 ? "1 day left" : `${left} days left`}
+        </p>
+      )}
+    </section>
+  );
+}

package/templates/storefront/src/app/dashboard/page.tsx

@@ -14,6 +14,7 @@ import { redirect } from "next/navigation";
 import { listClaimedOrderIds } from "@/lib/checkout-order-claim";
 import { fetchOrder } from "@/vendor/carrier/client";
 import type { EsimOrder, OrderStatus } from "@/vendor/carrier/types";
+import { EsimControls } from "./EsimControls";
 
 export const metadata = { title: "Dashboard" };
 
@@ -47,7 +48,11 @@ function OrderRow({ orderId, order }: { orderId: string; order: EsimOrder | null
           {order?.planName ?? order?.templateId ?? "eSIM order"}
         </p>
         <span className="text-xs text-sand-500">
-          {order ? STATUS_LABEL[order.status] : "Status unavailable"}
+          {order
+            ? order.cancelledAt
+              ? "Cancelled"
+              : STATUS_LABEL[order.status]
+            : "Status unavailable"}
         </span>
       </div>
       <p className="mt-1 font-mono text-xs break-all text-sand-400">{orderId}</p>
@@ -63,6 +68,12 @@ function OrderRow({ orderId, order }: { orderId: string; order: EsimOrder | null
       >
         {order?.status === "ready" ? "View QR code" : "View order"} →
       </a>
+      {/* Only once there is an eSIM behind the row. Usage, top-up and cancel
+          all address a thing that exists; offering them over a pending order
+          invites three calls that can only answer "not yet". */}
+      {order?.status === "ready" && (
+        <EsimControls orderId={orderId} cancelled={Boolean(order.cancelledAt)} />
+      )}
     </li>
   );
 }