@carrierllc/mcp 0.11.17 → 0.13.0

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/order-route-guard.ts

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

package/templates/storefront/src/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 };
+}

package/templates/storefront/src/middleware.ts

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

package/templates/storefront/src/vendor/carrier/client.ts

@@ -12,7 +12,7 @@
  * to a charge must read `source`, not just the array. `fetchTemplates()` keeps
  * the plain-array shape for the pages that only render.
  */
-import type { EsimOrder, SkuTemplate } from "./types";
+import type { EsimOrder, EsimUsage, SkuTemplate, TopUpOption } from "./types";
 
 const MOCK_TEMPLATES: SkuTemplate[] = [
   {
@@ -190,3 +190,88 @@ export async function fetchOrder(orderId: string): Promise<OrderLookup> {
     return { ok: false, reason: "network-error" };
   }
 }
+
+/**
+ * Call one order-scoped fulfilment route and classify the failure.
+ *
+ * Shared by usage, top-up options and cancel so that every one of them reports
+ * the same four reasons in the same words. A page that says "we can't reach
+ * fulfilment" for one action and nothing at all for another teaches the
+ * customer that the second action silently does nothing.
+ */
+async function orderScopedCall<T>(
+  orderId: string,
+  path: string,
+  init?: RequestInit,
+): Promise<{ ok: true; data: T } | { ok: false; reason: OrderLookupError }> {
+  const base = apiBase();
+  if (!base) return { ok: false, reason: "unconfigured" };
+  if (!/^[A-Za-z0-9_-]{1,256}$/.test(orderId)) return { ok: false, reason: "not-found" };
+
+  const headers: Record<string, string> = { Accept: "application/json", ...(init?.headers as Record<string, string>) };
+  const key = apiKey();
+  if (key) headers.Authorization = `Bearer ${key}`;
+
+  try {
+    const res = await fetch(`${base}/api/orders/${encodeURIComponent(orderId)}${path}`, {
+      ...init,
+      headers,
+      cache: "no-store",
+    });
+    if (res.status === 404) return { ok: false, reason: "not-found" };
+    if (!res.ok) return { ok: false, reason: "upstream-error" };
+    return { ok: true, data: (await res.json()) as T };
+  } catch {
+    return { ok: false, reason: "network-error" };
+  }
+}
+
+/**
+ * How much of the plan is gone.
+ *
+ * Contract: GET {origin}/api/orders/{orderId}/usage -> EsimUsage.
+ * Until an origin serves it the dashboard says the meter is unavailable. It
+ * never shows a zero, because "no data used" and "we could not ask" look
+ * identical on a meter and mean opposite things to someone about to travel.
+ */
+export async function fetchUsage(
+  orderId: string,
+): Promise<{ ok: true; usage: EsimUsage } | { ok: false; reason: OrderLookupError }> {
+  const res = await orderScopedCall<EsimUsage>(orderId, "/usage");
+  if (!res.ok) return res;
+  if (typeof res.data?.usedBytes !== "number") return { ok: false, reason: "upstream-error" };
+  return { ok: true, usage: res.data };
+}
+
+/**
+ * What this eSIM can be topped up with.
+ *
+ * Contract: GET {origin}/api/orders/{orderId}/top-up-options -> TopUpOption[].
+ * An empty array is a valid answer and means this plan cannot be topped up —
+ * distinct from a failure, and rendered as such.
+ */
+export async function fetchTopUpOptions(
+  orderId: string,
+): Promise<{ ok: true; options: TopUpOption[] } | { ok: false; reason: OrderLookupError }> {
+  const res = await orderScopedCall<TopUpOption[]>(orderId, "/top-up-options");
+  if (!res.ok) return res;
+  if (!Array.isArray(res.data)) return { ok: false, reason: "upstream-error" };
+  return { ok: true, options: res.data };
+}
+
+/**
+ * Stop billing this eSIM.
+ *
+ * Contract: POST {origin}/api/orders/{orderId}/cancel -> { cancelledAt: string }.
+ * The operator decides what cancellation means for a plan mid-cycle; the
+ * storefront only reports back what it was told.
+ */
+export async function cancelOrder(
+  orderId: string,
+): Promise<{ ok: true; cancelledAt?: string } | { ok: false; reason: OrderLookupError }> {
+  const res = await orderScopedCall<{ cancelledAt?: string }>(orderId, "/cancel", {
+    method: "POST",
+  });
+  if (!res.ok) return res;
+  return { ok: true, cancelledAt: res.data?.cancelledAt };
+}

package/templates/storefront/src/vendor/carrier/types.ts

@@ -55,4 +55,38 @@ export interface EsimOrder {
   expiresAt?: string;
   /** Operator-supplied, customer-safe explanation when status is "failed". */
   failureMessage?: string;
+  /**
+   * The plan is no longer billable. Set once a cancellation has been accepted,
+   * so the dashboard can stop offering to cancel it twice.
+   */
+  cancelledAt?: string;
+}
+
+/**
+ * What one eSIM has actually carried, as a customer meter shows it.
+ *
+ * `usedBytes` is the only field that must be present. An operator that cannot
+ * state an allowance (an unmetered plan, or a bundle whose ceiling lives
+ * elsewhere) omits `totalBytes`, and the meter renders as a figure rather than
+ * a bar. Inventing a denominator to keep a bar drawable would turn "we do not
+ * know" into a number the customer would plan a trip around.
+ */
+export interface EsimUsage {
+  iccid?: string;
+  usedBytes: number;
+  totalBytes?: number;
+  /** When the plan stops working, whatever is left on it. */
+  expiresAt?: string;
+  /** Operator's own timestamp for this reading. */
+  measuredAt?: string;
+}
+
+/** One way to put more data on an eSIM that already exists. */
+export interface TopUpOption {
+  id: TemplateId;
+  name: string;
+  dataGb: number;
+  validityDays: number;
+  price_cents: number;
+  currency: string;
 }

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

@@ -0,0 +1,254 @@
+/**
+ * "Your eSIM is ready" — the message a customer actually installs from.
+ *
+ * Written as a plain HTML string rather than React Email components, for the
+ * reason given in resend.ts: this file ships into somebody else's repository,
+ * and an operator re-wording their own delivery email should not first have to
+ * learn a component library. Inline styles and a single-column table are the
+ * only layout most mail clients render the same way twice.
+ *
+ * The layering is deliberate, worst case first:
+ *
+ *   1. A QR code, attached and referenced as `cid:` — never a `data:` URI,
+ *      which Gmail strips.
+ *   2. A direct-install link, which needs no typing at all on iOS 17.4+.
+ *   3. The SM-DP+ address and the activation code as two separate values,
+ *      because those are two separate fields on the phone. One opaque
+ *      `LPA:1$…$…` blob is not something a person can act on.
+ *   4. The steps, in words, for iPhone and for Android.
+ *
+ * A QR code alone fails the commonest case there is: the customer is reading
+ * this on the phone the eSIM is for, and cannot photograph its own screen.
+ */
+import {
+  ANDROID_INSTALL_STEPS,
+  IPHONE_INSTALL_STEPS,
+  directInstallUrl,
+  manualActivationCode,
+} from "@/lib/esim-install";
+import type { EmailAttachment, EmailMessage } from "./resend";
+
+/** The QR image, already fetched and base64-encoded by the caller. */
+export interface QrImage {
+  base64: string;
+  contentType: string;
+}
+
+export interface QrDeliveryBrand {
+  name: string;
+  supportEmail?: string;
+  supportUrl?: string;
+  appUrl?: string;
+  colors?: { accent?: string; text?: string };
+}
+
+export interface QrDeliveryOrder {
+  orderId: string;
+  planName?: string;
+  iccid?: string;
+  activationCode?: string;
+  smdpAddress?: string;
+  matchingId?: string;
+}
+
+export interface QrDeliveryInput {
+  to: string;
+  order: QrDeliveryOrder;
+  brand: QrDeliveryBrand;
+  /** Absent when the operator's fulfilment produced no renderable QR. */
+  qr?: QrImage | null;
+}
+
+/**
+ * The content id the HTML points at. Any stable token works; this one is
+ * spelled out so the test can assert the HTML and the attachment agree.
+ */
+export const QR_CONTENT_ID = "esim-qr";
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+function steps(title: string, items: readonly string[]): string {
+  return `
+    <p style="margin:0 0 8px;font-size:12px;font-weight:600;letter-spacing:0.08em;text-transform:uppercase;color:#6b7280;">${escapeHtml(
+      title,
+    )}</p>
+    <ol style="margin:0 0 20px;padding-left:20px;font-size:14px;line-height:1.6;color:#374151;">
+      ${items.map((s) => `<li>${escapeHtml(s)}</li>`).join("")}
+    </ol>`;
+}
+
+/** One labelled credential, in a font a person can read a hyphen in. */
+function credential(label: string, value: string): string {
+  return `
+    <tr>
+      <td style="padding:0 0 14px;">
+        <p style="margin:0 0 2px;font-size:12px;color:#6b7280;">${escapeHtml(label)}</p>
+        <p style="margin:0;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:14px;word-break:break-all;color:#111827;">${escapeHtml(
+          value,
+        )}</p>
+      </td>
+    </tr>`;
+}
+
+/**
+ * Build the message. Pure: every input is an argument, so the shape of what
+ * goes out can be asserted without a network or an API key.
+ */
+export function buildQrDeliveryEmail(input: QrDeliveryInput): EmailMessage {
+  const { to, order, brand, qr } = input;
+  const accent = brand.colors?.accent ?? "#1a1a1a";
+  const lpa = manualActivationCode(order);
+  const attachments: EmailAttachment[] = [];
+
+  let qrBlock = "";
+  if (qr) {
+    attachments.push({
+      filename: "esim-qr.png",
+      content: qr.base64,
+      content_type: qr.contentType,
+      content_id: QR_CONTENT_ID,
+    });
+    qrBlock = `
+      <tr>
+        <td align="center" style="padding:8px 32px 24px;">
+          <img src="cid:${QR_CONTENT_ID}" width="200" height="200" alt="eSIM activation QR code" style="display:block;border:0;background:#ffffff;padding:8px;border-radius:12px;" />
+          <p style="margin:12px 0 0;font-size:13px;color:#6b7280;">Scan this from another device&rsquo;s camera.</p>
+        </td>
+      </tr>`;
+  }
+
+  const installButton = lpa
+    ? `
+      <tr>
+        <td align="center" style="padding:0 32px 8px;">
+          <a href="${escapeHtml(directInstallUrl(lpa))}" style="display:inline-block;background:${escapeHtml(
+            accent,
+          )};color:#ffffff;font-size:16px;font-weight:600;padding:14px 32px;border-radius:999px;text-decoration:none;">Install on this iPhone</a>
+          <p style="margin:10px 0 0;font-size:12px;color:#6b7280;">One tap, no typing. iPhone on iOS&nbsp;17.4 or later. On Android, use the steps below.</p>
+        </td>
+      </tr>`
+    : "";
+
+  const credentials = [
+    order.smdpAddress ? credential("SM-DP+ address", order.smdpAddress) : "",
+    order.matchingId ? credential("Activation code", order.matchingId) : "",
+    order.iccid ? credential("ICCID", order.iccid) : "",
+  ].join("");
+
+  const manualBlock = credentials
+    ? `
+      <tr>
+        <td style="padding:24px 32px 0;">
+          <div style="border:1px solid #e5e7eb;border-radius:16px;padding:20px;">
+            <p style="margin:0 0 14px;font-size:14px;font-weight:600;color:#111827;">Install manually</p>
+            <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0">${credentials}</table>
+            <div style="border-top:1px solid #e5e7eb;padding-top:18px;margin-top:4px;">
+              ${steps("On iPhone", IPHONE_INSTALL_STEPS)}
+              ${steps("On Android", ANDROID_INSTALL_STEPS)}
+            </div>
+          </div>
+        </td>
+      </tr>`
+    : "";
+
+  const activateUrl = brand.appUrl
+    ? `${brand.appUrl.replace(/\/+$/, "")}/activate/${encodeURIComponent(order.orderId)}`
+    : null;
+
+  const supportLine = brand.supportEmail
+    ? `Questions? <a href="mailto:${escapeHtml(brand.supportEmail)}" style="color:${escapeHtml(
+        accent,
+      )};">${escapeHtml(brand.supportEmail)}</a>`
+    : brand.supportUrl
+      ? `Questions? <a href="${escapeHtml(brand.supportUrl)}" style="color:${escapeHtml(accent)};">Contact support</a>`
+      : "";
+
+  const html = `<!DOCTYPE html>
+<html><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width" /><title>${escapeHtml(
+    brand.name,
+  )}</title></head>
+<body style="margin:0;padding:0;background:#f6f6f4;font-family:system-ui,-apple-system,'Segoe UI',sans-serif;">
+  <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="background:#f6f6f4;">
+    <tr><td align="center" style="padding:24px 12px;">
+      <table role="presentation" width="100%" cellpadding="0" cellspacing="0" border="0" style="max-width:560px;background:#ffffff;border-radius:20px;overflow:hidden;">
+        <tr>
+          <td style="background:${escapeHtml(accent)};padding:20px 32px;">
+            <p style="margin:0;color:#ffffff;font-size:20px;font-weight:700;letter-spacing:-0.4px;">${escapeHtml(
+              brand.name,
+            )}</p>
+          </td>
+        </tr>
+        <tr>
+          <td style="padding:28px 32px 4px;">
+            <p style="margin:0 0 8px;font-size:24px;font-weight:700;color:#111827;">Your eSIM is ready.</p>
+            <p style="margin:0;font-size:15px;line-height:1.55;color:#4b5563;">Install it now and it stays dormant until you arrive. ${
+              order.planName ? `Your plan: <strong>${escapeHtml(order.planName)}</strong>.` : ""
+            }</p>
+          </td>
+        </tr>
+        ${installButton}
+        ${qrBlock}
+        ${manualBlock}
+        <tr>
+          <td style="padding:24px 32px 28px;">
+            ${
+              activateUrl
+                ? `<p style="margin:0 0 10px;font-size:13px;color:#6b7280;">All of this is also on your <a href="${escapeHtml(
+                    activateUrl,
+                  )}" style="color:${escapeHtml(accent)};">activation page</a>.</p>`
+                : ""
+            }
+            <p style="margin:0 0 6px;font-size:13px;color:#6b7280;">${supportLine}</p>
+            <p style="margin:0;font-size:12px;color:#9ca3af;">Order ${escapeHtml(
+              order.orderId,
+            )} &middot; You are receiving this because you bought a plan from ${escapeHtml(
+              brand.name,
+            )}.</p>
+          </td>
+        </tr>
+      </table>
+    </td></tr>
+  </table>
+</body></html>`;
+
+  // null drops a line that does not apply. "" is a blank line on purpose:
+  // filtering every empty string turns the five install routes into one paragraph.
+  const text = [
+    "Your eSIM is ready.",
+    order.planName ? `Plan: ${order.planName}` : null,
+    "",
+    lpa ? `Install on iPhone (iOS 17.4+), one tap: ${directInstallUrl(lpa)}` : null,
+    "",
+    "Install manually:",
+    order.smdpAddress ? `  SM-DP+ address: ${order.smdpAddress}` : null,
+    order.matchingId ? `  Activation code: ${order.matchingId}` : null,
+    order.iccid ? `  ICCID: ${order.iccid}` : null,
+    "",
+    "On iPhone:",
+    ...IPHONE_INSTALL_STEPS.map((s, i) => `  ${i + 1}. ${s}`),
+    "",
+    "On Android:",
+    ...ANDROID_INSTALL_STEPS.map((s, i) => `  ${i + 1}. ${s}`),
+    "",
+    activateUrl ? `Activation page: ${activateUrl}` : null,
+    brand.supportEmail ? `Questions? ${brand.supportEmail}` : null,
+    `Order ${order.orderId}`,
+  ]
+    .filter((line) => line !== null)
+    .join("\n");
+
+  return {
+    to,
+    subject: `Your ${brand.name} eSIM is ready`,
+    html,
+    text,
+    attachments,
+  };
+}