@carrierllc/mcp 0.12.0 → 0.13.3

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

package/templates/storefront/src/vendor/email/resend.ts

@@ -0,0 +1,140 @@
+/**
+ * Transactional email over the Resend HTTP API.
+ *
+ * Deliberately no SDK. This template is copied into other people's
+ * repositories, so every dependency added here is one the operator inherits,
+ * has to audit, and has to keep patched. Sending one message is a single POST
+ * with a JSON body; `resend` and `@react-email/components` would buy us
+ * nothing that `fetch` does not already do, and `@react-email/components`
+ * would additionally drag a server-side React render into a Cloudflare Worker
+ * request path. The same reasoning put Stripe.js on a CDN rather than in
+ * package.json.
+ *
+ * The cost of that choice is honest: no typed client, and the field names
+ * below are the raw API's snake_case (`content_id`, not the SDK's
+ * `contentId`). They are pinned by tests.
+ */
+import brand from "@/brand.config";
+
+const RESEND_API = "https://api.resend.com";
+
+/**
+ * Resend rejects any request without a User-Agent with a 403 that looks
+ * exactly like a bad key. Workers do not set one, so we always do.
+ */
+const USER_AGENT = "carrier-storefront/1.0";
+
+/** One file travelling with the message. Inline when `content_id` is set. */
+export interface EmailAttachment {
+  filename: string;
+  /** Base64, no data: prefix. */
+  content: string;
+  content_type?: string;
+  /**
+   * Makes this attachment addressable from the HTML as `cid:<content_id>`.
+   *
+   * This is the whole reason the QR is an attachment rather than a `data:`
+   * URI in an `<img src>`. Gmail strips `data:` image sources, so a `data:`
+   * QR renders as a broken image for a large share of buyers — and a broken
+   * QR in a "your eSIM is ready" email is a support ticket, every time.
+   */
+  content_id?: string;
+}
+
+export interface EmailMessage {
+  to: string;
+  subject: string;
+  html: string;
+  text?: string;
+  attachments?: EmailAttachment[];
+}
+
+/**
+ * Why mail cannot be sent, when it cannot.
+ *
+ * "unconfigured" is a normal state, not a fault: a storefront with no Resend
+ * key still sells eSIMs, and every caller must treat this as a thing to
+ * mention rather than a thing to fail on.
+ */
+export type EmailUnavailable = "unconfigured" | "no-from-address";
+
+export type EmailSendResult =
+  | { ok: true; id?: string }
+  | { ok: false; reason: EmailUnavailable | "rejected" | "network-error"; detail?: string };
+
+/** Server-side only. Never reached from a client bundle, so never inlined. */
+function apiKey(): string {
+  return process.env.RESEND_API_KEY?.trim() ?? "";
+}
+
+export function emailConfigured(): boolean {
+  return apiKey().length > 0;
+}
+
+/**
+ * The address this storefront sends from, composed from the operator's own
+ * mailbox and their own domain.
+ *
+ * It is composed rather than stored whole on purpose. A literal from-address
+ * in a white-label template drifts onto a domain the operator does not own the
+ * first time somebody copies the file, and mail from a domain you cannot add
+ * SPF and DKIM records to does not arrive. There is no default: if the brand
+ * has no mailbox or no domain, this returns null and the caller says email is
+ * not configured rather than sending from somebody else's domain.
+ */
+export function fromAddress(
+  config: { emailFromName?: string; emailFromMailbox?: string; domain?: string } = brand,
+): string | null {
+  const mailbox = config.emailFromMailbox?.trim();
+  const domain = config.domain?.trim().replace(/^https?:\/\//, "").replace(/\/+$/, "");
+  if (!mailbox || !domain) return null;
+
+  const address = `${mailbox}@${domain}`;
+  const name = config.emailFromName?.trim();
+  return name ? `${name} <${address}>` : address;
+}
+
+/**
+ * Send one message. Never throws: a storefront that cannot send an email must
+ * still be able to finish taking an order.
+ */
+export async function sendEmail(message: EmailMessage): Promise<EmailSendResult> {
+  const key = apiKey();
+  if (!key) return { ok: false, reason: "unconfigured" };
+
+  const from = fromAddress();
+  if (!from) return { ok: false, reason: "no-from-address" };
+
+  try {
+    const res = await fetch(`${RESEND_API}/emails`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${key}`,
+        "Content-Type": "application/json",
+        "User-Agent": USER_AGENT,
+      },
+      body: JSON.stringify({
+        from,
+        to: [message.to],
+        subject: message.subject,
+        html: message.html,
+        ...(message.text ? { text: message.text } : {}),
+        ...(message.attachments?.length ? { attachments: message.attachments } : {}),
+      }),
+    });
+
+    if (!res.ok) {
+      const detail = (await res.text().catch(() => "")).slice(0, 300);
+      return { ok: false, reason: "rejected", detail: `HTTP ${res.status} ${detail}`.trim() };
+    }
+
+    const body = (await res.json().catch(() => ({}))) as { id?: string };
+    return { ok: true, id: body.id };
+  } catch (e: unknown) {
+    return {
+      ok: false,
+      reason: "network-error",
+      detail: e instanceof Error ? e.message : String(e),
+    };
+  }
+}