@carrierllc/mcp 0.10.7 → 0.11.4

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

@@ -0,0 +1,69 @@
+/**
+ * GET /api/orders/[orderId]
+ *
+ * The activate page's data source. Signed-in callers only, and only for an
+ * order they have already claimed — ownership is the same check the page
+ * itself makes, repeated here because a route handler is reachable directly.
+ *
+ * Upstream failures are reported, not smoothed over. A page that cannot read
+ * an order must say so; the one thing it must never do is draw a reassuring
+ * placeholder while the eSIM behind it does not exist.
+ */
+import { auth } from "@clerk/nextjs/server";
+import { NextResponse } from "next/server";
+import { userOwnsOrder } from "@/lib/checkout-order-claim";
+import { fetchOrder } from "@/vendor/carrier/client";
+
+export const dynamic = "force-dynamic";
+
+interface Context {
+  params: Promise<{ orderId: string }>;
+}
+
+export async function GET(_req: Request, ctx: Context): Promise<NextResponse> {
+  const { userId } = await auth();
+  if (!userId) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  const { orderId } = await ctx.params;
+  if (!orderId) {
+    return NextResponse.json({ error: "orderId is required" }, { status: 400 });
+  }
+
+  if (!(await userOwnsOrder(userId, orderId))) {
+    return NextResponse.json({ error: "Order not found" }, { status: 404 });
+  }
+
+  const lookup = await fetchOrder(orderId);
+  if (lookup.ok) {
+    return NextResponse.json({ order: lookup.order });
+  }
+
+  if (lookup.reason === "not-found") {
+    return NextResponse.json({ error: "Order not found", code: "not_found" }, { status: 404 });
+  }
+
+  if (lookup.reason === "unconfigured") {
+    console.error(
+      "[orders] NEXT_PUBLIC_CARRIER_API_URL is unset — the storefront has no fulfilment origin to ask, " +
+        "so no order can ever reach 'ready'",
+    );
+    return NextResponse.json(
+      {
+        error: "Activation is not available yet. Please contact support with your order number.",
+        code: "fulfilment_unconfigured",
+      },
+      { status: 503 },
+    );
+  }
+
+  console.error(`[orders] order lookup failed for ${orderId}: ${lookup.reason}`);
+  return NextResponse.json(
+    {
+      error: "We could not reach your eSIM details right now. Please try again in a moment.",
+      code: "fulfilment_unavailable",
+    },
+    { status: 502 },
+  );
+}

package/templates/storefront/src/app/checkout/[templateId]/CheckoutClient.tsx

@@ -12,11 +12,17 @@
  * After Stripe payment success, the user lands on /checkout/success where they
  * are prompted to create an account (email + password, no phone) or sign in.
  * Then they are redirected to /activate/[orderId] for optional WhatsApp/phone setup.
+ *
+ * Every string on this page is read by a customer. It names no environment
+ * variable and gives no configuration instructions — an operator's deployment
+ * problem is not something a shopper can act on, and printing it makes a store
+ * look broken rather than busy.
  */
 import { useEffect, useRef, useState } from "react";
 import { useAuth } from "@clerk/nextjs";
 import { useRouter } from "next/navigation";
 import { conversionEvents } from "@/lib/conversion-events";
