@carrierllc/mcp 0.12.0 → 0.13.0

package/dist/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carrierllc/mcp",
-  "version": "0.12.0",
+  "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/templates/storefront/src/app/activate/[orderId]/ActivateClient.tsx

@@ -19,6 +19,12 @@
  *   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 {
@@ -42,17 +48,17 @@ 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.
+ * What happened to the delivery email, as the page is allowed to describe it.
  *
- * Nothing equivalent exists on Android: install there is Settings → Network →
- * add eSIM → enter manually, which is what the written steps below are for.
+ * "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.
  */
-function directInstallUrl(activationCode: string): string {
-  return `https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=${encodeURIComponent(
-    activationCode,
-  )}`;
-}
+type EmailState =
+  | { phase: "idle" }
+  | { phase: "sending" }
+  | { phase: "sent" }
+  | { phase: "unavailable"; reason: string };
 
 export function ActivateClient({ orderId }: Props) {
   const [phone, setPhone] = useState("");
@@ -61,7 +67,9 @@ 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
@@ -133,6 +141,47 @@ export function ActivateClient({ orderId }: Props) {
     };
   }, [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();
     setSaving(true);
@@ -170,9 +219,7 @@ export function ActivateClient({ orderId }: Props) {
   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">
@@ -323,6 +370,20 @@ 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. */}
@@ -387,11 +448,9 @@ export function ActivateClient({ orderId }: Props) {
                 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>
+                {IPHONE_INSTALL_STEPS.map((step) => (
+                  <li key={step}>{step}</li>
+                ))}
               </ol>
             </div>
             <div>
@@ -399,11 +458,9 @@ export function ActivateClient({ orderId }: Props) {
                 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>
+                {ANDROID_INSTALL_STEPS.map((step) => (
+                  <li key={step}>{step}</li>
+                ))}
               </ol>
             </div>
           </div>

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 });
+}

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

@@ -30,15 +30,19 @@ async function fetchStripeSession(sessionId: string): Promise<StripeSession | nu
   return (await resp.json()) as StripeSession;
 }
 
