@carrierllc/mcp 0.11.17 → 0.12.0

package/dist/index.js

@@ -65,7 +65,7 @@ import {
   usageOverPeriodParams,
   verifyStorefront,
   withOcsListSummary
-} from "./chunk-EHGZRVSO.js";
+} from "./chunk-J52VP7E7.js";
 import "./chunk-SHKKVIIA.js";
 
 // src/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carrierllc/mcp",
-  "version": "0.11.17",
+  "version": "0.12.0",
   "description": "Carrier MCP \u2014 natural-language control of MVNO/eSIM fleets via eSIMVault OCS. Stdio mode for direct integration with Claude Desktop, Cursor, Windsurf, and MCP-compatible clients. Ships the `carrier` CLI (plugin install + white-label eSIM storefront scaffold).",
   "license": "MIT",
   "author": "Carrier (Lifecycle Innovations Limited)",

package/plugin/carrier/agents/carrier-storefront-builder.md

@@ -1,15 +1,15 @@
 ---
 name: carrier-storefront-builder
-description: Scaffolds, white-labels, and deploys the customer-facing eSIM storefront (Mango template) via @carrierllc/cli, and keeps its plans in sync with the Carrier fleet. Use to launch or rebrand a storefront.
+description: Scaffolds, white-labels, and deploys the customer-facing eSIM storefront via @carrierllc/cli, and keeps its plans in sync with the Carrier fleet. Use to launch or rebrand a storefront.
 ---
 
 You build and ship white-labeled eSIM storefronts on top of a Carrier fleet.
 
-The storefront is a Next.js app (Mango-derived template) scaffolded by `@carrierllc/cli`. Its single white-label surface is `src/brand.config.ts` (name, tagline, colors, domain, support, social).
+The storefront is a Next.js app (bundled template) scaffolded by `@carrierllc/cli`. Its single white-label surface is `src/brand.config.ts` (name, tagline, colors, domain, support, social).
 
 Workflow:
 1. **Scaffold** — `npx @carrierllc/cli site create <dir>` with the operator's brand (name, domain, accent hex, support email).
-2. **Brand** — verify `src/brand.config.ts` and `globals.css` reflect the brand; the default accent is Carrier Flame `#FF6B35` on dark `#080C16` — replace with the operator's palette. Check there are no leftover "Mango" strings.
+2. **Brand** — verify `src/brand.config.ts` and `globals.css` reflect the brand; the default accent is Carrier Flame `#FF6B35` on dark `#080C16` — replace with the operator's palette. The template ships brand-free — every name a page prints comes from `brand.config.ts`.
 3. **Wire** — set `NEXT_PUBLIC_CARRIER_API_URL` in `.env.local`; ensure the plans shown match `pricing_plans` / `list_package_templates` from the fleet.
 4. **Build & deploy** — `npx @carrierllc/cli site deploy <dir>` → Cloudflare Pages (`wrangler login` first).
 5. **Verify** — load the live URL, confirm it renders, plans are correct, and checkout reaches the control plane.

package/plugin/carrier/skills/storefront/SKILL.md

@@ -6,7 +6,7 @@ argument-hint: "[create|logo|deploy|targets|clerk|rebrand] [dir]"
 
 # Storefront
 
-Roll out the customer-facing eSIM storefront (Mango template, white-labeled) on top of your Carrier fleet.
+Roll out the customer-facing eSIM storefront (white-labeled) on top of your Carrier fleet.
 
 Works for **any developer** with Carrier MCP (`https://mcp.carrier.llc/mcp`) or the `carrier` CLI. You do not need an image-API key on your laptop.
 
@@ -42,7 +42,7 @@ MCP (any authenticated Carrier user):
 generate_storefront_logo
   name: Bananas
   accent: #FF8A00
