@burdenoff/website-sdk 2026.1014.1 → 2026.1021.1

package/README.md

@@ -548,15 +548,33 @@ Newsletter subscription component with rate limiting.
 
 ### PricingPage / PricingSection
 
-Dynamic pricing tables with API integration and billing cycle toggle.
+Pricing cards driven by the live billing catalog (`publicPlans`), with a
+billing cycle toggle and a currency picker.
 
 **Props:**
-- `productName` (required): Product name
-- `productId` (required): Product ID for API requests
-- `apiBaseUrl` (required): API base URL
+- `productName`: Product name
+- `productId`: the product **slug** (e.g. `"vibecontrols"`); falls back to `WebSDKConfig.productId`.
+  A product UUID is mapped to its slug (via `ProductProvider`, else `publicProducts`);
+  a UUID no public product owns is refused with an error state, never a blank grid.
 - `appLoginUrl` (required): App login URL for signup
 - `contactUrl`: Contact page URL (default: '/contact')
+- `planMetadata`: per-plan copy keyed by the lowercased catalog name
+  (`"vibecontrols - pro (monthly)"`) or the clean name (`"pro"`)
 - `fallbackFeatures`: Fallback features when API doesn't provide them
+- `defaultCurrency`: ISO code to show first; otherwise the base currency, then the
+  visitor's regional currency (time zone, then browser language) when the catalog sells in it
+- `showCurrencySelector`: show the currency picker (default `true`; only rendered when
+  every plan is priced in more than one currency)
+
+Behaviour:
+- Card names drop the product prefix and billing period
+  (`"VibeControls - Hobby (Monthly)"` → `"Hobby"`); `planMetadata.displayName` wins.
+- An empty or all-inactive catalog renders the error state and logs the product key.
+- A `$0` contact-sales plan (e.g. Enterprise) shows as **Custom** and sorts last.
+- A monthly-only free plan stays visible on the Yearly toggle.
+- The catalog helpers (`cleanPlanDisplayName`, `planPriceIn`, `availablePlanCurrencies`,
+  `resolvePricingProductKey`, `isUuidLike`, `PricingProductKeyError`) are exported so a
+  website can pin its own `planMetadata` keys and tests to the same rules.
 
 ## License
 

package/dist/components/pricing.d.mts

@@ -1,30 +1,68 @@
 import * as react from 'react';
 
 /**
- * Pricing Component
- * GraphQL-powered pricing component with quota-based features and monthly/yearly toggle
+ * Pure helpers that turn the billing catalog (`publicPlans`) into what the
+ * pricing page shows: which product key to query, the display name of a
+ * plan, which currencies a visitor can pick, and the price in that currency.
  *
- * @example
- * ```tsx
- * import { PricingPage, PricingSection } from '@burdenoff/website-sdk/components/pricing'
+ * Kept free of React so every rule here is unit-tested directly
+ * (see `pricing-catalog.test.ts`).
+ */
+/** True when `value` is shaped like a UUID (a product registry id, not a slug). */
+declare function isUuidLike(value: string): boolean;
+/** A product as returned by `publicProduct` / `publicProducts`. */
+interface ProductKeyCandidate {
+    id: string;
+    slug: string;
+}
+/**
+ * Thrown when the pricing page is given a product UUID that no public product
+ * owns. `publicPlans(productId)` matches on the product SLUG (a plan's
+ * `productID` is e.g. `"bigconsole"`), so a registry UUID silently returns an
+ * empty list — the page must refuse it instead of rendering a blank grid.
+ */
+declare class PricingProductKeyError extends Error {
+    constructor(productId: string);
+}
+/**
+ * Resolve the key `publicPlans` expects.
  *
- * // Full page with hero
- * <PricingPage
- *   productName="BigConsole"
- *   productId="bigconsole-123"
- *   appLoginUrl="https://app.bigconsole.com/login"
- *   contactUrl="/contact"
- *   fallbackFeatures={{
- *     basic: ['Up to 5 dashboards', '10 data sources'],
- *     professional: ['Unlimited dashboards', 'API access'],
- *     enterprise: ['Everything in Professional', 'Dedicated support']
- *   }}
- * />
+ * - A slug is returned unchanged (trimmed).
+ * - A UUID is mapped to its product's slug using `candidates` (the product
+ *   from `ProductProvider` and/or the `publicProducts` list).
+ * - A UUID with no matching candidate returns `null`: the caller must look it
+ *   up or fail with {@link PricingProductKeyError}.
+ */
+declare function resolvePricingProductKey(productId: string, candidates: ReadonlyArray<ProductKeyCandidate | null | undefined>): string | null;
+/**
+ * Catalog plan names carry the product and the billing period, e.g.
+ * `"VibeControls - Hobby (Monthly)"`. The card already sits on the product's
+ * own site and the period is chosen by the Monthly/Yearly toggle, so the
+ * visitor sees `"Hobby"`.
  *
- * // Embeddable section
- * <PricingSection {...props} id="pricing" className="bg-muted/30" />
- * ```
+ * Only the FIRST `" - "` separates the product, so `"Acme - Pro - Teams"`
+ * becomes `"Pro - Teams"`. A name that would end up empty is returned as is.
+ */
+declare function cleanPlanDisplayName(name: string): string;
+/** The price-bearing fields of a catalog plan. */
+interface PricedPlan {
+    price: number;
+    currency: string;
+    currencyPrices?: Record<string, number> | null;
+}
+/**
+ * The price of `plan` in `currency`, or `null` when the catalog has no price
+ * for it. A free plan costs 0 in every currency.
+ */
+declare function planPriceIn(plan: PricedPlan, currency: string): number | null;
+/**
+ * The currencies a visitor can switch to: those in which EVERY plan has a
+ * price (free plans count as priced everywhere). A currency missing from a
+ * single paid plan is left out, so switching never blanks a card. Sorted with
+ * the catalog's base currency first, then alphabetically.
  */
