@startsimpli/billing 0.4.35 → 0.4.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/billing",
-  "version": "0.4.35",
+  "version": "0.4.37",
   "description": "Universal billing integration for StartSimpli Next.js apps",
   "license": "MIT",
   "homepage": "https://startsimpli.com",
@@ -35,8 +35,8 @@
     "next": ">=14.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@startsimpli/api": "^0.5.73",
-    "@startsimpli/ui": "^0.4.176"
+    "@startsimpli/api": "^0.5.75",
+    "@startsimpli/ui": "^0.4.177"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {
@@ -61,8 +61,8 @@
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5",
-    "@startsimpli/api": "0.5.73",
-    "@startsimpli/ui": "0.4.176"
+    "@startsimpli/ui": "0.4.177",
+    "@startsimpli/api": "0.5.75"
   },
   "keywords": [
     "billing",

package/src/components/CurrentPlanCard.tsx

@@ -16,7 +16,9 @@
 
 import React from "react";
 import type { OfferFeature, SubscriptionInfo, UsageMap } from "../types";
-import { formatFeatureLabel, formatPrice } from "../utils/format";
+import { formatPrice } from "../utils/format";
+import { FeatureLabel } from "./FeatureLabel";
+import { withBillingCopy, type BillingCopy, type BillingCopyInput, type FeatureCopy } from "../copy";
 
 export interface CurrentPlanCardProps {
   subscription: SubscriptionInfo;
@@ -29,10 +31,14 @@ export interface CurrentPlanCardProps {
    * "Reactivate", trial "Cancel trial". SubscriptionManager wires this to
    * usePortal so apps don't reinvent it. startsim-br2 + startsim-xe5 + startsim-dyg. */
   onPortalClick?: () => void;
+  /** Wording overrides (badges, banners, button labels). */
+  copy?: BillingCopyInput;
+  /** Feature-row overrides by feature key. */
+  featureCopy?: FeatureCopy;
 }
 
-function priceLabel(offer: SubscriptionInfo["offer"]): string {
-  if (offer.isFree) return "Free";
+function priceLabel(offer: SubscriptionInfo["offer"], free = "Free"): string {
+  if (offer.isFree) return free;
   return formatPrice(offer.unitPrice, offer.currency);
 }
 
@@ -40,27 +46,22 @@ function isProgressBarFeature(f: OfferFeature): boolean {
   return typeof f.limit === "number" && f.limit > 0;
 }
 
-function featureLabel(f: OfferFeature): string | null {
-  if (f.value === false) return null;
-  return formatFeatureLabel(f);
-}
-
 /**
  * The card's one status pill. A plan that is ending (cancelled, or cancelled
  * at period end) reads "Ends <date>": it used to say "Active" beside a
  * "your plan is cancelled" banner (crochet_patterns-3bzni, -pes38). A trial
  * reads "Trialing" only; its end date is in the banner (crochet_patterns-rjg2e).
  */
-function StatusBadge({ status, endsOn }: { status: string; endsOn: string | null }) {
+function StatusBadge({ status, endsOn, copy }: { status: string; endsOn: string | null; copy: BillingCopy }) {
   if (endsOn) {
     return (
       <span
         data-testid="plan-status"
         role="status"
-        aria-label={`Subscription status: ends ${prettyDate(endsOn)}`}
+        aria-label={copy.statusAria(copy.endsOnAria(prettyDate(endsOn)))}
         className="inline-block text-xs font-semibold px-3 py-1 rounded-full bg-gray-100 text-gray-600"
       >
-        {`Ends ${prettyDate(endsOn)}`}
+        {copy.endsOn(prettyDate(endsOn))}
       </span>
     );
   }
@@ -75,21 +76,13 @@ function StatusBadge({ status, endsOn }: { status: string; endsOn: string | null
     case "unpaid":            cls += "bg-red-50 text-red-700"; break;
     default:                  cls += "bg-gray-100 text-gray-600";
   }
-  const labels: Record<string, string> = {
-    active: "Active",
-    trialing: "Trialing",
-    past_due: "Past due",
-    cancelled: "Cancelled",
-    incomplete: "Incomplete",
-    incomplete_expired: "Expired",
-    unpaid: "Unpaid",
-  };
+  const labels = copy.status;
   const readable = labels[status] ?? status;
   return (
     <span
       data-testid="plan-status"
       role="status"
-      aria-label={`Subscription status: ${readable}`}
+      aria-label={copy.statusAria(readable)}
       className={cls}
     >
       {readable}
@@ -112,9 +105,8 @@ function ProgressBar({ used, limit }: { used: number; limit: number }) {
   );
 }
 
-function FeatureRow({ feature, used }: { feature: OfferFeature; used: number | null }) {
-  const label = featureLabel(feature);
-  if (label === null) return null;
+function FeatureRow({ feature, used, featureCopy }: { feature: OfferFeature; used: number | null; featureCopy?: FeatureCopy }) {
+  if (feature.value === false) return null;
 
   const showBar = isProgressBarFeature(feature) && used !== null;
   const limit = feature.limit as number;
@@ -126,7 +118,7 @@ function FeatureRow({ feature, used }: { feature: OfferFeature; used: number | n
              stroke="currentColor" strokeWidth={2.5} aria-hidden="true">
           <path strokeLinecap="round" strokeLinejoin="round" d="M5 13l4 4L19 7" />
         </svg>
-        <span className="flex-1">{label}</span>
+        <FeatureLabel feature={feature} featureCopy={featureCopy} className="flex-1" />
         {showBar && (
           <span data-testid={`usage-count-${feature.key}`} className="text-xs text-gray-500 tabular-nums">
             {used} / {limit}
@@ -189,7 +181,8 @@ function StateBanner({ testId, variant, message, action }: BannerProps) {
   );
 }
 
-export function CurrentPlanCard({ subscription, usage, upgradeCta, onPortalClick }: CurrentPlanCardProps) {
+export function CurrentPlanCard({ subscription, usage, upgradeCta, onPortalClick, copy: copyOverride, featureCopy }: CurrentPlanCardProps) {
+  const copy = withBillingCopy(copyOverride);
   const offer = subscription.offer;
   const features = offer.features ?? [];
   const ending = subscription.status === "cancelled" || subscription.cancelAtPeriodEnd;
@@ -207,26 +200,26 @@ export function CurrentPlanCard({ subscription, usage, upgradeCta, onPortalClick
         message={
           <>
             {/* Not dated: the period end is not when the payment failed (crochet_patterns-lb8u3). */}
-            Your last payment failed. Update your card to keep your subscription active.
+            {copy.pastDueMessage}
           </>
         }
-        action={{ label: "Update card", onClick: onPortalClick }}
+        action={{ label: copy.updateCard, onClick: onPortalClick }}
       />
     );
   } else if (subscription.status === "cancelled" || subscription.cancelAtPeriodEnd) {
     // startsim-dyg: cancelled-in-period — user keeps access until the end of
     // the period, can reactivate via portal.
-    const endDate = subscription.currentPeriodEnd ? prettyDate(subscription.currentPeriodEnd) : "the end of your period";
+    const endDate = subscription.currentPeriodEnd ? prettyDate(subscription.currentPeriodEnd) : copy.endOfPeriod;
     stateBanner = (
       <StateBanner
         testId="banner-cancelled-in-period"
         variant="neutral"
         message={
           <>
-            Your {offer.name} plan is cancelled. You'll keep access until {endDate}.
+            {copy.cancelledMessage(offer.name, endDate)}
           </>
         }
-        action={onPortalClick ? { label: "Reactivate", onClick: onPortalClick } : undefined}
+        action={onPortalClick ? { label: copy.reactivate, onClick: onPortalClick } : undefined}
       />
     );
   } else if ((subscription.status === "incomplete" || subscription.status === "incomplete_expired") && onPortalClick) {
@@ -241,11 +234,11 @@ export function CurrentPlanCard({ subscription, usage, upgradeCta, onPortalClick
         variant="warning"
         message={
           expired
-            ? `Your ${offer.name} checkout expired. Start over to activate the plan.`
-            : `Your ${offer.name} plan setup is incomplete. Finish checkout to activate.`
+            ? copy.checkoutExpired(offer.name)
+            : copy.setupIncomplete(offer.name)
         }
         action={{
-          label: expired ? "Start over" : "Finish checkout",
+          label: expired ? copy.startOver : copy.finishCheckout,
           onClick: onPortalClick,
         }}
       />
@@ -256,16 +249,16 @@ export function CurrentPlanCard({ subscription, usage, upgradeCta, onPortalClick
     const days = daysUntil(subscription.trialEnd);
     const variant: "info" | "warning" = days <= 3 ? "warning" : "info";
     const label = days <= 0
-      ? `Your trial ends today (${prettyDate(subscription.trialEnd)}).`
+      ? copy.trialEndsToday(prettyDate(subscription.trialEnd))
       : days === 1
-        ? `Your trial ends tomorrow (${prettyDate(subscription.trialEnd)}).`
-        : `Your trial ends in ${days} days (${prettyDate(subscription.trialEnd)}).`;
+        ? copy.trialEndsTomorrow(prettyDate(subscription.trialEnd))
+        : copy.trialEndsIn(days, prettyDate(subscription.trialEnd));
     stateBanner = (
       <StateBanner
         testId="banner-trialing"
         variant={variant}
         message={label}
-        action={onPortalClick ? { label: "Cancel trial", onClick: onPortalClick } : undefined}
+        action={onPortalClick ? { label: copy.cancelTrial, onClick: onPortalClick } : undefined}
       />
     );
   }
@@ -275,17 +268,17 @@ export function CurrentPlanCard({ subscription, usage, upgradeCta, onPortalClick
       {stateBanner}
       <div className="flex items-center justify-between mb-4">
         <h2 className="text-xl font-bold text-gray-900">{offer.name}</h2>
-        <StatusBadge status={subscription.status} endsOn={endsOn} />
+        <StatusBadge status={subscription.status} endsOn={endsOn} copy={copy} />
       </div>
 
       <div className="mb-4">
         {offer.isFree ? (
-          <span aria-label="Free">
-            <span aria-hidden="true" className="text-3xl font-extrabold text-gray-900">Free</span>
+          <span aria-label={copy.freePrice}>
+            <span aria-hidden="true" className="text-3xl font-extrabold text-gray-900">{copy.freePrice}</span>
           </span>
         ) : (
-          <span aria-label={`${priceLabel(offer)} ${offer.intervalDisplay}`}>
-            <span aria-hidden="true" className="text-3xl font-extrabold text-gray-900">{priceLabel(offer)}</span>
+          <span aria-label={`${priceLabel(offer, copy.freePrice)} ${offer.intervalDisplay}`}>
+            <span aria-hidden="true" className="text-3xl font-extrabold text-gray-900">{priceLabel(offer, copy.freePrice)}</span>
             {" "}
             <span aria-hidden="true" className="text-base text-gray-500">{offer.intervalDisplay}</span>
           </span>
@@ -300,16 +293,15 @@ export function CurrentPlanCard({ subscription, usage, upgradeCta, onPortalClick
           One date format on the card, the banners' (crochet_patterns-rjg2e). */}
       {subscription.status === "trialing" && subscription.trialEnd && !offer.isFree && !ending ? (
         <p data-testid="first-charge" className="text-sm text-gray-600 mb-6">
-          {`First charge ${priceLabel(offer)} on ${prettyDate(subscription.trialEnd)}`}
+          {copy.firstCharge(priceLabel(offer, copy.freePrice), prettyDate(subscription.trialEnd))}
         </p>
       ) : subscription.currentPeriodEnd && !offer.isFree && subscription.status === "active" && !subscription.cancelAtPeriodEnd ? (
         <p data-testid="next-billing-date" className="text-sm text-gray-600 mb-6">
-          Next billing date: {prettyDate(subscription.currentPeriodEnd)}
+          {copy.nextBilling(prettyDate(subscription.currentPeriodEnd))}
         </p>
       ) : subscription.currentPeriodStart && subscription.currentPeriodEnd && !ending ? (
         <p className="text-sm text-gray-500 mb-6">
-          Billing period: {prettyDate(subscription.currentPeriodStart)} to{" "}
-          {prettyDate(subscription.currentPeriodEnd)}
+          {copy.billingPeriod(prettyDate(subscription.currentPeriodStart), prettyDate(subscription.currentPeriodEnd))}
         </p>
       ) : null}
 
@@ -322,6 +314,7 @@ export function CurrentPlanCard({ subscription, usage, upgradeCta, onPortalClick
                 key={f.key}
                 feature={f}
                 used={u && typeof u.used === "number" ? u.used : null}
+                featureCopy={featureCopy}
               />
             );
           })}

package/src/components/FeatureLabel.tsx

@@ -0,0 +1,18 @@
+import React from "react";
+import type { OfferFeature } from "../types";
+import { featureText, type FeatureCopy } from "../copy";
+
+/**
+ * The text of one feature row. Without an override it is the bare
+ * `<span>{label}</span>` every card always rendered; an override may add a
+ * hint under the label.
+ */
+export function FeatureLabel({ feature, featureCopy, className }: { feature: OfferFeature; featureCopy?: FeatureCopy; className?: string }) {
+  const { label, hint } = featureText(feature, featureCopy);
+  return (
+    <span className={className}>
+      {label}
+      {hint && <span data-testid={`feature-hint-${feature.key}`} className="block text-xs text-gray-400">{hint}</span>}
+    </span>
+  );
+}

package/src/components/IntervalToggle.tsx

@@ -16,6 +16,7 @@ import {
   type OfferTier,
 } from "../utils/tiers";
 import { formatPrice } from "../utils/format";
+import { withBillingCopy, type BillingCopyInput } from "../copy";
 
 export interface IntervalEntry {
   tier: OfferTier;
@@ -38,12 +39,15 @@ export function IntervalToggle({
   interval,
   onChange,
   disabled = false,
+  copy,
 }: {
   interval: BillingInterval;
   onChange: (interval: BillingInterval) => void;
   /** A plan change or checkout is in flight. */
   disabled?: boolean;
+  copy?: BillingCopyInput;
 }) {
+  const words = withBillingCopy(copy);
   const option = (value: BillingInterval, label: string) => {
     const selected = interval === value;
     return (
@@ -65,12 +69,12 @@ export function IntervalToggle({
     <div className="flex justify-center">
       <div
         role="radiogroup"
-        aria-label="Billing interval"
+        aria-label={words.billingInterval}
         data-testid="interval-toggle"
         className="inline-flex items-center gap-1 rounded-full bg-gray-100 p-1"
       >
-        {option("monthly", "Monthly")}
-        {option("annual", "Annual")}
+        {option("monthly", words.monthly)}
+        {option("annual", words.annual)}
       </div>
     </div>
   );

package/src/components/PlanChangeConfirm.tsx

@@ -10,6 +10,7 @@ import React, { useEffect, useRef } from "react";
 import type { ProductOffer } from "../types";
 import type { PlanChangeConfirmState } from "../hooks/usePlanChange";
 import { formatPrice } from "../utils/format";
+import { defaultBillingCopy, withBillingCopy, type BillingCopyInput, type PlanChangeCopy } from "../copy";
 
 export interface PlanChangeConfirmProps {
   state: PlanChangeConfirmState | null;
@@ -17,6 +18,8 @@ export interface PlanChangeConfirmProps {
   error: string | null;
   onConfirm: () => void;
   onCancel: () => void;
+  /** Wording overrides; defaults are the original strings. */
+  copy?: BillingCopyInput;
 }
 
 function formatDay(iso: string | null | undefined): string | null {
@@ -38,91 +41,72 @@ interface Copy {
 }
 
 /** The dialog's words. Exported for tests. */
-export function planChangeCopy(state: PlanChangeConfirmState): Copy {
+export function planChangeCopy(state: PlanChangeConfirmState, copy: PlanChangeCopy = defaultBillingCopy): Copy {
   const { offer, preview, currentName, leavingUnlisted } = state;
-  const current = currentName ?? "your current plan";
+  const current = currentName ?? copy.confirmYourCurrentPlan;
   const date = formatDay(preview?.effectiveAt);
   const mode = preview?.mode ?? null;
 
   if (offer.isFree) {
-    const title = `Downgrade to ${offer.name}?`;
+    const title = copy.confirmDowngradeTitle(offer.name);
+    const action = copy.confirmDowngradeAction(offer.name);
     if (mode === "at_period_end") {
       return {
         title,
         body: [
-          date
-            ? `Your ${current} plan ends on ${date}. You keep everything in it until then, and you won't be charged again.`
-            : `Your ${current} plan ends at the end of this billing period. You keep everything in it until then, and you won't be charged again.`,
-          `After that you're on ${offer.name}, and lose what ${current} includes.`,
+          date ? copy.confirmDowngradeAtDate(current, date) : copy.confirmDowngradeAtPeriodEnd(current),
+          copy.confirmDowngradeAfter(offer.name, current),
         ],
-        action: `Downgrade to ${offer.name}`,
+        action,
       };
     }
     if (leavingUnlisted) {
       return {
         title,
-        body: [
-          `Your ${current} plan ends now, and you lose what it includes.`,
-          `${current} isn't a plan you can buy, so once it ends you can't get it back.`,
-        ],
-        action: `End ${current}`,
+        body: [copy.confirmEndsNow(current), copy.confirmUnlistedGone(current)],
+        action: copy.confirmEndAction(current),
       };
     }
     if (mode === "immediate") {
-      return {
-        title,
-        body: [`Your ${current} plan ends now, and you lose what it includes.`],
-        action: `Downgrade to ${offer.name}`,
-      };
+      return { title, body: [copy.confirmEndsNow(current)], action };
     }
-    return {
-      title,
-      body: [
-        `Your ${current} plan will end. If it is a paid plan you keep it until the end of the period you've paid for.`,
-      ],
-      action: `Downgrade to ${offer.name}`,
-    };
+    return { title, body: [copy.confirmDowngradeGeneric(current)], action };
   }
 
   if (mode === "at_period_end") {
     return {
-      title: `Switch to ${offer.name}?`,
+      title: copy.confirmSwitchTitle(offer.name),
       body: [
         date
-          ? `You keep ${current} until ${date}. Then your plan changes to ${offer.name} at ${recurring(offer)}.`
-          : `You keep ${current} until the end of this billing period. Then your plan changes to ${offer.name} at ${recurring(offer)}.`,
-        "Nothing is charged today.",
+          ? copy.confirmSwitchAtDate(current, offer.name, date, recurring(offer))
+          : copy.confirmSwitchAtPeriodEnd(current, offer.name, recurring(offer)),
+        copy.confirmNothingToday,
       ],
-      action: `Switch to ${offer.name}`,
+      action: copy.confirmSwitchAction(offer.name),
     };
   }
 
   if (!preview) {
     // The preview could not be had: say only what the rules guarantee.
     return {
-      title: `Change to ${offer.name}?`,
-      body: [
-        `${offer.name} is ${recurring(offer)}. Moving to a more expensive plan is charged today for the rest of this billing period (prorated); moving to a cheaper one takes effect when this period ends.`,
-        "There's no free trial when you're already on a paid plan.",
-      ],
-      action: `Change to ${offer.name}`,
+      title: copy.confirmChangeTitle(offer.name),
+      body: [copy.confirmChangeRules(offer.name, recurring(offer)), copy.confirmNoTrial],
+      action: copy.confirmChangeAction(offer.name),
     };
   }
 
   const amount = preview?.amountDue != null ? formatPrice(preview.amountDue, preview.currency.toUpperCase()) : null;
   return {
-    title: `Upgrade to ${offer.name}?`,
+    title: copy.confirmUpgradeTitle(offer.name),
     body: [
-      amount
-        ? `You'll be charged ${amount} today for the rest of this billing period, then ${recurring(offer)}.`
-        : `You'll be charged today for the rest of this billing period (prorated), then ${recurring(offer)}.`,
-      `Your plan changes from ${current} to ${offer.name} now. There's no free trial when you're already on a paid plan.`,
+      amount ? copy.confirmChargedAmount(amount, recurring(offer)) : copy.confirmChargedProrated(recurring(offer)),
+      `${copy.confirmChangesNow(current, offer.name)} ${copy.confirmNoTrial}`,
     ],
-    action: amount ? `Upgrade and pay ${amount}` : `Upgrade to ${offer.name}`,
+    action: amount ? copy.confirmUpgradeAndPay(amount) : copy.confirmUpgradeAction(offer.name),
   };
 }
 
-export function PlanChangeConfirm({ state, confirming, error, onConfirm, onCancel }: PlanChangeConfirmProps) {
+export function PlanChangeConfirm({ state, confirming, error, onConfirm, onCancel, copy: copyOverride }: PlanChangeConfirmProps) {
   const cancelRef = useRef<HTMLButtonElement>(null);
   useEffect(() => {
     if (state) cancelRef.current?.focus();
@@ -137,7 +121,8 @@ export function PlanChangeConfirm({ state, confirming, error, onConfirm, onCance
   }, [state, onCancel]);
 
   if (!state) return null;
-  const copy = planChangeCopy(state);
+  const words = withBillingCopy(copyOverride);
+  const copy = planChangeCopy(state, words);
   const destructive = state.offer.isFree;
 
   return (
@@ -172,7 +157,7 @@ export function PlanChangeConfirm({ state, confirming, error, onConfirm, onCance
             disabled={confirming}
             className="px-4 py-2.5 text-sm font-semibold rounded-xl border border-gray-300 bg-white text-gray-700 hover:bg-gray-50 cursor-pointer disabled:cursor-not-allowed disabled:opacity-60"
           >
-            {destructive ? "Keep my plan" : "Cancel"}
+            {destructive ? words.confirmKeepPlan : words.confirmCancel}
           </button>
           <button
             type="button"
@@ -184,7 +169,7 @@ export function PlanChangeConfirm({ state, confirming, error, onConfirm, onCance
               destructive ? "bg-red-600 hover:bg-red-700" : "bg-blue-600 hover:bg-blue-700"
             }`}
           >
-            {confirming ? "Working…" : copy.action}
+            {confirming ? words.confirmWorking : copy.action}
           </button>
         </div>
       </div>