@meterbox/customer-portal 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Meterbox Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @meterbox/customer-portal
+
+Drop-in multi-page React customer portal for Meterbox. One component, three
+pages (Account, Plans, Credits), composed from the widgets shipped in
+[`@meterbox/react`](https://www.npmjs.com/package/@meterbox/react). All data is
+fetched via the `/v1/customer-portal/*` endpoints using a short-lived
+customer-scoped JWT that your backend mints with `POST /v1/tokens/:id`, so no
+API key ever reaches the browser.
+
+```bash
+npm install @meterbox/customer-portal react react-dom
+```
+
+```jsx
+import CustomerPortal from "@meterbox/customer-portal";
+
+function handlePlanSelect(plan, billingInterval) {
+  // Fires alongside the built-in preview + apply/schedule flow below.
+  // Optional, e.g. for your own analytics. You don't need to build a
+  // checkout redirect for a monthly pick; that's what the Plans page
+  // already does. An annual pick still has no in-place apply path (see
+  // below), so route those through your own <CheckoutButton> instead.
+}
+
+<CustomerPortal
+  baseUrl="https://meterbox.ai"
+  customerId="cus_42"
+  customerToken={customerJwt}
+  initialPage="account"
+  onPlanSelect={handlePlanSelect}
+  onTopUp={(balance) => /* mint top-up session */}
+/>
+```
+
+## Pages
+
+- **Account**: name, email, current plan, status (`GET /v1/customer-portal/:id/me`)
+- **Plans**: `<PricingTable>` (monthly/annual toggle included) + inline
+  `<PlanChangeCard>` for a monthly pick: proration preview plus "Change now"
+  / "Schedule for end of period" actions, so picking a plan actually applies
+  it, not just previews it. `onPlanSelect` fires with `(plan,
+billingInterval)` either way. The inline card only covers monthly:
+  `subscription/preview` and `subscription/change` don't prorate an annual
+  commitment yet, so an annual pick shows a short note instead of
+  previewing/applying a misleading number; annual stays on the checkout
+  path (a new Stripe Checkout session with its own annual price).
+- **Credits**: `<CreditBalance>` + `<CreditGrantsTable>` + `<CreditUtilization>`
+
+No router dependency. Page state is internal; wire deep-linking yourself via
+`initialPage` if you want browser-history navigation.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@meterbox/customer-portal",
+  "version": "0.1.0",
+  "description": "Drop-in multi-page React customer portal for Meterbox: Account, Plans, Credits. Built on @meterbox/react.",
+  "license": "MIT",
+  "homepage": "https://meterbox.ai",
+  "main": "src/index.js",
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@meterbox/react": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=17",
+    "react-dom": ">=17"
+  },
+  "keywords": [
+    "meterbox",
+    "react",
+    "customer-portal",
+    "subscription",
+    "credits"
+  ]
+}

package/src/CustomerPortal.js