-  tagline: Travel eSIM that just works.
+  tagline: Data that works wherever you land.
 ```
 
 Write the returned `svg` to `public/brand/logo.svg`. Nav and icons read that path.

package/templates/storefront/src/app/activate/[orderId]/ActivateClient.tsx

@@ -2,14 +2,19 @@
 /**
  * ActivateClient
  *
- * MANGO-8/9: Shown after sign-up/sign-in on /activate/[orderId].
+ * Shown after sign-up/sign-in on /activate/[orderId].
  *
  * - Fetches the order and shows the real eSIM QR code once provisioning is done.
- * - Falls back to the SM-DP+ address and matching ID for manual entry whenever
- *   the QR image is missing — every phone accepts those typed by hand.
+ * - Offers a one-tap install, then the SM-DP+ address and matching ID, then
+ *   written steps. A QR code is useless on the one phone the customer is
+ *   reading this on, so every layer below it has to stand on its own.
  * - Says plainly when it cannot read the order at all. The page used to print
  *   a fixed reassurance that a QR code was on its way, and then never
  *   ask anyone anything, which reads as progress and is not.
+ * - Never spins forever. A spinner is a promise that something is still
+ *   happening; when the answer is "this order does not exist", "it is not
+ *   yours", or "provisioning has not finished in the time it normally takes",
+ *   the page stops and says which, with something the customer can do next.
  * - Optionally collects phone number / WhatsApp for eSIM delivery notifications.
  *   Phone is NEVER required — user can skip.
  */
@@ -23,12 +28,32 @@ interface Props {
 type LoadState =
   | { phase: "loading" }
   | { phase: "ready"; order: EsimOrder }
-  | { phase: "error"; message: string };
+  /**
+   * `terminal` means retrying cannot change the answer. A 404 or a 403 is a
+   * fact about this order, not a hiccup, so the page offers support instead of
+   * a "Try again" button that will fail identically.
+   */
+  | { phase: "error"; message: string; terminal: boolean }
+  /** Still provisioning after the polls ran out. Not an error, not progress. */
+  | { phase: "stalled"; order: EsimOrder };
 
 /** Provisioning is usually seconds. Poll a bounded number of times, then stop. */
 const POLL_INTERVAL_MS = 4000;
 const MAX_POLLS = 15;
 
+/**
+ * Apple's universal eSIM install link — iOS 17.4 and later hand the activation
+ * string straight to Settings, so the customer never types anything.
+ *
+ * Nothing equivalent exists on Android: install there is Settings → Network →
+ * add eSIM → enter manually, which is what the written steps below are for.
+ */
+function directInstallUrl(activationCode: string): string {
+  return `https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=${encodeURIComponent(
+    activationCode,
+  )}`;
+}
+
 export function ActivateClient({ orderId }: Props) {
   const [phone, setPhone] = useState("");
   const [submitted, setSubmitted] = useState(false);
@@ -37,6 +62,11 @@ export function ActivateClient({ orderId }: Props) {
   const [state, setState] = useState<LoadState>({ phase: "loading" });
   const [copied, setCopied] = useState(false);
   const pollsRef = useRef(0);
+  // Bumped by "Check again". The polling effect depends on it, so a new value
+  // tears the old loop down and starts a fresh one. Resetting the counter and
+  // calling loadOrder once would fetch a single time and then sit on the
+  // spinner forever, because loadOrder is stable and the effect never re-runs.
+  const [pollCycle, setPollCycle] = useState(0);
 
   const loadOrder = useCallback(async (): Promise<EsimOrder | null> => {
     try {
@@ -46,11 +76,21 @@ export function ActivateClient({ orderId }: Props) {
       const payload = (await res.json().catch(() => ({}))) as {
         order?: EsimOrder;
         error?: string;
+        code?: string;
       };
       if (!res.ok || !payload.order) {
+        // 404 and 403 are settled answers: the order is unknown, or it is not
+        // this account's. Retrying returns the same status, and a spinner over
+        // the top of it is a lie about what the page is waiting for.
+        const terminal = res.status === 404 || res.status === 403 || payload.code === "not_found";
         setState({
           phase: "error",
-          message: payload.error ?? "We could not load your eSIM details right now.",
+          terminal,
+          message:
+            payload.error ??
+            (terminal
+              ? "We can't find this order on your account."
+              : "We could not load your eSIM details right now."),
         });
         return null;
       }
@@ -59,6 +99,7 @@ export function ActivateClient({ orderId }: Props) {
     } catch {
       setState({
         phase: "error",
+        terminal: false,
         message: "We could not reach your eSIM details. Check your connection and try again.",
       });
       return null;
@@ -73,10 +114,16 @@ export function ActivateClient({ orderId }: Props) {
       const order = await loadOrder();
       if (cancelled) return;
       const stillWorking = order?.status === "pending" || order?.status === "provisioning";
-      if (stillWorking && pollsRef.current < MAX_POLLS) {
+      if (!stillWorking) return;
+      if (pollsRef.current < MAX_POLLS) {
         pollsRef.current += 1;
         timer = setTimeout(tick, POLL_INTERVAL_MS);
+        return;
       }
+      // Out of polls and still not ready. Stop the spinner and say so — it has
+      // now taken materially longer than provisioning normally does, and
+      // "we're preparing your eSIM" under an animation is no longer true.
+      setState({ phase: "stalled", order });
     }
 
     void tick();
@@ -84,7 +131,7 @@ export function ActivateClient({ orderId }: Props) {
       cancelled = true;
       if (timer) clearTimeout(timer);
     };
-  }, [loadOrder]);
+  }, [loadOrder, pollCycle]);
 
   async function handlePhoneSubmit(e: FormEvent<HTMLFormElement>) {
     e.preventDefault();
@@ -120,7 +167,8 @@ export function ActivateClient({ orderId }: Props) {
     }
   }
 
-  const order = state.phase === "ready" ? state.order : null;
+  const order =
+    state.phase === "ready" || state.phase === "stalled" ? state.order : null;
   const ready = order?.status === "ready";
   const manualCode =
     order?.activationCode ??
@@ -150,27 +198,68 @@ export function ActivateClient({ orderId }: Props) {
         {state.phase === "error" && (
           <>
             <p className="text-sand-900 dark:text-sand-50 text-sm font-medium mb-2">
-              We couldn&apos;t load your eSIM
+              {state.terminal ? "We can't show this eSIM" : "We couldn't load your eSIM"}
             </p>
             <p className="text-sand-600 dark:text-sand-400 text-sm mb-4">{state.message}</p>
             <p className="text-sand-400 text-xs mb-4">
               Your payment is safe and your order number is above. Quote it if you contact us.
             </p>
+            <div className="flex items-center justify-center gap-3">
+              {/* No "Try again" on a terminal answer: the same request would
+                  return the same status, and a button that cannot work is
+                  worse than no button. */}
+              {!state.terminal && (
+                <button
+                  type="button"
+                  onClick={() => {
+                    pollsRef.current = 0;
+                    setState({ phase: "loading" });
+                    void loadOrder();
+                  }}
+                  className="rounded-full bg-[var(--brand-accent)] px-5 py-2 text-sm font-semibold text-white transition-opacity hover:opacity-90"
+                >
+                  Try again
+                </button>
+              )}
+              <a
+                href="/contact"
+                className={
+                  state.terminal
+                    ? "rounded-full bg-[var(--brand-accent)] px-5 py-2 text-sm font-semibold text-white transition-opacity hover:opacity-90"
+                    : "rounded-full border border-sand-300 dark:border-sand-700 px-5 py-2 text-sm text-sand-900 dark:text-sand-50 hover:bg-white/10 transition-colors"
+                }
+              >
+                Contact support
+              </a>
+            </div>
+          </>
+        )}
+
+        {state.phase === "stalled" && (
+          <>
+            <p className="text-sand-900 dark:text-sand-50 text-sm font-medium mb-2">
+              This is taking longer than it should
+            </p>
+            <p className="text-sand-600 dark:text-sand-400 text-sm mb-4">
+              Your payment went through and your order is queued, but the eSIM isn&apos;t ready
+              yet. We&apos;ll email your QR code as soon as it is — you don&apos;t have to wait
+              here.
+            </p>
             <div className="flex items-center justify-center gap-3">
               <button
                 type="button"
                 onClick={() => {
                   pollsRef.current = 0;
                   setState({ phase: "loading" });
-                  void loadOrder();
+                  setPollCycle((n) => n + 1);
                 }}
-                className="rounded-full bg-[var(--brand-accent)] px-5 py-2 text-sm font-semibold text-white transition-opacity hover:opacity-90"
+                className="rounded-full border border-sand-300 dark:border-sand-700 px-5 py-2 text-sm text-sand-900 dark:text-sand-50 hover:bg-white/10 transition-colors"
               >
-                Try again
+                Check again
               </button>
               <a
                 href="/contact"
-                className="rounded-full border border-sand-300 dark:border-sand-700 px-5 py-2 text-sm text-sand-900 dark:text-sand-50 hover:bg-white/10 transition-colors"
+                className="rounded-full bg-[var(--brand-accent)] px-5 py-2 text-sm font-semibold text-white transition-opacity hover:opacity-90"
               >
                 Contact support
               </a>
@@ -178,7 +267,7 @@ export function ActivateClient({ orderId }: Props) {
           </>
         )}
 
-        {order && !ready && order.status !== "failed" && (
+        {state.phase === "ready" && order && !ready && order.status !== "failed" && (
           <>
             <div className="h-8 w-8 rounded-full border-2 border-[var(--brand-accent)] border-t-transparent animate-spin mx-auto mb-4" />
             <p className="text-sand-600 dark:text-sand-400 text-sm mb-2">
@@ -234,6 +323,18 @@ export function ActivateClient({ orderId }: Props) {
         )}
       </div>
 
+      {/* One tap, no typing — iOS 17.4+ only, and harmless everywhere else:
+          a phone that cannot handle the link opens a page that explains the
+          manual route, which is the next card down. */}
+      {ready && manualCode && (
+        <a
+          href={directInstallUrl(manualCode)}
+          className="mb-4 block w-full rounded-full bg-[var(--brand-accent)] px-6 py-3 text-center text-sm font-semibold text-white transition-opacity hover:opacity-90"
+        >
+          Install this eSIM on this iPhone
+        </a>
+      )}
+
       {/* Manual install — always available once we know the credentials, because
           a QR is useless on the one phone the customer is reading this on. */}
       {ready && (order?.smdpAddress || manualCode) && (
@@ -276,6 +377,36 @@ export function ActivateClient({ orderId }: Props) {
               {copied ? "Copied" : "Copy activation string"}
             </button>
           )}
+
+          {/* The steps in words. A customer whose camera cannot reach a second
+              screen, and whose phone is too old for the one-tap link, has the
+              credentials above and no idea where to type them. */}
+          <div className="mt-6 grid gap-5 border-t border-sand-200 pt-5 dark:border-sand-800">
+            <div>
+              <p className="mb-2 text-xs font-semibold tracking-wide text-sand-500 uppercase">
+                On iPhone
+              </p>
+              <ol className="list-decimal space-y-1 pl-4 text-sm text-sand-700 dark:text-sand-300">
+                <li>Open Settings, then Cellular (or Mobile Service).</li>
+                <li>Tap Add eSIM, then Use QR Code.</li>
+                <li>Tap Enter Details Manually.</li>
+                <li>Paste the SM-DP+ address and activation code from above.</li>
+                <li>Leave data roaming on — that is how the plan connects abroad.</li>
+              </ol>
+            </div>
+            <div>
+              <p className="mb-2 text-xs font-semibold tracking-wide text-sand-500 uppercase">
+                On Android
+              </p>
+              <ol className="list-decimal space-y-1 pl-4 text-sm text-sand-700 dark:text-sand-300">
+                <li>Open Settings, then Network &amp; internet.</li>
+                <li>Tap SIMs, then Add SIM or Download a SIM instead.</li>
+                <li>Choose Need help? then Enter it manually.</li>
+                <li>Paste the activation code from above.</li>
+                <li>Turn on roaming for this SIM once it appears.</li>
+              </ol>
+            </div>
+          </div>
         </div>
       )}
 

package/templates/storefront/src/app/activate/[orderId]/page.tsx

@@ -2,7 +2,7 @@ export const dynamic = "force-dynamic";
 /**
  * /activate/[orderId]
  *
- * MANGO-8/9: Post-purchase eSIM activation page.
+ * Post-purchase eSIM activation page.
  *
  * Phone number / WhatsApp is collected HERE — optionally — after the user
  * has already paid and created their account. It is never required at sign-up.

package/templates/storefront/src/app/api/checkout/guest/route.ts

@@ -1,14 +1,23 @@
 /**
  * POST /api/checkout/guest
  *
- * MANGO-8/9: Purchase-first flow — creates a Stripe Checkout session for
+ * Purchase-first flow — creates a Stripe Checkout session for
  * unauthenticated users. No Clerk auth required.
  *
- * Body: { templateId: string, channel?: string }
+ * Body: { templateId: string, channel?: string, uiMode?: "hosted" | "embedded" }
  *
- * Returns: { url: string } — Stripe-hosted checkout URL
+ * Returns one of:
+ *   { url: string }                          — hosted: send the browser there
+ *   { clientSecret: string, sessionId }       — embedded: mount it in our page
  *
- * The Stripe success_url encodes the templateId so the /checkout/success
+ * Embedded is asked for only when the storefront has a Stripe publishable key,
+ * and the route still answers "hosted" for anything else, so a deploy without
+ * one keeps selling. The session is created with redirect_on_completion set to
+ * `if_required`: a redirect-based payment method still returns through
+ * `return_url`, and a plain card finishes in the iframe and hands control back
+ * to the page, which navigates onward itself.
+ *
+ * The success / return URL encodes the templateId so the /checkout/success
  * page can display the correct plan and prompt sign-up / sign-in.
  *
  * The line item is built inline from the plan's own price (`price_data`, no
@@ -22,10 +31,22 @@ import { NextRequest, NextResponse } from "next/server";
 import { fetchTemplateCatalog } from "@/vendor/carrier/client";
 import { decideGuestCheckout, normalizeChannel } from "@/vendor/carrier/catalog-guard";
 
+interface GuestCheckoutBody {
+  templateId?: string;
+  channel?: string;
+  uiMode?: string;
+  /**
+   * Set when this purchase adds data to an eSIM that already exists. Carried
+   * into Stripe metadata so fulfilment tops up that ICCID instead of
+   * provisioning a second eSIM the customer neither wants nor can install.
+   */
+  topUpForOrderId?: string;
+}
+
 export async function POST(req: NextRequest): Promise<NextResponse> {
-  let body: { templateId?: string; channel?: string };
+  let body: GuestCheckoutBody;
   try {
-    body = (await req.json()) as { templateId?: string; channel?: string };
+    body = (await req.json()) as GuestCheckoutBody;
   } catch {
     return NextResponse.json({ error: "Invalid request body" }, { status: 400 });
   }
@@ -71,6 +92,12 @@ export async function POST(req: NextRequest): Promise<NextResponse> {
   const successUrl =
     `${appUrl}/checkout/success?templateId=${encodeURIComponent(templateId)}&session_id={CHECKOUT_SESSION_ID}`;
   const cancelUrl = `${appUrl}/shop`;
+  const embedded = body.uiMode === "embedded";
+  // Same charset gate the rest of the storefront applies to a Stripe session id.
+  const topUpForOrderId =
+    typeof body.topUpForOrderId === "string" && /^[A-Za-z0-9_-]{1,256}$/.test(body.topUpForOrderId)
+      ? body.topUpForOrderId
+      : null;
 
   const formBody = new URLSearchParams({
     mode: "payment",
@@ -79,8 +106,16 @@ export async function POST(req: NextRequest): Promise<NextResponse> {
     "line_items[0][price_data][product_data][name]": plan.name,
     "line_items[0][price_data][product_data][description]": plan.description,
     "line_items[0][quantity]": "1",
-    success_url: successUrl,
-    cancel_url: cancelUrl,
+    // Embedded sessions take `return_url` and reject `success_url` /
+    // `cancel_url`: there is no hosted page to come back from, and cancelling
+    // is just closing the form.
+    ...(embedded
+      ? {
+          ui_mode: "embedded",
+          redirect_on_completion: "if_required",
+          return_url: successUrl,
+        }
+      : { success_url: successUrl, cancel_url: cancelUrl }),
     // Store templateId in BOTH session and payment_intent metadata so the
     // provisioning webhook can read it. The `checkout.session.completed` event
     // exposes `session.metadata` (NOT `payment_intent.metadata`), so the
@@ -95,6 +130,15 @@ export async function POST(req: NextRequest): Promise<NextResponse> {
     "payment_intent_data[metadata][channel]": channel,
     // Allow guest checkout (no Stripe account required)
     "payment_method_collection": "always",
+    // Session-level and payment-intent-level, for the same reason templateId
+    // is: `checkout.session.completed` only exposes session metadata, and a
+    // top-up that loses its target order provisions a brand-new eSIM.
+    ...(topUpForOrderId
+      ? {
+          "metadata[topUpForOrderId]": topUpForOrderId,
+          "payment_intent_data[metadata][topUpForOrderId]": topUpForOrderId,
+        }
+      : {}),
   });
 
   const resp = await fetch("https://api.stripe.com/v1/checkout/sessions", {
@@ -117,6 +161,25 @@ export async function POST(req: NextRequest): Promise<NextResponse> {
     );
   }
 
-  const session = (await resp.json()) as { url: string };
+  const session = (await resp.json()) as {
+    id?: string;
+    url?: string;
+    client_secret?: string;
+  };
+
+  if (embedded) {
+    if (!session.client_secret || !session.id) {
+      // Stripe accepted the session but did not return what an embedded form
+      // needs. Say so rather than shipping an empty iframe — the client falls
+      // back to the hosted page on this code.
+      console.error("[checkout] embedded session has no client_secret");
+      return NextResponse.json(
+        { error: "We could not start checkout. Please try again in a moment.", code: "embed_unavailable" },
+        { status: 502 },
+      );
+    }
+    return NextResponse.json({ clientSecret: session.client_secret, sessionId: session.id });
+  }
+
   return NextResponse.json({ url: session.url });
 }

package/templates/storefront/src/app/api/orders/[orderId]/cancel/route.ts

@@ -0,0 +1,33 @@
+/**
+ * POST /api/orders/[orderId]/cancel
+ *
+ * Stop billing one eSIM. Signed-in callers only, and only for an order they
+ * have already claimed.
+ *
+ * POST rather than DELETE because what happens upstream is a state change on a
+ * plan, not the removal of a record: the order, the ICCID and the usage
+ * history all survive a cancellation and the customer can still read them.
+ */
+import { NextResponse } from "next/server";
+import { fulfilmentFailureResponse, guardOrderRoute } from "@/lib/order-route-guard";
+import { cancelOrder } from "@/vendor/carrier/client";
+
+export const dynamic = "force-dynamic";
+
+interface Context {
+  params: Promise<{ orderId: string }>;
+}
+
+export async function POST(_req: Request, ctx: Context): Promise<NextResponse> {
+  const guard = await guardOrderRoute(ctx.params);
+  if (!guard.ok) return guard.response;
+
+  const result = await cancelOrder(guard.orderId);
+  if (result.ok) {
+    return NextResponse.json({
+      cancelledAt: result.cancelledAt ?? new Date().toISOString(),
+    });
+  }
+
+  return fulfilmentFailureResponse(result.reason, "cancel this plan", guard.orderId);
+}

package/templates/storefront/src/app/api/orders/[orderId]/top-up-options/route.ts

@@ -0,0 +1,28 @@
+/**
+ * GET /api/orders/[orderId]/top-up-options
+ *
+ * What more data on this eSIM would cost. Signed-in callers only, and only for
+ * an order they have already claimed.
+ *
+ * An empty list is a successful answer: this plan cannot be topped up. The
+ * dashboard says so rather than showing a button that refuses on tap.
+ */
+import { NextResponse } from "next/server";
+import { fulfilmentFailureResponse, guardOrderRoute } from "@/lib/order-route-guard";
+import { fetchTopUpOptions } from "@/vendor/carrier/client";
+
+export const dynamic = "force-dynamic";
+
+interface Context {
+  params: Promise<{ orderId: string }>;
+}
+
+export async function GET(_req: Request, ctx: Context): Promise<NextResponse> {
+  const guard = await guardOrderRoute(ctx.params);
+  if (!guard.ok) return guard.response;
+
+  const lookup = await fetchTopUpOptions(guard.orderId);
+  if (lookup.ok) return NextResponse.json({ options: lookup.options });
+
+  return fulfilmentFailureResponse(lookup.reason, "load top-up options", guard.orderId);
+}

package/templates/storefront/src/app/api/orders/[orderId]/usage/route.ts

@@ -0,0 +1,25 @@
+/**
+ * GET /api/orders/[orderId]/usage
+ *
+ * The usage meter's data source. Signed-in callers only, and only for an order
+ * they have already claimed.
+ */
+import { NextResponse } from "next/server";
+import { fulfilmentFailureResponse, guardOrderRoute } from "@/lib/order-route-guard";
+import { fetchUsage } from "@/vendor/carrier/client";
+
+export const dynamic = "force-dynamic";
+
+interface Context {
+  params: Promise<{ orderId: string }>;
+}
+
+export async function GET(_req: Request, ctx: Context): Promise<NextResponse> {
+  const guard = await guardOrderRoute(ctx.params);
+  if (!guard.ok) return guard.response;
+
+  const lookup = await fetchUsage(guard.orderId);
+  if (lookup.ok) return NextResponse.json({ usage: lookup.usage });
+
+  return fulfilmentFailureResponse(lookup.reason, "read your usage", guard.orderId);
+}

package/templates/storefront/src/app/api/profile/phone/route.ts

@@ -1,7 +1,7 @@
 /**
  * POST /api/profile/phone
  *
- * MANGO-8/9: Saves an optional phone number to the user's Clerk profile.
+ * Saves an optional phone number to the user's Clerk profile.
  * Called from /activate/[orderId] — never required, always skippable.
  *
  * Body: { phone: string }