+import { normalizeChannel } from "@/vendor/carrier/catalog-guard";
 import type { SkuTemplate } from "@/vendor/carrier/types";
 
 interface Props {
@@ -25,6 +31,21 @@ interface Props {
   session: { url: string } | null;
 }
 
+const GENERIC_CHECKOUT_ERROR = "Checkout is unavailable right now. Please try again in a moment.";
+
+/**
+ * Where this visit came from, read off the landing URL.
+ *
+ * `?channel=` is the explicit form; `utm_source` is what ad and email tools
+ * actually append, so both are honoured. The value is normalised here and
+ * again on the server — this copy only keeps the request tidy.
+ */
+function readChannel(): string {
+  if (typeof window === "undefined") return "storefront";
+  const params = new URLSearchParams(window.location.search);
+  return normalizeChannel(params.get("channel") ?? params.get("utm_source"));
+}
+
 export function CheckoutClient({ plan, session }: Props) {
   const { isSignedIn, isLoaded } = useAuth();
   const router = useRouter();
@@ -49,9 +70,7 @@ export function CheckoutClient({ plan, session }: Props) {
         router.refresh();
         return;
       }
-      setCheckoutError(
-        "Checkout is unavailable. Configure NEXT_PUBLIC_CARRIER_API_URL and Clerk keys, then try again.",
-      );
+      setCheckoutError(GENERIC_CHECKOUT_ERROR);
       return;
     }
 
@@ -63,12 +82,15 @@ export function CheckoutClient({ plan, session }: Props) {
     fetch("/api/checkout/guest", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ templateId: plan.id }),
+      body: JSON.stringify({ templateId: plan.id, channel: readChannel() }),
     })
       .then(async (res) => {
         if (!res.ok) {
-          const err = (await res.json()) as { error?: string };
-          throw new Error(err.error ?? "Failed to create checkout session");
+          // The route returns customer-safe copy for every refusal it knows
+          // about. Anything else (a proxy error page, say) gets the generic
+          // line rather than whatever text happened to come back.
+          const err = (await res.json().catch(() => ({}))) as { error?: string; code?: string };
+          throw new Error(err.code && err.error ? err.error : GENERIC_CHECKOUT_ERROR);
         }
         return res.json() as Promise<{ url: string }>;
       })
@@ -77,8 +99,7 @@ export function CheckoutClient({ plan, session }: Props) {
       })
       .catch((err: unknown) => {
         guestCheckoutPlanIdRef.current = null;
-        const msg = err instanceof Error ? err.message : "Checkout unavailable. Please try again.";
-        setCheckoutError(msg);
+        setCheckoutError(err instanceof Error ? err.message : GENERIC_CHECKOUT_ERROR);
         setLoading(false);
       });
   }, [isLoaded, isSignedIn, plan, session, router]);

package/templates/storefront/src/app/dashboard/page.tsx

@@ -1,29 +1,108 @@
 export const dynamic = "force-dynamic";
 
+/**
+ * /dashboard — the customer's order history.
+ *
+ * This page used to render "No active eSIMs yet." unconditionally, which told
+ * a paying customer their purchase had not happened. It now reads the orders
+ * they have actually claimed and asks fulfilment about each one. Three
+ * outcomes, all of them stated rather than implied: no orders, orders we could
+ * read, and orders we could not read.
+ */
 import { auth } from "@clerk/nextjs/server";
 import { redirect } from "next/navigation";
+import { listClaimedOrderIds } from "@/lib/checkout-order-claim";
+import { fetchOrder } from "@/vendor/carrier/client";
+import type { EsimOrder, OrderStatus } from "@/vendor/carrier/types";
 
 export const metadata = { title: "Dashboard" };
 