@@ -0,0 +1,127 @@
+/**
+ * <CustomerPortal /> — drop-in multi-page portal.
+ *
+ *   <CustomerPortal
+ *     baseUrl="https://meterbox.ai"
+ *     customerId="cus_42"
+ *     customerToken={jwt}
+ *     initialPage="account"          // "account" (default) | "plans" | "credits"
+ *     onPageChange={(page) => ...}   // (optional) consumer wires deep-linking
+ *     onPlanSelect={(plan) => ...}   // (optional) host app routes to checkout
+ *     onTopUp={(balance) => ...}     // (optional) host app mints top-up
+ *     threshold={10}                 // (optional) low-balance trigger
+ *     currency="USD"                 // (optional)
+ *     granularity="day"              // (optional)
+ *   />
+ *
+ * No router dependency — page state is internal. Hosts that want
+ * browser-history nav can drive `initialPage` from their own router and
+ * observe `onPageChange`.
+ */
+
+const React = require("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" };
+
+const styles = {
+  shell: {
+    fontFamily: "system-ui, -apple-system, sans-serif",
+    color: "#111",
+    display: "grid",
+    gap: 16,
+    maxWidth: 760,
+  },
+  nav: {
+    display: "flex",
+    gap: 4,
+    borderBottom: "1px solid #e5e7eb",
+    paddingBottom: 0,
+  },
+  tab: {
+    background: "transparent",
+    border: "none",
+    borderBottom: "2px solid transparent",
+    padding: "8px 14px",
+    fontSize: 14,
+    fontWeight: 600,
+    cursor: "pointer",
+    color: "#374151",
+  },
+  tabActive: {
+    color: "#5045e8",
+    borderBottom: "2px solid #5045e8",
+  },
+};
+
+function CustomerPortal({
+  baseUrl,
+  customerId,
+  customerToken,
+  initialPage = "account",
+  onPageChange,
+  onPlanSelect,
+  onTopUp,
+  threshold,
+  currency,
+  granularity,
+  fetch: fetchImpl,
+}) {
+  const initial = PAGES.includes(initialPage) ? initialPage : "account";
+  const [page, setPage] = React.useState(initial);
+
+  // Honor external nav changes via initialPage prop.
+  React.useEffect(() => {
+    if (PAGES.includes(initialPage)) setPage(initialPage);
+  }, [initialPage]);
+
+  const go = (next) => {
+    setPage(next);
+    if (typeof onPageChange === "function") onPageChange(next);
+  };
+
+  const common = { baseUrl, customerId, customerToken, fetch: fetchImpl };
+
+  let body;
+  if (page === "plans") {
+    body = React.createElement(PlansPage, { ...common, currency, onPlanSelect });
+  } else if (page === "credits") {
+    body = React.createElement(CreditsPage, {
+      ...common,
+      threshold,
+      onTopUp,
+      granularity,
+    });
+  } else {
+    body = React.createElement(AccountPage, common);
+  }
+
+  return React.createElement(
+    "div",
+    { className: "meterbox-customer-portal", style: styles.shell },
+    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),
+          },
+          LABELS[p],
+        ),
+      ),
+    ),
+    body,
+  );
+}
+
+module.exports = CustomerPortal;

package/src/index.js

@@ -0,0 +1,19 @@
+/**
+ * @meterbox/customer-portal — drop-in multi-page React customer portal.
+ *
+ * Default export is `<CustomerPortal>`. Individual pages are also exported
+ * so hosts that want to embed just one (e.g. an existing Account page in
+ * their app) can pull it directly.
+ */
+
+const CustomerPortal = require("./CustomerPortal");
+const AccountPage = require("./pages/AccountPage");
+const PlansPage = require("./pages/PlansPage");
+const CreditsPage = require("./pages/CreditsPage");
+
+module.exports = CustomerPortal;
+module.exports.default = CustomerPortal;
+module.exports.CustomerPortal = CustomerPortal;
+module.exports.AccountPage = AccountPage;
+module.exports.PlansPage = PlansPage;
+module.exports.CreditsPage = CreditsPage;

package/src/pages/AccountPage.js