+declare function availablePlanCurrencies(plans: ReadonlyArray<PricedPlan>): string[];
+
 interface PlanCard {
     id: string;
     name: string;
@@ -91,6 +129,18 @@ interface PricingProps {
      * Billing interval display text
      */
     billingIntervals?: Record<string, string>;
+    /**
+     * Currency to show first (ISO 4217, e.g. "INR"). When omitted the page shows
+     * the catalog's base currency until the browser reveals the visitor's
+     * region, then switches to that region's currency if the catalog sells in it.
+     */
+    defaultCurrency?: string;
+    /**
+     * Show the currency picker when the catalog prices every plan in more than
+     * one currency.
+     * @default true
+     */
+    showCurrencySelector?: boolean;
     /**
      * Plan metadata (tier info, CTA text, etc.)
      */
@@ -281,4 +331,4 @@ declare function PricingSection(props: PricingProps): react.JSX.Element;
  */
 declare function PricingPage(props: PricingProps): react.JSX.Element;
 
-export { type PlanCard, PricingPage, type PricingProps, PricingSection, resolveEnterprisePlans, splitPlansByAudience, transformFeatureToLabel };
+export { type PlanCard, PricingPage, PricingProductKeyError, type PricingProps, PricingSection, availablePlanCurrencies, cleanPlanDisplayName, isUuidLike, planPriceIn, resolveEnterprisePlans, resolvePricingProductKey, splitPlansByAudience, transformFeatureToLabel };

package/dist/components/pricing.d.ts

@@ -1,30 +1,68 @@
 import * as react from 'react';
 
 /**
- * Pricing Component
- * GraphQL-powered pricing component with quota-based features and monthly/yearly toggle
+ * Pure helpers that turn the billing catalog (`publicPlans`) into what the
+ * pricing page shows: which product key to query, the display name of a
+ * plan, which currencies a visitor can pick, and the price in that currency.
  *
- * @example
- * ```tsx
- * import { PricingPage, PricingSection } from '@burdenoff/website-sdk/components/pricing'
+ * Kept free of React so every rule here is unit-tested directly
+ * (see `pricing-catalog.test.ts`).
+ */
+/** True when `value` is shaped like a UUID (a product registry id, not a slug). */
+declare function isUuidLike(value: string): boolean;
+/** A product as returned by `publicProduct` / `publicProducts`. */
+interface ProductKeyCandidate {
+    id: string;
+    slug: string;
+}
+/**
+ * Thrown when the pricing page is given a product UUID that no public product
+ * owns. `publicPlans(productId)` matches on the product SLUG (a plan's
+ * `productID` is e.g. `"bigconsole"`), so a registry UUID silently returns an
+ * empty list — the page must refuse it instead of rendering a blank grid.
+ */
+declare class PricingProductKeyError extends Error {
+    constructor(productId: string);
+}
+/**
+ * Resolve the key `publicPlans` expects.
  *
- * // Full page with hero
- * <PricingPage
- *   productName="BigConsole"
- *   productId="bigconsole-123"
- *   appLoginUrl="https://app.bigconsole.com/login"
- *   contactUrl="/contact"
- *   fallbackFeatures={{
- *     basic: ['Up to 5 dashboards', '10 data sources'],
- *     professional: ['Unlimited dashboards', 'API access'],
- *     enterprise: ['Everything in Professional', 'Dedicated support']
- *   }}
- * />
+ * - A slug is returned unchanged (trimmed).
+ * - A UUID is mapped to its product's slug using `candidates` (the product
+ *   from `ProductProvider` and/or the `publicProducts` list).
+ * - A UUID with no matching candidate returns `null`: the caller must look it
+ *   up or fail with {@link PricingProductKeyError}.
+ */
+declare function resolvePricingProductKey(productId: string, candidates: ReadonlyArray<ProductKeyCandidate | null | undefined>): string | null;
+/**
+ * Catalog plan names carry the product and the billing period, e.g.
+ * `"VibeControls - Hobby (Monthly)"`. The card already sits on the product's
+ * own site and the period is chosen by the Monthly/Yearly toggle, so the
+ * visitor sees `"Hobby"`.
  *
- * // Embeddable section
- * <PricingSection {...props} id="pricing" className="bg-muted/30" />
- * ```
+ * Only the FIRST `" - "` separates the product, so `"Acme - Pro - Teams"`
+ * becomes `"Pro - Teams"`. A name that would end up empty is returned as is.
+ */
+declare function cleanPlanDisplayName(name: string): string;
+/** The price-bearing fields of a catalog plan. */
+interface PricedPlan {
+    price: number;
+    currency: string;
+    currencyPrices?: Record<string, number> | null;
+}
+/**
+ * The price of `plan` in `currency`, or `null` when the catalog has no price
+ * for it. A free plan costs 0 in every currency.
+ */
+declare function planPriceIn(plan: PricedPlan, currency: string): number | null;
+/**
+ * The currencies a visitor can switch to: those in which EVERY plan has a
+ * price (free plans count as priced everywhere). A currency missing from a
+ * single paid plan is left out, so switching never blanks a card. Sorted with
+ * the catalog's base currency first, then alphabetically.
  */
+declare function availablePlanCurrencies(plans: ReadonlyArray<PricedPlan>): string[];
+
 interface PlanCard {
     id: string;
     name: string;
@@ -91,6 +129,18 @@ interface PricingProps {
      * Billing interval display text
      */
     billingIntervals?: Record<string, string>;
+    /**
+     * Currency to show first (ISO 4217, e.g. "INR"). When omitted the page shows
+     * the catalog's base currency until the browser reveals the visitor's
+     * region, then switches to that region's currency if the catalog sells in it.
+     */
+    defaultCurrency?: string;
+    /**
+     * Show the currency picker when the catalog prices every plan in more than
+     * one currency.
+     * @default true
+     */
+    showCurrencySelector?: boolean;
     /**
      * Plan metadata (tier info, CTA text, etc.)
      */
@@ -281,4 +331,4 @@ declare function PricingSection(props: PricingProps): react.JSX.Element;
  */
 declare function PricingPage(props: PricingProps): react.JSX.Element;
 
-export { type PlanCard, PricingPage, type PricingProps, PricingSection, resolveEnterprisePlans, splitPlansByAudience, transformFeatureToLabel };
+export { type PlanCard, PricingPage, PricingProductKeyError, type PricingProps, PricingSection, availablePlanCurrencies, cleanPlanDisplayName, isUuidLike, planPriceIn, resolveEnterprisePlans, resolvePricingProductKey, splitPlansByAudience, transformFeatureToLabel };