@carrierllc/mcp 0.11.17 → 0.13.0

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carrierllc/mcp",
-  "version": "0.11.17",
+  "version": "0.13.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,18 +2,29 @@
 /**
  * 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.
  */
 import { useCallback, useEffect, useRef, useState, FormEvent } from "react";
+import {
+  ANDROID_INSTALL_STEPS,
+  IPHONE_INSTALL_STEPS,
+  directInstallUrl,
+  manualActivationCode,
+} from "@/lib/esim-install";
 import type { EsimOrder } from "@/vendor/carrier/types";
 
 interface Props {
@@ -23,12 +34,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;
 
+/**
+ * What happened to the delivery email, as the page is allowed to describe it.
+ *
+ * "unconfigured" is on this list because a storefront with no Resend key is a
+ * working storefront, and the page must say "we cannot email this" rather than
+ * letting the customer leave believing a copy is on its way.
+ */
+type EmailState =
+  | { phase: "idle" }
+  | { phase: "sending" }
+  | { phase: "sent" }
+  | { phase: "unavailable"; reason: string };
+
 export function ActivateClient({ orderId }: Props) {
   const [phone, setPhone] = useState("");
   const [submitted, setSubmitted] = useState(false);
@@ -36,7 +67,14 @@ export function ActivateClient({ orderId }: Props) {
   const [saveError, setSaveError] = useState<string | null>(null);
   const [state, setState] = useState<LoadState>({ phase: "loading" });
   const [copied, setCopied] = useState(false);
+  const [email, setEmail] = useState<EmailState>({ phase: "idle" });
   const pollsRef = useRef(0);
+  const emailAskedRef = useRef(false);
+  // 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 +84,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 +107,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 +122,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 +139,48 @@ export function ActivateClient({ orderId }: Props) {
       cancelled = true;
       if (timer) clearTimeout(timer);
     };
-  }, [loadOrder]);
+  }, [loadOrder, pollCycle]);
+
+  /**
+   * Ask the server to email this eSIM, once, the moment it is ready.
+   *
+   * The page has always promised "we'll email you the QR code" and, until
+   * there was a sender, nothing was ever sent. The request is fired from here
+   * rather than from fulfilment because this is the first place that knows the
+   * order reached `ready`; the route itself carries the ownership check and
+   * the send-once marker, so a reload does not produce a second copy.
+   */
+  useEffect(() => {
+    if (state.phase !== "ready" || state.order.status !== "ready") return;
+    if (emailAskedRef.current) return;
+    emailAskedRef.current = true;
+
+    let cancelled = false;
+    setEmail({ phase: "sending" });
+    void (async () => {
+      try {
+        const res = await fetch(`/api/orders/${encodeURIComponent(orderId)}/email`, {
+          method: "POST",
+        });
+        const payload = (await res.json().catch(() => ({}))) as {
+          sent?: boolean;
+          reason?: string;
+        };
+        if (cancelled) return;
+        if (res.ok && payload.sent) {
+          setEmail({ phase: "sent" });
+          return;
+        }
+        setEmail({ phase: "unavailable", reason: payload.reason ?? "unavailable" });
+      } catch {
+        if (!cancelled) setEmail({ phase: "unavailable", reason: "network" });
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [state, orderId]);
 
   async function handlePhoneSubmit(e: FormEvent<HTMLFormElement>) {
     e.preventDefault();
@@ -120,11 +216,10 @@ 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 ??
-    (order?.smdpAddress && order?.matchingId ? `LPA:1$${order.smdpAddress}$${order.matchingId}` : null);
+  const manualCode = order ? manualActivationCode(order) : null;
 
   return (
     <div className="mx-auto max-w-lg px-4 py-16">
@@ -150,27 +245,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 +314,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 +370,32 @@ export function ActivateClient({ orderId }: Props) {
         )}
       </div>
 
+      {/* What happened to the email, in one line. The page promises a copy by
+          email in two other places; if none can be sent, it has to say so here
+          rather than let the customer navigate away expecting one. */}
+      {ready && email.phase !== "idle" && (
+        <p className="mb-4 text-center text-xs text-sand-500">
+          {email.phase === "sending" && "Emailing you a copy…"}
+          {email.phase === "sent" && "We've emailed a copy to the address that paid."}
+          {email.phase === "unavailable" &&
+            (email.reason === "unconfigured" || email.reason === "no-from-address"
+              ? "Email delivery isn't set up on this store, so keep this page — everything you need to install is on it."
+              : "We couldn't email you a copy. Everything you need to install is on this page.")}
+        </p>
+      )}
+
+      {/* 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 +438,32 @@ 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">
+                {IPHONE_INSTALL_STEPS.map((step) => (
+                  <li key={step}>{step}</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">
+                {ANDROID_INSTALL_STEPS.map((step) => (
+                  <li key={step}>{step}</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]/email/route.ts

@@ -0,0 +1,73 @@
+/**
+ * POST /api/orders/[orderId]/email
+ *
+ * Send the "your eSIM is ready" email for one order, to the address that paid
+ * for it. Called by the activation page the moment fulfilment reports `ready`,
+ * which is the first instant the email has anything true to say.
+ *
+ * Three things this route refuses to do:
+ *
+ *   - send for an order that is not ready. An email whose QR code is a blank
+ *     square is worse than no email;
+ *   - send twice. The marker lives in Stripe session metadata, because that is
+ *     the only durable store this storefront has;
+ *   - fail the order because email is not configured. A storefront with no
+ *     Resend key sells eSIMs perfectly well; it answers 200 with
+ *     `sent: false` and a reason, and the page says so in a sentence.
+ *
+ * It is guarded by the same auth + ownership check as every other
+ * order-scoped route, so a session id alone cannot make this storefront send
+ * mail to the address on someone else's order.
+ */
+import { NextResponse } from "next/server";
+import { markQrEmailSent, orderPurchaserEmail, qrEmailSentAt } from "@/lib/checkout-order-claim";
+import { guardOrderRoute, fulfilmentFailureResponse } from "@/lib/order-route-guard";
+import { deliverQrEmail } from "@/lib/qr-delivery-email";
+import { fetchOrder } 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 { orderId } = guard;
+
+  const already = await qrEmailSentAt(orderId);
+  if (already) {
+    return NextResponse.json({ sent: true, deduplicated: true, sentAt: already });
+  }
+
+  const lookup = await fetchOrder(orderId);
+  if (!lookup.ok) {
+    return fulfilmentFailureResponse(lookup.reason, "send your eSIM email", orderId);
+  }
+  if (lookup.order.status !== "ready") {
+    return NextResponse.json(
+      { sent: false, reason: "not_ready", status: lookup.order.status },
+      { status: 409 },
+    );
+  }
+
+  const to = await orderPurchaserEmail(orderId);
+  if (!to) {
+    // No address on the payment means nowhere to send. That is a fact about
+    // the order, not a failure of this storefront, and the page has the same
+    // QR on screen regardless.
+    return NextResponse.json({ sent: false, reason: "no_recipient" });
+  }
+
+  const result = await deliverQrEmail(lookup.order, to);
+  if (!result.sent) {
+    if (result.detail) {
+      console.error(`[email] QR delivery for ${orderId} failed (${result.reason}): ${result.detail}`);
+    }
+    return NextResponse.json({ sent: false, reason: result.reason });
+  }
+
+  await markQrEmailSent(orderId, new Date().toISOString());
+  return NextResponse.json({ sent: true, withQrImage: result.withQrImage });
+}