@@ -0,0 +1,146 @@
+/**
+ * <AccountPage /> — fetches GET /v1/customer-portal/:id/me and renders the
+ * customer's own profile + current plan.
+ */
+
+const React = require("react");
+
+const styles = {
+  card: {
+    fontFamily: "system-ui, -apple-system, sans-serif",
+    color: "#111",
+    border: "1px solid #e5e7eb",
+    borderRadius: 12,
+    padding: 20,
+    background: "#fff",
+    display: "grid",
+    gap: 12,
+    maxWidth: 480,
+  },
+  row: { display: "flex", justifyContent: "space-between", fontSize: 14 },
+  label: { opacity: 0.65 },
+  value: { fontWeight: 600 },
+  pill: {
+    display: "inline-block",
+    padding: "1px 8px",
+    borderRadius: 999,
+    fontSize: 11,
+    fontWeight: 600,
+    background: "#ecfdf5",
+    color: "#047857",
+  },
+  pillInactive: { background: "#fef2f2", color: "#b91c1c" },
+};
+
+async function fetchMe({ baseUrl, customerId, customerToken, fetchImpl }) {
+  const url = `${String(baseUrl).replace(/\/+$/, "")}/v1/customer-portal/${encodeURIComponent(
+    customerId,
+  )}/me`;
+  const res = await fetchImpl(url, {
+    method: "GET",
+    headers: { Authorization: `Bearer ${customerToken}` },
+  });
+  const json = await res.json();
+  if (!res.ok) {
+    const err = new Error(json?.error || `HTTP ${res.status}`);
+    err.status = res.status;
+    throw err;
+  }
+  return json;
+}
+
+function AccountPage({ baseUrl, customerId, customerToken, fetch: fetchImpl }) {
+  const [me, setMe] = React.useState(null);
+  const [error, setError] = React.useState(null);
+  const [loading, setLoading] = React.useState(true);
+
+  React.useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    fetchMe({
+      baseUrl,
+      customerId,
+      customerToken,
+      fetchImpl: fetchImpl || globalThis.fetch,
+    })
+      .then((body) => {
+        if (!cancelled) {
+          setMe(body);
+          setLoading(false);
+        }
+      })
+      .catch((err) => {
+        if (!cancelled) {
+          setError(err.message || "Could not load account.");
+          setLoading(false);
+        }
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [baseUrl, customerId, customerToken, fetchImpl]);
+
+  if (loading) {
+    return React.createElement(
+      "div",
+      { style: { opacity: 0.6, fontFamily: styles.card.fontFamily } },
+      "Loading account…",
+    );
+  }
+  if (error) {
+    return React.createElement(
+      "div",
+      { style: { color: "#dc2626", fontFamily: styles.card.fontFamily } },
+      error,
+    );
+  }
+  if (!me) return null;
+  const statusPill =
+    me.status === "active"
+      ? styles.pill
+      : { ...styles.pill, ...styles.pillInactive };
+  return React.createElement(
+    "div",
+    { className: "meterbox-account-page", style: styles.card },
+    me.name &&
+      React.createElement(
+        "div",
+        { style: styles.row },
+        React.createElement("span", { style: styles.label }, "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.value }, me.email),
+      ),
+    React.createElement(
+      "div",
+      { style: styles.row },
+      React.createElement("span", { style: styles.label }, "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),
+    ),
+    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),
+        ),
+      ),
+  );
+}
+
+module.exports = AccountPage;

package/src/pages/CreditsPage.js

@@ -0,0 +1,37 @@
+/**
+ * <CreditsPage /> — composes the three credit widgets in self-fetch mode.
+ * `threshold` + `onTopUp` are passed through to `<CreditBalance>`.
+ */
+
+const React = require("react");
+const { CreditBalance, CreditGrantsTable, CreditUtilization } = require("@meterbox/react");
+
+const styles = {
+  wrap: { display: "grid", gap: 16 },
+  row: { display: "flex", gap: 16, flexWrap: "wrap" },
+};
+
+function CreditsPage({
+  baseUrl,
+  customerId,
+  customerToken,
+  threshold,
+  onTopUp,
+  granularity = "day",
+  fetch: fetchImpl,
+}) {
+  const common = { baseUrl, customerId, customerToken, fetch: fetchImpl };
+  return React.createElement(
+    "div",
+    { className: "meterbox-credits-page", style: styles.wrap },
+    React.createElement(
+      "div",
+      { style: styles.row },
+      React.createElement(CreditBalance, { ...common, threshold, onTopUp }),
+      React.createElement(CreditUtilization, { ...common, granularity }),
+    ),
+    React.createElement(CreditGrantsTable, common),
+  );
+}
+
+module.exports = CreditsPage;

package/src/pages/PlansPage.js

