@meterbox/customer-portal 0.1.7 → 0.1.9

package/README.md

@@ -30,11 +30,45 @@ function handlePlanSelect(plan, billingInterval) {
   customerId="cus_42"
   customerToken={customerJwt}
   initialPage="account"
+  locale="en"
   onPlanSelect={handlePlanSelect}
   onTopUp={(balance) => /* mint top-up session */}
 />
 ```
 
+## Deep links
+
+`initialAction` opens the portal on an action rather than a page, for links
+like "cancel" or "upgrade to Pro" in your emails or app:
+
+```jsx
+<CustomerPortal {...props} initialAction={{ type: "cancel" }} />
+<CustomerPortal {...props} initialAction={{ type: "change_plan", planId: "pro" }} />
+```
+
+`cancel` opens the cancel flow on the Account page, at its "Why are you
+cancelling?" step. `change_plan` opens the Plans page with that plan picked:
+its proration preview and the "Change now" / "Schedule for end of period"
+buttons. A plan that's the customer's current one, or that isn't published,
+picks nothing. The action applies once; moving to another tab drops it.
+
+## Language
+
+`locale` shows the portal in your customer's language, with dates and amounts
+formatted for it: English (the default), Spanish (`es`), French (`fr`) and
+German (`de`) are built in. `messages` overrides any string by its key, or
+translates them all for another language (anything missing stays in
+English):
+
+```jsx
+<CustomerPortal {...props} locale={navigator.language} />
+<CustomerPortal {...props} locale="it" messages={{ "portal.account": "Conto" }} />
+```
+
+The keys are listed in
+[`@meterbox/react`'s `src/i18n.js`](https://www.npmjs.com/package/@meterbox/react).
+Plan names, features and retention offers are shown as you entered them.
+
 ## Branding
 
 The portal takes your branding from Settings → Branding
@@ -45,6 +79,8 @@ override it.
 ## Pages
 
 - **Account**: name, email, current plan, status (`GET /v1/customer-portal/:id/me`),
+  a button to update the payment method and billing details on Stripe's own
+  portal (`<BillingDetailsButton>`, when available),
   and **Cancel subscription**: the customer gives a reason, sees your plan's
   retention offers (a discount, a longer trial, or a downgrade) and either takes
   one or cancels at the end of the period, keeping access until then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meterbox/customer-portal",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Drop-in multi-page React customer portal for Meterbox: Account, Plans, Credits. Built on @meterbox/react.",
   "license": "MIT",
   "homepage": "https://meterbox.ai",
@@ -17,7 +17,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@meterbox/react": "0.1.5"
+    "@meterbox/react": "0.1.7"
   },
   "peerDependencies": {
     "react": ">=17",

package/src/CancelSubscription.js

@@ -3,10 +3,13 @@
  * reason, see the plan's retention offers, and either take one and stay or
  * cancel at the end of the period (keeping access until then). Uses the
  * /v1/customer-portal/:id/cancellation endpoints with the customer token.
+ *
+ * `initialStep="reason"` opens straight on the reason step (the portal's
+ * cancel deep link).
  */
 
 const React = require("react");
-const { theme } = require("@meterbox/react");
+const { theme, useI18n } = require("@meterbox/react");
 
 const REASONS = {
   too_expensive: "It's too expensive",
@@ -46,10 +49,6 @@ const styles = {
   muted: { opacity: 0.7 },
 };
 
-function formatDate(iso) {
-  return iso ? String(iso).slice(0, 10) : "the end of the period";
-}
-
 function button(label, onClick, extra = {}, disabled = false) {
   return React.createElement(
     "button",
@@ -65,9 +64,12 @@ function CancelSubscription({
   fetch: fetchImpl,
   status,
   cancelAt,
+  initialStep = "idle",
   onChange,
 }) {
-  const [step, setStep] = React.useState("idle"); // idle → reason → offers → done
+  const { t, date } = useI18n();
+  // idle → reason → offers → done
+  const [step, setStep] = React.useState(initialStep === "reason" ? "reason" : "idle");
   const [reason, setReason] = React.useState("too_expensive");
   const [detail, setDetail] = React.useState("");
   const [offers, setOffers] = React.useState([]);
@@ -75,6 +77,10 @@ function CancelSubscription({
   const [error, setError] = React.useState(null);
   const [busy, setBusy] = React.useState(false);
 
+  function endsOn(iso) {
+    return iso ? t("cancel.endsOn", { date: date(iso) }) : t("cancel.endsAtPeriodEnd");
+  }
+
   async function call(method, sub, body) {
     const url = `${String(baseUrl).replace(/\/+$/, "")}/v1/customer-portal/${encodeURIComponent(
       customerId,
@@ -95,7 +101,7 @@ function CancelSubscription({
     try {
       await fn();
     } catch (err) {
-      setError(err.message || "Something went wrong.");
+      setError(err.message || t("cancel.error"));
     } finally {
       setBusy(false);
     }
@@ -113,14 +119,14 @@ function CancelSubscription({
   const accept = (offer) =>
     run(async () => {
       await call("POST", "/accept-offer", { offer_id: offer.id });
-      setDone(`Done: ${offer.label}. Your subscription continues.`);
+      setDone(t("cancel.offerTaken", { offer: offer.label }));
       setStep("done");
       if (onChange) onChange();
     });
   const confirm = () =>
     run(async () => {
       const r = await call("POST", "/confirm");
-      setDone(`Your subscription ends on ${formatDate(r.cancel_at)}. You keep access until then.`);
+      setDone(endsOn(r.cancel_at));
       setStep("done");
       if (onChange) onChange();
     });
@@ -131,66 +137,61 @@ function CancelSubscription({
     });
 
   if (status === "cancelling") {
-    return React.createElement(
-      "div",
-      { style: styles.box },
-      `Your subscription ends on ${formatDate(cancelAt)}. You keep access until then.`,
-    );
+    return React.createElement("div", { style: styles.box }, endsOn(cancelAt));
   }
   if (status === "cancelled") return null;
 
   let content;
   if (step === "idle") {
-    content = button("Cancel subscription", () => setStep("reason"), styles.danger);
+    content = button(t("cancel.button"), () => setStep("reason"), styles.danger);
   } else if (step === "reason") {
     content = React.createElement(
       React.Fragment,
       null,
-      React.createElement("strong", null, "Why are you cancelling?"),
+      React.createElement("strong", null, t("cancel.why")),
       React.createElement(
         "select",
         {
           value: reason,
           onChange: (e) => setReason(e.target.value),
-          "aria-label": "Reason for cancelling",
+          "aria-label": t("cancel.reasonLabel"),
         },
-        Object.entries(REASONS).map(([value, label]) =>
-          React.createElement("option", { key: value, value }, label),
+        Object.keys(REASONS).map((value) =>
+          React.createElement("option", { key: value, value }, t(`cancel.reason.${value}`)),
         ),
       ),
       React.createElement("textarea", {
         value: detail,
         onChange: (e) => setDetail(e.target.value),
-        placeholder: "Anything else we should know? (optional)",
-        "aria-label": "More about why",
+        placeholder: t("cancel.detailPlaceholder"),
+        "aria-label": t("cancel.detailLabel"),
         rows: 3,
       }),
       React.createElement(
         "div",
         { style: styles.row },
-        button("Continue", start, styles.primary, busy),
-        button("Keep my subscription", () => setStep("idle"), {}, busy),
+        button(t("cancel.continue"), start, styles.primary, busy),
+        button(t("cancel.keep"), () => setStep("idle"), {}, busy),
       ),
     );
   } else if (step === "offers") {
     content = React.createElement(
       React.Fragment,
       null,
-      offers.length > 0 &&
-        React.createElement("strong", null, "Before you go, would one of these help?"),
+      offers.length > 0 && React.createElement("strong", null, t("cancel.offersTitle")),
       ...offers.map((offer) =>
         React.createElement(
           "div",
           { key: offer.id, style: styles.offer },
           React.createElement("span", null, offer.label),
-          button("Accept", () => accept(offer), styles.primary, busy),
+          button(t("cancel.accept"), () => accept(offer), styles.primary, busy),
         ),
       ),
       React.createElement(
         "div",
         { style: styles.row },
-        button("Cancel at the end of the period", confirm, styles.danger, busy),
-        button("Keep my subscription", keep, {}, busy),
+        button(t("cancel.confirm"), confirm, styles.danger, busy),
+        button(t("cancel.keep"), keep, {}, busy),
       ),
     );
   } else {

package/src/CustomerPortal.js

@@ -6,6 +6,9 @@
  *     customerId="cus_42"
  *     customerToken={jwt}
  *     initialPage="account"          // "account" (default) | "plans" | "credits"
+ *     initialAction={{ type: "cancel" }}   // (optional) deep link, see below
+ *     locale="fr"                    // (optional) language + date/amount format
+ *     messages={{ "cancel.button": "..." }} // (optional) override any string
  *     onPageChange={(page) => ...}   // (optional) consumer wires deep-linking
  *     onPlanSelect={(plan) => ...}   // (optional) host app routes to checkout
  *     onTopUp={(balance) => ...}     // (optional) host app mints top-up
@@ -22,16 +25,28 @@
  * No router dependency — page state is internal. Hosts that want
  * browser-history nav can drive `initialPage` from their own router and
  * observe `onPageChange`.
+ *
+ * Deep links: `initialAction` opens straight on an action rather than a
+ * page: `{ type: "cancel" }` opens the cancel flow on the Account page, at
+ * its reason step; `{ type: "change_plan", planId: "pro" }` opens the Plans
+ * page with that plan picked (its proration preview and Change now /
+ * Schedule buttons). The action applies once; moving to another tab drops it.
+ *
+ * Language: `locale` translates every string (English, Spanish, French and
+ * German built in, through @meterbox/react's <LocaleProvider>) and formats
+ * dates and amounts for it; `messages` overrides any string by its key, or
+ * translates them all for another language. English when unset.
  */
 
 const React = require("react");
-const { BrandingProvider, logoUrl, theme } = require("@meterbox/react");
+const { BrandingProvider, LocaleProvider, useI18n, logoUrl, theme } = require("@meterbox/react");
 const AccountPage = require("./pages/AccountPage");
 const PlansPage = require("./pages/PlansPage");
 const CreditsPage = require("./pages/CreditsPage");
 
 const PAGES = ["account", "plans", "credits"];
-const LABELS = { account: "Account", plans: "Plans", credits: "Credits" };
+// The page each deep link opens on.
+const ACTION_PAGES = { cancel: "account", change_plan: "plans" };
 
 const styles = {
   shell: {
@@ -78,11 +93,36 @@ async function fetchBranding({ baseUrl, customerId, customerToken, fetchImpl })
   return res.ok ? res.json() : null;
 }
 
+function Tabs({ page, go }) {
+  const { t } = useI18n();
+  return React.createElement(
+    "nav",
+    { style: styles.nav, role: "tablist" },
+    PAGES.map((p) =>
+      React.createElement(
+        "button",
+        {
+          key: p,
+          type: "button",
+          role: "tab",
+          "aria-selected": page === p,
+          style: page === p ? { ...styles.tab, ...styles.tabActive } : styles.tab,
+          onClick: () => go(p),
+        },
+        t(`portal.${p}`),
+      ),
+    ),
+  );
+}
+
 function CustomerPortal({
   baseUrl,
   customerId,
   customerToken,
   initialPage = "account",
+  initialAction,
+  locale,
+  messages,
   onPageChange,
   onPlanSelect,
   onTopUp,
@@ -92,7 +132,11 @@ function CustomerPortal({
   branding,
   fetch: fetchImpl,
 }) {
-  const initial = PAGES.includes(initialPage) ? initialPage : "account";
+  const actionType = ACTION_PAGES[initialAction?.type] ? initialAction.type : null;
+  const actionPlanId = initialAction?.planId || null;
+  const [action, setAction] = React.useState(actionType);
+  const initial =
+    ACTION_PAGES[actionType] || (PAGES.includes(initialPage) ? initialPage : "account");
   const [page, setPage] = React.useState(initial);
   const [tenant, setTenant] = React.useState(null);
 
@@ -113,19 +157,37 @@ function CustomerPortal({
 
   // Honor external nav changes via initialPage prop.
   React.useEffect(() => {
-    if (PAGES.includes(initialPage)) setPage(initialPage);
+    if (!PAGES.includes(initialPage)) return;
+    setAction(null);
+    setPage(initialPage);
   }, [initialPage]);
 
+  // ...and a new deep link (after the above, so on mount the deep link wins).
+  React.useEffect(() => {
+    if (!actionType) return;
+    setAction(actionType);
+    setPage(ACTION_PAGES[actionType]);
+  }, [actionType, actionPlanId]);
+
   const go = (next) => {
+    setAction(null);
     setPage(next);
     if (typeof onPageChange === "function") onPageChange(next);
   };
 
   const common = { baseUrl, customerId, customerToken, fetch: fetchImpl };
 
+  // Keyed by the deep link, so a new one remounts the page and applies.
+  const key = action ? `${action}:${actionPlanId || ""}` : "page";
   let body;
   if (page === "plans") {
-    body = React.createElement(PlansPage, { ...common, currency, onPlanSelect });
+    body = React.createElement(PlansPage, {
+      ...common,
+      key,
+      currency,
+      onPlanSelect,
+      initialPlanId: action === "change_plan" ? actionPlanId : undefined,
+    });
   } else if (page === "credits") {
     body = React.createElement(CreditsPage, {
       ...common,
@@ -134,42 +196,33 @@ function CustomerPortal({
       granularity,
     });
   } else {
-    body = React.createElement(AccountPage, common);
+    body = React.createElement(AccountPage, {
+      ...common,
+      key,
+      startCancel: action === "cancel",
+    });
   }
 
   return React.createElement(
-    BrandingProvider,
-    { branding: brand },
+    LocaleProvider,
+    { locale, messages },
     React.createElement(
-      "div",
-      { className: "meterbox-customer-portal", style: styles.shell },
-      (logo || companyName) &&
-        React.createElement(
-          "header",
-          { style: styles.header },
-          logo &&
-            React.createElement("img", { src: logo, alt: companyName || "", style: styles.logo }),
-          companyName && React.createElement("span", { style: styles.company }, companyName),
-        ),
+      BrandingProvider,
+      { branding: brand },
       React.createElement(
-        "nav",
-        { style: styles.nav, role: "tablist" },
-        PAGES.map((p) =>
+        "div",
+        { className: "meterbox-customer-portal", style: styles.shell },
+        (logo || companyName) &&
           React.createElement(
-            "button",
-            {
-              key: p,
-              type: "button",
-              role: "tab",
-              "aria-selected": page === p,
-              style: page === p ? { ...styles.tab, ...styles.tabActive } : styles.tab,
-              onClick: () => go(p),
-            },
-            LABELS[p],
+            "header",
+            { style: styles.header },
+            logo &&
+              React.createElement("img", { src: logo, alt: companyName || "", style: styles.logo }),
+            companyName && React.createElement("span", { style: styles.company }, companyName),
           ),
-        ),
+        React.createElement(Tabs, { page, go }),
+        body,
       ),
-      body,
     ),
   );
 }

package/src/pages/AccountPage.js

@@ -1,11 +1,14 @@
 /**
  * <AccountPage /> — fetches GET /v1/customer-portal/:id/me and renders the
- * customer's own profile + current plan, the way to cancel, and their
- * invoices with PDFs (`<InvoiceHistory>` from @meterbox/react).
+ * customer's own profile + current plan, a button to update their payment
+ * method and billing details on Stripe's portal (when available), the way to
+ * cancel, and their invoices with PDFs (`<InvoiceHistory>` from
+ * @meterbox/react). `startCancel` opens the cancel flow on its reason step
+ * (the portal's cancel deep link).
  */
 
 const React = require("react");
-const { InvoiceHistory, theme } = require("@meterbox/react");
+const { InvoiceHistory, BillingDetailsButton, theme, useI18n } = require("@meterbox/react");
 const CancelSubscription = require("../CancelSubscription");
 
 const styles = {
@@ -52,13 +55,20 @@ async function fetchMe({ baseUrl, customerId, customerToken, fetchImpl }) {
   return json;
 }
 
-function AccountPage({ baseUrl, customerId, customerToken, fetch: fetchImpl }) {
+function AccountPage({ baseUrl, customerId, customerToken, startCancel, fetch: fetchImpl }) {
+  const { t, date } = useI18n();
   const [me, setMe] = React.useState(null);
   const [error, setError] = React.useState(null);
   const [loading, setLoading] = React.useState(true);
+  const [billingError, setBillingError] = React.useState(null);
   // Bumped after a cancellation step, to show the new status.
   const [version, setVersion] = React.useState(0);
-  const reload = React.useCallback(() => setVersion((v) => v + 1), []);
+  // The cancel deep link opens the flow once, not again on each reload.
+  const [openCancel, setOpenCancel] = React.useState(Boolean(startCancel));
+  const reload = React.useCallback(() => {
+    setOpenCancel(false);
+    setVersion((v) => v + 1);
+  }, []);
 
   React.useEffect(() => {
     let cancelled = false;
@@ -78,7 +88,7 @@ function AccountPage({ baseUrl, customerId, customerToken, fetch: fetchImpl }) {
       })
       .catch((err) => {
         if (!cancelled) {
-          setError(err.message || "Could not load account.");
+          setError(err.message || t("account.error"));
           setLoading(false);
         }
       });
@@ -91,7 +101,7 @@ function AccountPage({ baseUrl, customerId, customerToken, fetch: fetchImpl }) {
     return React.createElement(
       "div",
       { style: { opacity: 0.6, fontFamily: styles.card.fontFamily } },
-      "Loading account…",
+      t("account.loading"),
     );
   }
   if (error) {
@@ -111,46 +121,52 @@ function AccountPage({ baseUrl, customerId, customerToken, fetch: fetchImpl }) {
       React.createElement(
         "div",
         { style: styles.row },
-        React.createElement("span", { style: styles.label }, "Name"),
+        React.createElement("span", { style: styles.label }, t("account.name")),
         React.createElement("span", { style: styles.value }, me.name),
       ),
     me.email &&
       React.createElement(
         "div",
         { style: styles.row },
-        React.createElement("span", { style: styles.label }, "Email"),
+        React.createElement("span", { style: styles.label }, t("account.email")),
         React.createElement("span", { style: styles.value }, me.email),
       ),
     React.createElement(
       "div",
       { style: styles.row },
-      React.createElement("span", { style: styles.label }, "Plan"),
+      React.createElement("span", { style: styles.label }, t("account.plan")),
       React.createElement("span", { style: styles.value }, me.plan_name || me.plan_id),
     ),
     React.createElement(
       "div",
       { style: styles.row },
-      React.createElement("span", { style: styles.label }, "Status"),
-      React.createElement("span", { style: statusPill }, me.status),
+      React.createElement("span", { style: styles.label }, t("account.status")),
+      React.createElement("span", { style: statusPill }, t(`status.${me.status}`, null, me.status)),
     ),
     me.current_period_end &&
       React.createElement(
         "div",
         { style: styles.row },
-        React.createElement("span", { style: styles.label }, "Current period ends"),
-        React.createElement(
-          "span",
-          { style: styles.value },
-          String(me.current_period_end).slice(0, 10),
-        ),
+        React.createElement("span", { style: styles.label }, t("account.periodEnds")),
+        React.createElement("span", { style: styles.value }, date(me.current_period_end)),
       ),
     me.cancel_at &&
       React.createElement(
         "div",
         { style: styles.row },
-        React.createElement("span", { style: styles.label }, "Ends on"),
-        React.createElement("span", { style: styles.value }, String(me.cancel_at).slice(0, 10)),
+        React.createElement("span", { style: styles.label }, t("account.endsOn")),
+        React.createElement("span", { style: styles.value }, date(me.cancel_at)),
       ),
+    me.billing_details_available &&
+      React.createElement(BillingDetailsButton, {
+        baseUrl,
+        customerId,
+        customerToken,
+        fetch: fetchImpl,
+        onError: (err) => setBillingError(err.message),
+      }),
+    billingError &&
+      React.createElement("span", { role: "alert", style: { color: "#dc2626" } }, billingError),
   );
   return React.createElement(
     "div",
@@ -163,6 +179,7 @@ function AccountPage({ baseUrl, customerId, customerToken, fetch: fetchImpl }) {
       fetch: fetchImpl,
       status: me.status,
       cancelAt: me.cancel_at,
+      initialStep: openCancel ? "reason" : "idle",
       onChange: reload,
     }),
     React.createElement(InvoiceHistory, { baseUrl, customerId, customerToken, fetch: fetchImpl }),

package/src/pages/PlansPage.js

@@ -16,10 +16,13 @@
  * path (`<CheckoutButton billingInterval="annual">`, a new Stripe Checkout
  * session with its own annual price) — a short note stands in here instead
  * of a silently wrong in-place change.
+ *
+ * `initialPlanId` picks that plan once the plans load (the portal's "change
+ * to plan X" deep link), unless it's the current plan or not offered.
  */
 
 const React = require("react");
-const { PricingTable, PlanChangeCard } = require("@meterbox/react");
+const { PricingTable, PlanChangeCard, useI18n } = require("@meterbox/react");
 
 const styles = {
   wrap: { display: "grid", gap: 16 },
@@ -41,9 +44,11 @@ function PlansPage({
   customerId,
   customerToken,
   currency = "USD",
+  initialPlanId,
   onPlanSelect,
   fetch: fetchImpl,
 }) {
+  const { t } = useI18n();
   const fetcher = fetchImpl || globalThis.fetch;
   const root = String(baseUrl).replace(/\/+$/, "");
   const [plans, setPlans] = React.useState(null);
@@ -78,14 +83,18 @@ function PlansPage({
     ])
       .then(([catalog, me]) => {
         if (cancelled) return;
-        setPlans(catalog.plans || []);
+        const list = catalog.plans || [];
+        setPlans(list);
         setCurrentPlanId(me.plan_id || null);
         setScheduledChange(me.scheduled_change || null);
+        if (initialPlanId !== me.plan_id && list.some((p) => p.id === initialPlanId)) {
+          setPicked(initialPlanId);
+        }
         setLoading(false);
       })
       .catch((err) => {
         if (!cancelled) {
-          setError(err.message || "Could not load plans.");
+          setError(err.message || t("plans.error"));
           setLoading(false);
         }
       });
@@ -109,7 +118,7 @@ function PlansPage({
   }
 
   if (loading) {
-    return React.createElement("div", { style: { opacity: 0.6 } }, "Loading plans…");
+    return React.createElement("div", { style: { opacity: 0.6 } }, t("plans.loading"));
   }
   if (error) {
     return React.createElement("div", { style: { color: "#dc2626" } }, error);
@@ -135,11 +144,7 @@ function PlansPage({
     // currentPlanId to match what was just picked.
     picked &&
       (pickedInterval === "annual"
-        ? React.createElement(
-            "p",
-            { style: { fontSize: 13, opacity: 0.7 } },
-            "Cost preview isn't available for annual billing yet — the amount due will be confirmed at checkout.",
-          )
+        ? React.createElement("p", { style: { fontSize: 13, opacity: 0.7 } }, t("plans.annualNote"))
         : React.createElement(PlanChangeCard, {
             baseUrl,
             customerId,