-async function setStripeClaimedBy(sessionId: string, userId: string): Promise<boolean> {
+async function setSessionMetadata(
+  sessionId: string,
+  fields: Record<string, string>,
+): Promise<boolean> {
   const stripeKey = process.env.STRIPE_SECRET_KEY;
   if (!stripeKey) return false;
   const safeSessionId = safeStripeSessionId(sessionId);
   if (!safeSessionId) return false;
 
-  const formBody = new URLSearchParams({
-    "metadata[claimedByUserId]": userId,
-  });
+  const formBody = new URLSearchParams();
+  for (const [key, value] of Object.entries(fields)) {
+    formBody.set(`metadata[${key}]`, value);
+  }
 
   const resp = await fetch(`https://api.stripe.com/v1/checkout/sessions/${safeSessionId}`, {
     method: "POST",
@@ -52,6 +56,43 @@ async function setStripeClaimedBy(sessionId: string, userId: string): Promise<bo
   return resp.ok;
 }
 
+function setStripeClaimedBy(sessionId: string, userId: string): Promise<boolean> {
+  return setSessionMetadata(sessionId, { claimedByUserId: userId });
+}
+
+/**
+ * The address that paid, which is the address the eSIM email goes to.
+ *
+ * Deliberately taken from the Stripe session rather than from Clerk. The
+ * person who paid is the person expecting the QR code; the signed-in account
+ * may have several addresses on it, and picking one of those would be a guess.
+ */
+export async function orderPurchaserEmail(orderId: string): Promise<string | null> {
+  if (!orderId.startsWith("cs_")) return null;
+  const session = await fetchStripeSession(orderId);
+  return session ? sessionPurchaserEmail(session) : null;
+}
+
+/**
+ * When the delivery email for this order was sent, if it was.
+ *
+ * The storefront has no database — Stripe session metadata is the only place
+ * it can record a fact about an order, and it is already used that way for
+ * `claimedByUserId`. Without this marker every reload of the activation page
+ * would send the customer another copy of the same email.
+ */
+export async function qrEmailSentAt(orderId: string): Promise<string | null> {
+  if (!process.env.STRIPE_SECRET_KEY || !orderId.startsWith("cs_")) return null;
+  const session = await fetchStripeSession(orderId);
+  return session?.metadata?.qrEmailSentAt ?? null;
+}
+
+/** Best-effort. A send that happened and was not recorded is a duplicate, not a loss. */
+export async function markQrEmailSent(orderId: string, at: string): Promise<void> {
+  if (!process.env.STRIPE_SECRET_KEY || !orderId.startsWith("cs_")) return;
+  await setSessionMetadata(orderId, { qrEmailSentAt: at }).catch(() => false);
+}
+
 function claimedOrderIds(metadata: Record<string, unknown> | undefined): string[] {
   const value = metadata?.claimedOrderIds;
   return Array.isArray(value) ? value.filter((id): id is string => typeof id === "string") : [];

package/templates/storefront/src/lib/esim-install.ts

@@ -0,0 +1,74 @@
+/**
+ * How a customer gets an eSIM onto a phone, in every form we can offer.
+ *
+ * This lives apart from the pages because the activate page and the delivery
+ * email have to say exactly the same thing. They did not, in the product this
+ * template grew out of: the page learned about one-tap install and the email
+ * kept telling people to scan a QR code on the device they were reading it on.
+ * Two copies of install instructions drift, and the copy that drifts is the one
+ * the customer is holding.
+ */
+
+/** Both halves of the credential, as a phone's manual-entry form asks for them. */
+export interface ManualInstallDetails {
+  /** e.g. consumer.rsp.example.com — the "SM-DP+ address" field. */
+  smdpAddress?: string;
+  /** e.g. K2-1A2B3C-4D5E6F — the "activation code" field. */
+  matchingId?: string;
+  /** The whole LPA string, which is what a QR code encodes. */
+  activationCode?: string;
+}
+
+/**
+ * The full LPA string, from whichever pieces the operator supplied.
+ *
+ * `LPA:1$<smdp>$<matchingId>` is the format every modern handset accepts, so
+ * either the operator hands it over whole or we can rebuild it.
+ */
+export function manualActivationCode(details: ManualInstallDetails): string | null {
+  if (details.activationCode) return details.activationCode;
+  if (details.smdpAddress && details.matchingId) {
+    return `LPA:1$${details.smdpAddress}$${details.matchingId}`;
+  }
+  return null;
+}
+
+/**
+ * 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.
+ * The link is harmless on a phone that cannot use it; it opens a page that
+ * explains the manual route.
+ */
+export function directInstallUrl(activationCode: string): string {
+  return `https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=${encodeURIComponent(
+    activationCode,
+  )}`;
+}
+
+/**
+ * The steps in words.
+ *
+ * A customer whose camera cannot reach a second screen, and whose phone is too
+ * old for the one-tap link, otherwise has two credentials and no idea where to
+ * type them. The SM-DP+ address and the activation code are named here exactly
+ * as the handset names them, because "paste your activation string" does not
+ * match any field on either operating system.
+ */
+export const IPHONE_INSTALL_STEPS: readonly string[] = [
+  "Open Settings, then Cellular (or Mobile Service).",
+  "Tap Add eSIM, then Use QR Code.",
+  "Tap Enter Details Manually.",
+  "Paste the SM-DP+ address and activation code from above.",
+  "Leave data roaming on — that is how the plan connects abroad.",
+];
+
+export const ANDROID_INSTALL_STEPS: readonly string[] = [
+  "Open Settings, then Network & internet.",
+  "Tap SIMs, then Add SIM or Download a SIM instead.",
+  "Choose Need help? then Enter it manually.",
+  "Paste the activation code from above.",
+  "Turn on roaming for this SIM once it appears.",
+];

package/templates/storefront/src/lib/qr-delivery-email.ts

@@ -0,0 +1,106 @@
+/**
+ * Turn one ready order into one delivered email.
+ *
+ * The interesting part is getting the QR out of whatever the operator's
+ * fulfilment handed us and into an attachment. `EsimOrder.qrCode` is
+ * documented as "a data: URI or an https URL" because both are things a
+ * fulfilment API plausibly returns, and neither can be dropped into an email
+ * as-is:
+ *
+ *   - a `data:` URI in `<img src>` is stripped by Gmail and shows as a broken
+ *     image, which is the single most expensive way for this email to fail;
+ *   - an `https` URL survives, but only while that host is up and only if the
+ *     reader's client loads remote images, which many do not by default.
+ *
+ * So both are normalised to bytes and attached with a `content_id`, and the
+ * HTML points at `cid:`. An attachment is part of the message; it cannot 404
+ * next month and it does not need remote images enabled.
+ */
+import brand from "@/brand.config";
+import type { EsimOrder } from "@/vendor/carrier/types";
+import { buildQrDeliveryEmail, type QrImage } from "@/vendor/email/qr-delivery";
+import { emailConfigured, fromAddress, sendEmail, type EmailSendResult } from "@/vendor/email/resend";
+
+/** A QR code is a few kB. Anything this size is not one, and is not attached. */
+const MAX_QR_BYTES = 2 * 1024 * 1024;
+
+// `[\s\S]` rather than the `s` flag: the template's tsconfig targets an older
+// ES level than dotAll, and a base64 payload can contain newlines.
+const DATA_URI = /^data:([^;,]+)?(;base64)?,([\s\S]*)$/;
+
+function toBase64(bytes: Uint8Array): string {
+  // Chunked so a large-ish buffer cannot blow the argument limit of
+  // String.fromCharCode. btoa exists in both Workers and Node 18+.
+  let binary = "";
+  const chunk = 0x8000;
+  for (let i = 0; i < bytes.length; i += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+  }
+  return btoa(binary);
+}
+
+/**
+ * Fetch or decode the QR into base64 bytes. Null whenever that cannot be done
+ * — the email is still worth sending, because the manual credentials and the
+ * written steps below the QR are what most people use anyway.
+ */
+export async function resolveQrImage(qrCode: string | undefined): Promise<QrImage | null> {
+  if (!qrCode) return null;
+
+  const data = DATA_URI.exec(qrCode);
+  if (data) {
+    const [, contentType, isBase64, payload] = data;
+    if (!isBase64 || !payload) return null;
+    return { base64: payload.replace(/\s+/g, ""), contentType: contentType || "image/png" };
+  }
+
+  if (!/^https:\/\//i.test(qrCode)) return null;
+
+  try {
+    const res = await fetch(qrCode, { cache: "no-store" });
+    if (!res.ok) return null;
+    const buffer = await res.arrayBuffer();
+    if (buffer.byteLength === 0 || buffer.byteLength > MAX_QR_BYTES) return null;
+    return {
+      base64: toBase64(new Uint8Array(buffer)),
+      contentType: res.headers.get("content-type")?.split(";")[0]?.trim() || "image/png",
+    };
+  } catch {
+    return null;
+  }
+}
+
+export type QrDeliveryResult =
+  | { sent: true; id?: string; withQrImage: boolean }
+  | { sent: false; reason: "unconfigured" | "no-from-address" | "rejected" | "network-error"; detail?: string };
+
+/**
+ * Send the delivery email for one ready order.
+ *
+ * Never throws and never reports success it did not get. A storefront with no
+ * Resend key returns `unconfigured`, which the caller shows as a plain
+ * sentence — the order is complete either way, and pretending an email went
+ * out is worse than saying none did.
+ */
+export async function deliverQrEmail(order: EsimOrder, to: string): Promise<QrDeliveryResult> {
+  if (!emailConfigured()) return { sent: false, reason: "unconfigured" };
+  if (!fromAddress()) return { sent: false, reason: "no-from-address" };
+
+  const qr = await resolveQrImage(order.qrCode);
+  const message = buildQrDeliveryEmail({
+    to,
+    order,
+    brand: {
+      name: brand.name,
+      supportEmail: brand.supportEmail,
+      supportUrl: brand.supportUrl,
+      appUrl: brand.appUrl,
+      colors: { accent: brand.colors.accent },
+    },
+    qr,
+  });
+
+  const result: EmailSendResult = await sendEmail(message);
+  if (!result.ok) return { sent: false, reason: result.reason, detail: result.detail };
+  return { sent: true, id: result.id, withQrImage: qr !== null };
+}