+const STATUS_LABEL: Record<OrderStatus, string> = {
+  pending: "Payment received",
+  provisioning: "Setting up",
+  ready: "Active",
+  failed: "Needs attention",
+};
+
+function EmptyState() {
+  return (
+    <div className="rounded-2xl border border-sand-200 bg-white p-12 text-center dark:border-sand-800 dark:bg-sand-900">
+      <p className="text-sand-500">No active eSIMs yet.</p>
+      <a
+        href="/shop"
+        className="mt-4 inline-block rounded-full px-6 py-2 text-sm font-semibold text-white transition-opacity hover:opacity-90"
+        style={{ background: "var(--brand-accent)" }}
+      >
+        Browse plans
+      </a>
+    </div>
+  );
+}
+
+function OrderRow({ orderId, order }: { orderId: string; order: EsimOrder | null }) {
+  return (
+    <li className="rounded-2xl border border-sand-200 bg-white p-6 dark:border-sand-800 dark:bg-sand-900">
+      <div className="flex flex-wrap items-baseline justify-between gap-2">
+        <p className="font-medium text-sand-900 dark:text-sand-50">
+          {order?.planName ?? order?.templateId ?? "eSIM order"}
+        </p>
+        <span className="text-xs text-sand-500">
+          {order ? STATUS_LABEL[order.status] : "Status unavailable"}
+        </span>
+      </div>
+      <p className="mt-1 font-mono text-xs break-all text-sand-400">{orderId}</p>
+      {order?.iccid && <p className="mt-1 text-xs text-sand-500">ICCID {order.iccid}</p>}
+      {!order && (
+        <p className="mt-2 text-xs text-sand-500">
+          We couldn&apos;t reach this order just now. Your purchase is safe — try again shortly.
+        </p>
+      )}
+      <a
+        href={`/activate/${encodeURIComponent(orderId)}`}
+        className="mt-4 inline-block text-sm font-semibold text-[var(--brand-accent)] hover:underline"
+      >
+        {order?.status === "ready" ? "View QR code" : "View order"} →
+      </a>
+    </li>
+  );
+}
+
 export default async function DashboardPage() {
   const { userId } = await auth();
   if (!userId) redirect("/sign-in?redirect_url=/dashboard");
 
+  const orderIds = await listClaimedOrderIds(userId);
+  const orders = await Promise.all(
+    orderIds.map(async (orderId) => {
+      const lookup = await fetchOrder(orderId);
+      return { orderId, order: lookup.ok ? lookup.order : null };
+    }),
+  );
+  const unreadable = orders.filter((entry) => entry.order === null).length;
+
   return (
     <div className="mx-auto max-w-4xl px-4 py-16">
       <h1 className="mb-8 text-3xl font-semibold tracking-tight text-sand-900 dark:text-sand-50">
         Your eSIMs
       </h1>
-      <div className="rounded-2xl border border-sand-200 bg-white p-12 text-center dark:border-sand-800 dark:bg-sand-900">
-        <p className="text-sand-500">No active eSIMs yet.</p>
-        <a
-          href="/shop"
-          className="mt-4 inline-block rounded-full px-6 py-2 text-sm font-semibold text-white transition-opacity hover:opacity-90"
-          style={{ background: "var(--brand-accent)" }}
-        >
-          Browse plans
-        </a>
-      </div>
+
+      {orders.length === 0 ? (
+        <EmptyState />
+      ) : (
+        <>
+          {unreadable > 0 && (
+            <p className="mb-6 rounded-xl border border-amber-500/30 bg-amber-500/10 px-4 py-3 text-sm text-sand-700 dark:text-sand-200">
+              We couldn&apos;t load {unreadable === orders.length ? "your orders" : "some of your orders"}{" "}
+              right now. Nothing is lost — refresh in a minute, or contact us with the order number.
+            </p>
+          )}
+          <ul className="space-y-4">
+            {orders.map((entry) => (
+              <OrderRow key={entry.orderId} orderId={entry.orderId} order={entry.order} />
+            ))}
+          </ul>
+        </>
+      )}
     </div>
   );
 }

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

@@ -139,3 +139,16 @@ export async function userOwnsOrder(userId: string, orderId: string): Promise<bo
     orderId,
   );
 }
+
+/**
+ * Every order this user has claimed, newest last.
+ *
+ * Clerk's private metadata is the storefront's only record of who bought what:
+ * there is no local database, and Stripe cannot be queried by user. The
+ * dashboard reads this and then asks fulfilment about each id.
+ */
+export async function listClaimedOrderIds(userId: string): Promise<string[]> {
+  const client = await clerkClient();
+  const user = await client.users.getUser(userId);
+  return claimedOrderIds(user.privateMetadata as Record<string, unknown> | undefined);
+}

package/templates/storefront/src/vendor/carrier/catalog-guard.ts

