@carrierllc/mcp 0.11.17 → 0.12.0

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/geo/index.ts

@@ -19,6 +19,51 @@ export function formatPrice(cents: number, currency = "EUR", locale = "en"): str
   }
 }
 
+/**
+ * A plan's data allowance as a shopper reads it.
+ *
+ * Zero is not "0 GB" — an unmetered plan is the thing the customer is being
+ * sold, and printing a zero next to a price reads as a broken row.
+ */
+export function formatDataAllowance(dataGb: number): string {
+  if (!Number.isFinite(dataGb) || dataGb <= 0) return "Unlimited data";
+  if (dataGb < 1) return `${Math.round(dataGb * 1024)} MB data`;
+  return `${Number.isInteger(dataGb) ? dataGb : dataGb.toFixed(1)} GB data`;
+}
+
+/** A plan's validity window, singular-aware. */
+export function formatValidity(validityDays: number): string {
+  if (!Number.isFinite(validityDays) || validityDays <= 0) return "No expiry";
+  if (validityDays === 1) return "1 day";
+  if (validityDays % 7 === 0 && validityDays >= 7) {
+    const weeks = validityDays / 7;
+    return weeks === 1 ? "1 week" : `${weeks} weeks`;
+  }
+  return `${validityDays} days`;
+}
+
+/**
+ * Bytes as a usage meter shows them.
+ *
+ * Decimal units (1 GB = 1000 MB), because that is the unit a data bundle is
+ * sold in — showing 0.93 GB left of a 1 GB plan the moment it is bought is a
+ * support ticket, not a rounding preference.
+ */
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes <= 0) return "0 MB";
+  if (bytes >= 1_000_000_000) return `${(bytes / 1_000_000_000).toFixed(bytes >= 10_000_000_000 ? 0 : 1)} GB`;
+  if (bytes >= 1_000_000) return `${Math.round(bytes / 1_000_000)} MB`;
+  return `${Math.max(1, Math.round(bytes / 1_000))} KB`;
+}
+
+/** Days left until an ISO timestamp, floored at zero. Null when unparseable. */
+export function daysUntil(iso: string | undefined, now: Date = new Date()): number | null {
+  if (!iso) return null;
+  const then = Date.parse(iso);
+  if (Number.isNaN(then)) return null;
+  return Math.max(0, Math.ceil((then - now.getTime()) / 86_400_000));
+}
+
 export type DisplayCurrency = "EUR" | "USD" | "GBP";
 
 export const SUPPORTED_CURRENCIES: DisplayCurrency[] = ["EUR", "USD", "GBP"];

package/templates/storefront/src/vendor/ui/brand.ts

@@ -7,8 +7,15 @@ export const BRAND = {
   name: brand.name,
   legalName: brand.legalName,
   tagline: brand.tagline,
-  description: `Unlimited data in 200+ countries. Instant QR activation. WhatsApp support.`,
+  description: brand.description,
   domain: brand.domain,
+  appUrl: brand.appUrl,
+  email: {
+    fromName: brand.emailFromName,
+    // Composed, not configured. Keeping the mailbox and the domain as one
+    // field is how a storefront ends up sending from a domain it does not own.
+    fromAddress: `${brand.emailFromMailbox}@${brand.domain}`,
+  },
   support: {
     email: brand.supportEmail,
     whatsapp: brand.supportWhatsapp,