@@ -0,0 +1,147 @@
+/**
+ * <PlansPage /> — fetches the public plan catalog + the customer's current
+ * plan, renders `<PricingTable>`; on plan pick, renders an inline
+ * `<PlanChangeCard>` for that plan — the proration preview plus "Change
+ * now" / "Schedule for end of period" actions, so picking a plan is no
+ * longer a dead end the host app has to build its own apply flow for.
+ * `onPlanSelect(plan, billingInterval)` (if provided) still fires with the
+ * chosen plan and interval, e.g. for the host's own analytics.
+ *
+ * The inline panel only covers a monthly pick — `POST .../subscription/
+ * preview` (and `/subscription/change`) prorate against the plan's monthly
+ * price and have no concept of an annual commitment yet, so showing it for
+ * an annual pick would preview/apply a number that doesn't match what the
+ * customer is actually about to be charged. Annual stays on the checkout
+ * 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.
+ */
+
+const React = require("react");
+const { PricingTable, PlanChangeCard } = require("@meterbox/react");
+
+const styles = {
+  wrap: { display: "grid", gap: 16 },
+};
+
+async function fetchJson(url, headers, fetchImpl) {
+  const res = await fetchImpl(url, { method: "GET", headers });
+  const json = await res.json();
+  if (!res.ok) {
+    const err = new Error(json?.error || `HTTP ${res.status}`);
+    err.status = res.status;
+    throw err;
+  }
+  return json;
+}
+
+function PlansPage({
+  baseUrl,
+  customerId,
+  customerToken,
+  currency = "USD",
+  onPlanSelect,
+  fetch: fetchImpl,
+}) {
+  const fetcher = fetchImpl || globalThis.fetch;
+  const root = String(baseUrl).replace(/\/+$/, "");
+  const [plans, setPlans] = React.useState(null);
+  const [currentPlanId, setCurrentPlanId] = React.useState(null);
+  const [scheduledChange, setScheduledChange] = React.useState(null);
+  const [picked, setPicked] = React.useState(null);
+  const [pickedInterval, setPickedInterval] = React.useState("monthly");
+  const [error, setError] = React.useState(null);
+  const [loading, setLoading] = React.useState(true);
+
+  const fetchMe = React.useCallback(
+    () =>
+      fetchJson(
+        `${root}/v1/customer-portal/${encodeURIComponent(customerId)}/me`,
+        { Authorization: `Bearer ${customerToken}` },
+        fetcher,
+      ),
+    [root, customerId, customerToken, fetcher],
+  );
+
+  React.useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    Promise.all([fetchJson(`${root}/v1/plans`, {}, fetcher), fetchMe()])
+      .then(([catalog, me]) => {
+        if (cancelled) return;
+        setPlans(catalog.plans || []);
+        setCurrentPlanId(me.plan_id || null);
+        setScheduledChange(me.scheduled_change || null);
+        setLoading(false);
+      })
+      .catch((err) => {
+        if (!cancelled) {
+          setError(err.message || "Could not load plans.");
+          setLoading(false);
+        }
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [root, fetcher, fetchMe]);
+
+  // After a confirm/cancel, re-fetch /me so currentPlanId + scheduledChange
+  // reflect what actually landed (not just an optimistic guess).
+  function onChanged() {
+    fetchMe()
+      .then((me) => {
+        setCurrentPlanId(me.plan_id || null);
+        setScheduledChange(me.scheduled_change || null);
+      })
+      .catch(() => {
+        /* the panel already surfaced its own error; a stale currentPlanId
+           here just means the highlight doesn't update until next load */
+      });
+  }
+
+  if (loading) {
+    return React.createElement("div", { style: { opacity: 0.6 } }, "Loading plans…");
+  }
+  if (error) {
+    return React.createElement("div", { style: { color: "#dc2626" } }, error);
+  }
+  return React.createElement(
+    "div",
+    { className: "meterbox-plans-page", style: styles.wrap },
+    React.createElement(PricingTable, {
+      plans,
+      currentPlanId,
+      currency,
+      onSelect: (plan, billingInterval) => {
+        setPicked(plan.id);
+        setPickedInterval(billingInterval || "monthly");
+        if (typeof onPlanSelect === "function") onPlanSelect(plan, billingInterval);
+      },
+    }),
+    // Deliberately NOT also gated on `picked !== currentPlanId`: PricingTable
+    // already disables the current plan's own CTA, so a real click can't
+    // set `picked` to it in the first place. Re-checking against
+    // currentPlanId here would unmount the panel — and its just-rendered
+    // success message — the instant a successful change updates
+    // 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(PlanChangeCard, {
+            baseUrl,
+            customerId,
+            customerToken,
+            planId: picked,
+            scheduledChange,
+            fetch: fetchImpl,
+            onChanged,
+          })),
+  );
+}
+
+module.exports = PlansPage;