@@ -0,0 +1,110 @@
+/**
+ * Pure decision logic that sits between the plan catalog and Stripe.
+ *
+ * It lives apart from the route handler on purpose: the route imports
+ * `next/server`, which cannot be loaded in a plain node test, and this is the
+ * part that has to be provable. Nothing here touches the network or the env.
+ */
+import type { SkuTemplate } from "./types";
+import type { TemplateCatalog } from "./client";
+
+/** Codes the storefront maps to customer-facing copy. Never shown verbatim. */
+export type CheckoutRefusalCode = "plan_not_found" | "catalog_degraded" | "plan_not_sellable";
+
+export type CheckoutDecision =
+  | { ok: true; plan: SkuTemplate }
+  | { ok: false; status: number; code: CheckoutRefusalCode; error: string };
+
+/**
+ * A price is only chargeable when it is a whole, positive number of minor
+ * units and the currency is a plain ISO-4217 code. The guest route builds the
+ * Stripe line item inline from these two fields (price_data, no price id), so
+ * Stripe validates nothing on our behalf — this is the only check there is.
+ */
+function isSellable(plan: SkuTemplate): boolean {
+  return (
+    Number.isSafeInteger(plan.price_cents) &&
+    plan.price_cents > 0 &&
+    typeof plan.currency === "string" &&
+    /^[A-Za-z]{3}$/.test(plan.currency) &&
+    typeof plan.name === "string" &&
+    plan.name.trim().length > 0
+  );
+}
+
+/**
+ * Decide whether a plan may be charged for.
+ *
+ * The rule that matters: when Stripe is live, a catalog that fell back to the
+ * built-in sample plans must never reach a charge. Those plans have invented
+ * ids, names and prices; a payment against one takes real money for a product
+ * that does not exist and cannot be fulfilled. Rendering them is fine — that is
+ * what lets the template build with no credentials — but selling them is not.
+ */
+export function decideGuestCheckout(args: {
+  catalog: TemplateCatalog;
+  templateId: string;
+  stripeConfigured: boolean;
+}): CheckoutDecision {
+  const { catalog, templateId, stripeConfigured } = args;
+
+  if (stripeConfigured && catalog.source !== "live") {
+    return {
+      ok: false,
+      status: 503,
+      code: "catalog_degraded",
+      error: "Plans are temporarily unavailable. Please try again in a few minutes.",
+    };
+  }
+
+  const plan = catalog.templates.find((p) => p.id === templateId);
+  if (!plan) {
+    return {
+      ok: false,
+      status: 404,
+      code: "plan_not_found",
+      error: "That plan is no longer available.",
+    };
+  }
+
+  if (stripeConfigured && !isSellable(plan)) {
+    return {
+      ok: false,
+      status: 503,
+      code: "plan_not_sellable",
+      error: "That plan cannot be purchased right now. Please try again in a few minutes.",
+    };
+  }
+
+  return { ok: true, plan };
+}
+
+/**
+ * Channel attribution carried into Stripe session metadata.
+ *
+ * Stripe metadata values are free text and this one is caller-supplied — it
+ * arrives in the request body — so it is clamped to a short slug rather than
+ * passed through. An unrecognisable value degrades to the default instead of
+ * failing the purchase: attribution is never worth losing a sale over.
+ */
+export const DEFAULT_CHANNEL = "storefront";
+
+export function normalizeChannel(raw: unknown): string {
+  if (typeof raw !== "string") return DEFAULT_CHANNEL;
+  const slug = raw
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_.-]/g, "-")
+    .replace(/-{2,}/g, "-");
+  // Bound the length BEFORE stripping, and strip with a loop rather than
+  // /^-+|-+$/g. That pattern backtracks polynomially on a long run of dashes
+  // (CodeQL js/polynomial-redos), and `raw` comes straight off the request —
+  // "-" repeated a few hundred thousand times is a free CPU burn otherwise.
+  // The loop is linear and stays correct even if the collapse above changes.
+  const bounded = slug.slice(0, 64);
+  let start = 0;
+  let end = bounded.length;
+  while (start < end && bounded[start] === "-") start += 1;
+  while (end > start && bounded[end - 1] === "-") end -= 1;
+  return bounded.slice(start, end) || DEFAULT_CHANNEL;
+}

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

@@ -1,9 +1,18 @@
 /**
- * Carrier API client stub.
- * Set NEXT_PUBLIC_CARRIER_API_URL to point at a live Carrier API.
- * When absent, all methods return mock data so the storefront builds without credentials.
+ * Carrier API client.
+ *
+ * Set NEXT_PUBLIC_CARRIER_API_URL to point at a live Carrier API. When it is
+ * absent — or the call fails — the catalog falls back to sample plans so the
+ * storefront still builds and renders without credentials.
+ *
+ * That fallback is deliberately *labelled*. `fetchTemplateCatalog()` reports
+ * whether the plans are live or sample, because a sample plan is safe to draw
+ * and unsafe to sell: its id, name and price are invented, so a payment taken
+ * against one is money for a product that does not exist. Anything that leads
+ * to a charge must read `source`, not just the array. `fetchTemplates()` keeps
+ * the plain-array shape for the pages that only render.
  */
-import type { SkuTemplate } from "./types";
+import type { EsimOrder, SkuTemplate } from "./types";
 
 const MOCK_TEMPLATES: SkuTemplate[] = [
   {
@@ -63,26 +72,62 @@ const MOCK_TEMPLATES: SkuTemplate[] = [
   },
 ];
 
-const API_BASE = process.env.NEXT_PUBLIC_CARRIER_API_URL ?? "";
+/** Why the catalog is not live. Absent when `source` is "live". */
+export type CatalogDegradedReason = "unconfigured" | "upstream-error" | "network-error";
 
-export async function fetchTemplates(): Promise<SkuTemplate[]> {
-  if (!API_BASE) return MOCK_TEMPLATES;
+export interface TemplateCatalog {
+  templates: SkuTemplate[];
+  source: "live" | "sample";
+  reason?: CatalogDegradedReason;
+}
+
+function apiBase(): string {
+  return (process.env.NEXT_PUBLIC_CARRIER_API_URL ?? "").replace(/\/+$/, "");
+}
+
+/** Server-side only. Never reached in a client bundle, so never inlined. */
+function apiKey(): string {
+  return process.env.CARRIER_API_KEY ?? "";
+}
+
+function sampleCatalog(reason: CatalogDegradedReason): TemplateCatalog {
+  return { templates: MOCK_TEMPLATES, source: "sample", reason };
+}
+
+/**
+ * The plan catalog, with its provenance attached.
+ *
+ * Callers that can move money MUST branch on `source`. See catalog-guard.ts.
+ */
+export async function fetchTemplateCatalog(): Promise<TemplateCatalog> {
+  const base = apiBase();
+  if (!base) return sampleCatalog("unconfigured");
   try {
-    const res = await fetch(`${API_BASE}/api/templates`, { next: { revalidate: 3600 } });
-    if (!res.ok) return MOCK_TEMPLATES;
-    return (await res.json()) as SkuTemplate[];
+    const res = await fetch(`${base}/api/templates`, { next: { revalidate: 3600 } });
+    if (!res.ok) return sampleCatalog("upstream-error");
+    const templates = (await res.json()) as SkuTemplate[];
+    if (!Array.isArray(templates) || templates.length === 0) {
+      return sampleCatalog("upstream-error");
+    }
+    return { templates, source: "live" };
   } catch {
-    return MOCK_TEMPLATES;
+    return sampleCatalog("network-error");
   }
 }
 
+/** Render-only convenience. Do not use on any path that creates a charge. */
+export async function fetchTemplates(): Promise<SkuTemplate[]> {
+  return (await fetchTemplateCatalog()).templates;
+}
+
 export async function createCheckoutSession(
   templateId: string,
   userId: string,
 ): Promise<{ url: string } | null> {
-  if (!API_BASE) return null;
+  const base = apiBase();
+  if (!base) return null;
   try {
-    const res = await fetch(`${API_BASE}/api/checkout`, {
+    const res = await fetch(`${base}/api/checkout`, {
       method: "POST",
       headers: { "Content-Type": "application/json", Authorization: `Bearer ${userId}` },
       body: JSON.stringify({ templateId }),
@@ -93,3 +138,55 @@ export async function createCheckoutSession(
     return null;
   }
 }
+
+/**
+ * Why an order could not be read. Each maps to distinct customer copy, because
+ * "we cannot reach fulfilment" and "this order does not exist" call for very
+ * different things from the person reading the page.
+ */
+export type OrderLookupError = "unconfigured" | "not-found" | "upstream-error" | "network-error";
+
+export type OrderLookup =
+  | { ok: true; order: EsimOrder }
+  | { ok: false; reason: OrderLookupError };
+
+/**
+ * Read one order's fulfilment state and activation artefacts.
+ *
+ * Contract, deliberately stated because nothing in this repository implements
+ * it yet: the storefront expects the Carrier origin named by
+ * NEXT_PUBLIC_CARRIER_API_URL to serve
+ *
+ *     GET {origin}/api/orders/{orderId}       Authorization: Bearer {CARRIER_API_KEY}
+ *     200 -> EsimOrder (see types.ts)
+ *     404 -> order unknown
+ *
+ * The order id is the Stripe Checkout session id. Until an origin serves that
+ * route, every call returns `unconfigured` or `upstream-error` and the activate
+ * page says so in plain words. It does not draw a QR code it does not have.
+ */
+export async function fetchOrder(orderId: string): Promise<OrderLookup> {
+  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" };
+  const key = apiKey();
+  if (key) headers.Authorization = `Bearer ${key}`;
+
+  try {
+    const res = await fetch(`${base}/api/orders/${encodeURIComponent(orderId)}`, {
+      headers,
+      cache: "no-store",
+    });
+    if (res.status === 404) return { ok: false, reason: "not-found" };
+    if (!res.ok) return { ok: false, reason: "upstream-error" };
+    const order = (await res.json()) as EsimOrder;
+    if (!order || typeof order.orderId !== "string") {
+      return { ok: false, reason: "upstream-error" };
+    }
+    return { ok: true, order };
+  } catch {
+    return { ok: false, reason: "network-error" };
+  }
+}

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

@@ -19,3 +19,40 @@ export interface ProvisionEsimResult {
   activationUrl: string;
   expiresAt: string;
 }
+
+/**
+ * Fulfilment state of one purchase.
+ *
+ * "pending"      — paid, not yet handed to provisioning.
+ * "provisioning" — provisioning in flight; the page keeps polling.
+ * "ready"        — an eSIM exists and the activation artefacts below are set.
+ * "failed"       — provisioning gave up; the customer needs a human.
+ */
+export type OrderStatus = "pending" | "provisioning" | "ready" | "failed";
+
+/**
+ * One order as the storefront needs it.
+ *
+ * Everything below `status` is optional because it only exists once
+ * provisioning has succeeded. `qrCode` is an image the page can render
+ * directly (a data: URI or an https URL); `smdpAddress` and `matchingId` are
+ * the same credential in the form a phone accepts typed by hand, which is the
+ * fallback whenever the QR cannot be shown.
+ */
+export interface EsimOrder {
+  orderId: string;
+  status: OrderStatus;
+  templateId?: string;
+  planName?: string;
+  iccid?: string;
+  /** Renderable QR image: data: URI or https URL. */
+  qrCode?: string;
+  /** Full LPA string, e.g. LPA:1$smdp.example.com$MATCHING-ID */
+  activationCode?: string;
+  smdpAddress?: string;
+  matchingId?: string;
+  createdAt?: string;
+  expiresAt?: string;
+  /** Operator-supplied, customer-safe explanation when status is "failed". */
+  failureMessage?: string;
+}