@mmailaender/convex-creem 0.1.0

package/src/react/primitives/TrialLimitBanner.tsx

@@ -0,0 +1,32 @@
+import type { BillingSnapshot } from "../../core/types.js";
+
+export const TrialLimitBanner = ({
+  snapshot,
+  trialEndsAt,
+  className = "",
+}: {
+  snapshot?: BillingSnapshot | null;
+  trialEndsAt?: string | null;
+  className?: string;
+}) => {
+  if (snapshot?.activeCategory !== "trial") {
+    return null;
+  }
+
+  const resolvedTrialEnd =
+    trialEndsAt ??
+    (typeof snapshot.metadata?.trialEnd === "string"
+      ? snapshot.metadata.trialEnd
+      : null);
+
+  return (
+    <div
+      className={`rounded-lg border border-sky-300 bg-sky-50 px-4 py-3 text-sm text-sky-900 dark:border-sky-800 dark:bg-sky-950/40 dark:text-sky-200 ${className}`}
+    >
+      Trial plan active
+      {resolvedTrialEnd
+        ? ` until ${new Date(resolvedTrialEnd).toLocaleDateString()}.`
+        : ". Upgrade before your trial ends to avoid interruptions."}
+    </div>
+  );
+};

package/src/react/shared.ts

@@ -0,0 +1,138 @@
+import type {
+  AvailableAction,
+  BillingSnapshot,
+  UIPlanEntry,
+  RecurringCycle,
+} from "../core/types.js";
+import type { ConnectedProduct } from "./widgets/types.js";
+
+const CYCLE_KEY_ALIASES: Record<RecurringCycle, string[]> = {
+  "every-month": ["every-month", "monthly", "month"],
+  "every-three-months": ["every-three-months", "quarterly", "every-quarter"],
+  "every-six-months": ["every-six-months", "semiannual", "semi-annually"],
+  "every-year": ["every-year", "yearly", "annual"],
+  custom: ["custom"],
+};
+
+/** Format a billing cycle enum value to a human-readable label (e.g. `"every-month"` → `"Monthly"`). */
+export const formatRecurringCycle = (cycle: RecurringCycle) => {
+  if (cycle === "every-month") return "Monthly";
+  if (cycle === "every-three-months") return "Quarterly";
+  if (cycle === "every-six-months") return "Semi-annual";
+  if (cycle === "every-year") return "Yearly";
+  return "Custom";
+};
+
+/** Resolve the Creem product ID for a plan given the selected billing cycle. Handles cycle aliases and partial matches. */
+export const resolveProductIdForPlan = (
+  plan: UIPlanEntry,
+  selectedCycle: RecurringCycle | undefined,
+) => {
+  const productIds = plan.creemProductIds;
+  if (!productIds) {
+    return undefined;
+  }
+
+  const aliases = selectedCycle
+    ? CYCLE_KEY_ALIASES[selectedCycle]
+    : CYCLE_KEY_ALIASES.custom;
+  for (const alias of aliases) {
+    if (productIds[alias]) {
+      return productIds[alias];
+    }
+    const partial = Object.entries(productIds).find(([key]) =>
+      key.toLowerCase().includes(alias),
+    );
+    if (partial) {
+      return partial[1];
+    }
+  }
+
+  return Object.values(productIds)[0];
+};
+
+/** Local variant of `hasBillingAction` for use in shared UI code. */
+export const hasBillingActionLocal = (
+  snapshot: BillingSnapshot,
+  action: AvailableAction,
+) => snapshot.availableActions.includes(action);
+
+/** Format a price amount (in cents) to a localized currency string (e.g. `999` + `"USD"` → `"$9.99"`). */
+export const formatPrice = (amount: number, currency: string): string => {
+  return new Intl.NumberFormat(undefined, {
+    style: "currency",
+    currency,
+    minimumFractionDigits: 0,
+    maximumFractionDigits: 2,
+  }).format(amount / 100);
+};
+
+/** Resolve the formatted price and billing interval for a product by its ID. Returns `null` if not found. */
+export const resolveProductPrice = (
+  productId: string | undefined,
+  products: ConnectedProduct[],
+): { formatted: string; interval?: string } | null => {
+  if (!productId || !products.length) return null;
+  const product = products.find((p) => p.id === productId);
+  if (!product) return null;
+  if (product.price == null || !product.currency) return null;
+  const formatted = formatPrice(product.price, product.currency);
+  return { formatted, interval: product.billingPeriod ?? undefined };
+};
+
+const INTERVAL_LABELS: Record<string, string> = {
+  month: "/mo",
+  "every-month": "/mo",
+  "every-three-months": "/3mo",
+  "every-six-months": "/6mo",
+  year: "/yr",
+  "every-year": "/yr",
+};
+
+/** Format the total price for a seat-based plan (e.g. `"$10/mo × 5 seats"`). Returns `null` if product not found. */
+export const formatSeatPrice = (
+  productId: string | undefined,
+  products: ConnectedProduct[],
+  seats: number,
+): string | null => {
+  const resolved = resolveProductPrice(productId, products);
+  if (!resolved) return null;
+  const suffix = resolved.interval
+    ? (INTERVAL_LABELS[resolved.interval] ?? "")
+    : "";
+  if (seats <= 1) {
+    return `${resolved.formatted}${suffix}`;
+  }
+  return `${resolved.formatted}${suffix} × ${seats} seats`;
+};
+
+/** Format a product's price with its billing interval suffix (e.g. `"$10/mo"`). Returns `null` if product not found. */
+export const formatPriceWithInterval = (
+  productId: string | undefined,
+  products: ConnectedProduct[],
+): string | null => {
+  const resolved = resolveProductPrice(productId, products);
+  if (!resolved) return null;
+  const suffix = resolved.interval
+    ? (INTERVAL_LABELS[resolved.interval] ?? "")
+    : "";
+  return `${resolved.formatted}${suffix}`;
+};
+
+/** Split a price label into main amount, interval suffix, and trailing text (e.g. `"$10/mo × 5 seats"` → `{ main: "$10", suffix: "/mo", tail: "× 5 seats" }`). */
+export const splitPriceLabel = (
+  value: string | null,
+): { main: string; suffix: string | null; tail: string } | null => {
+  if (!value) return null;
+  const match = value.match(/^(.*?)(\/[a-z0-9]+)(.*)$/i);
+  if (!match) return { main: value, suffix: null, tail: "" };
+  return {
+    main: match[1]?.trim() ?? value,
+    suffix: match[2] ?? null,
+    tail: match[3]?.trim() ?? "",
+  };
+};
+
+/** Join CSS class tokens, filtering out falsy values. Lightweight alternative to `clsx`. */
+export const cx = (...tokens: Array<string | undefined | false>) =>
+  tokens.filter(Boolean).join(" ");

package/src/react/widgets/BillingPortal.tsx

@@ -0,0 +1,56 @@
+import { useState, type PropsWithChildren } from "react";
+import { useQuery, useConvex } from "convex/react";
+import { CustomerPortalButton } from "../primitives/CustomerPortalButton.js";
+import type {
+  BillingPermissions,
+  ConnectedBillingApi,
+  ConnectedBillingModel,
+} from "./types.js";
+
+export const BillingPortal = ({
+  api,
+  permissions,
+  className = "",
+  children,
+}: PropsWithChildren<{
+  api: ConnectedBillingApi;
+  permissions?: BillingPermissions;
+  class?: string;
+  className?: string;
+}>) => {
+  const canAccess = permissions?.canAccessPortal !== false;
+
+  const client = useConvex();
+
+  const billingUiModelRef = api.uiModel;
+  const portalUrlRef = api.customers?.portalUrl;
+
+  const modelRaw = useQuery(billingUiModelRef, {});
+  const model = modelRaw as ConnectedBillingModel | undefined;
+  const hasCreemCustomer = model?.hasCreemCustomer ?? false;
+
+  const [isLoading, setIsLoading] = useState(false);
+
+  const openPortal = async () => {
+    if (!portalUrlRef) return;
+    setIsLoading(true);
+    try {
+      const { url } = await client.action(portalUrlRef, {});
+      window.open(url, "_blank", "noopener,noreferrer");
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  if (!portalUrlRef || !hasCreemCustomer || !canAccess) return null;
+
+  return (
+    <CustomerPortalButton
+      disabled={isLoading}
+      onOpenPortal={openPortal}
+      className={className}
+    >
+      {children ?? "Manage billing"}
+    </CustomerPortalButton>
+  );
+};

package/src/react/widgets/ProductItem.tsx

@@ -0,0 +1,26 @@
+import { useContext, useEffect } from "react";
+import { ProductGroupContext } from "./productGroupContext.js";
+import type { ProductType } from "./types.js";
+
+export const ProductItem = ({
+  productId,
+  type,
+  title,
+  description,
+}: {
+  productId: string;
+  type: ProductType;
+  title?: string;
+  description?: string;
+}) => {
+  const rootContext = useContext(ProductGroupContext);
+
+  useEffect(() => {
+    if (!rootContext) return;
+    const registration = { productId, type, title, description };
+    const unregister = rootContext.registerItem(registration);
+    return unregister;
+  }, [rootContext, productId, type, title, description]);
+
+  return null;
+};

package/src/react/widgets/ProductRoot.tsx

@@ -0,0 +1,441 @@
+import {
+  useState,
+  useCallback,
+  useMemo,
+  useEffect,
+  useRef,
+  type PropsWithChildren,
+} from "react";
+import { useQuery, useConvex } from "convex/react";
+
+import { CheckoutButton } from "../primitives/CheckoutButton.js";
+import { formatPriceWithInterval, splitPriceLabel } from "../shared.js";
+import { ProductGroupContext } from "./productGroupContext.js";
+import { renderMarkdown } from "../../core/markdown.js";
+import { pendingCheckout } from "../../core/pendingCheckout.js";
+
+import type {
+  BillingPermissions,
+  CheckoutIntent,
+  ConnectedBillingApi,
+  ConnectedBillingModel,
+  ProductItemRegistration,
+  Transition,
+} from "./types.js";
+
+export const ProductRoot = ({
+  api,
+  permissions,
+  transition = [],
+  className = "",
+  layout = "default",
+  styleVariant = "legacy",
+  showImages = false,
+  pricingCtaVariant = "faded",
+  successUrl,
+  onBeforeCheckout,
+  children,
+}: PropsWithChildren<{
+  api: ConnectedBillingApi;
+  permissions?: BillingPermissions;
+  transition?: Transition[];
+  class?: string;
+  className?: string;
+  layout?: "default" | "single";
+  styleVariant?: "legacy" | "pricing";
+  showImages?: boolean;
+  pricingCtaVariant?: "filled" | "faded";
+  successUrl?: string;
+  onBeforeCheckout?: (intent: CheckoutIntent) => Promise<boolean> | boolean;
+}>) => {
+  const client = useConvex();
+
+  const billingUiModelRef = api.uiModel;
+  const checkoutLinkRef = api.checkouts.create;
+
+  const modelRaw = useQuery(billingUiModelRef, {});
+  const model = (modelRaw ?? null) as ConnectedBillingModel | null;
+
+  const [registeredItems, setRegisteredItems] = useState<
+    ProductItemRegistration[]
+  >([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const contextValue = useMemo(
+    () => ({
+      registerItem: (item: ProductItemRegistration) => {
+        setRegisteredItems((prev) => [
+          ...prev.filter((c) => c.productId !== item.productId),
+          item,
+        ]);
+        return () => {
+          setRegisteredItems((prev) =>
+            prev.filter((c) => c.productId !== item.productId),
+          );
+        };
+      },
+    }),
+    [],
+  );
+
+  const canCheckout =
+    !model?.user && onBeforeCheckout != null
+      ? true
+      : permissions?.canCheckout !== false;
+  const allProducts = useMemo(
+    () => model?.allProducts ?? [],
+    [model?.allProducts],
+  );
+  const rawOwnedProductIds = useMemo(
+    () => model?.ownedProductIds ?? [],
+    [model?.ownedProductIds],
+  );
+
+  // Pending checkout resume after auth
+  const pendingCheckoutHandled = useRef(false);
+  useEffect(() => {
+    if (!model?.user || pendingCheckoutHandled.current) return;
+    pendingCheckoutHandled.current = true;
+    const pending = pendingCheckout.load();
+    if (!pending) return;
+    if ((model.ownedProductIds ?? []).includes(pending.productId)) {
+      pendingCheckout.clear();
+      return;
+    }
+    startCheckout(pending.productId);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [model?.user]);
+
+  // Resolve effective ownership by applying transition rules
+  const effectiveOwnedProductIds = useMemo(() => {
+    const effective = new Set(rawOwnedProductIds);
+    for (const rule of transition) {
+      if (rule.kind === "via_product" && effective.has(rule.viaProductId)) {
+        effective.add(rule.to);
+        effective.delete(rule.from);
+      }
+    }
+    return [...effective];
+  }, [rawOwnedProductIds, transition]);
+
+  const activeOwnedProductId =
+    registeredItems.find((item) =>
+      effectiveOwnedProductIds.includes(item.productId),
+    )?.productId ?? null;
+
+  const isLowerTierThan = useCallback(
+    (productId: string, targetId: string): boolean => {
+      const visited = new Set<string>();
+      const queue = [productId];
+      while (queue.length > 0) {
+        const current = queue.shift()!;
+        if (visited.has(current)) continue;
+        visited.add(current);
+        for (const rule of transition) {
+          if (rule.from === current) {
+            if (rule.to === targetId) return true;
+            queue.push(rule.to);
+          }
+        }
+      }
+      return false;
+    },
+    [transition],
+  );
+
+  const resolveCheckoutProductId = useCallback(
+    (toProductId: string) => {
+      if (!activeOwnedProductId) {
+        return toProductId;
+      }
+      const rule = transition.find(
+        (r) => r.from === activeOwnedProductId && r.to === toProductId,
+      );
+      if (!rule) {
+        return null;
+      }
+      if (rule.kind === "via_product") {
+        return rule.viaProductId;
+      }
+      return toProductId;
+    },
+    [activeOwnedProductId, transition],
+  );
+
+  const getFallbackSuccessUrl = (): string | undefined => {
+    if (typeof window === "undefined") return undefined;
+    return `${window.location.origin}${window.location.pathname}`;
+  };
+
+  const getPreferredTheme = (): "light" | "dark" => {
+    if (typeof window === "undefined") return "light";
+    return window.matchMedia("(prefers-color-scheme: dark)").matches
+      ? "dark"
+      : "light";
+  };
+
+  const startCheckout = useCallback(
+    async (checkoutProductId: string) => {
+      if (onBeforeCheckout) {
+        const proceed = await onBeforeCheckout({
+          productId: checkoutProductId,
+        });
+        if (!proceed) return;
+      }
+      setIsLoading(true);
+      setError(null);
+      try {
+        const { url } = await client.action(checkoutLinkRef, {
+          productId: checkoutProductId,
+          ...(successUrl ? { successUrl } : {}),
+          fallbackSuccessUrl: getFallbackSuccessUrl(),
+          theme: getPreferredTheme(),
+        });
+        window.addEventListener(
+          "beforeunload",
+          (e) => {
+            e.stopImmediatePropagation();
+          },
+          { capture: true, once: true },
+        );
+        window.location.href = url;
+      } catch (checkoutError) {
+        setError(
+          checkoutError instanceof Error
+            ? checkoutError.message
+            : "Checkout failed",
+        );
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [client, checkoutLinkRef, successUrl, onBeforeCheckout],
+  );
+
+  return (
+    <ProductGroupContext.Provider value={contextValue}>
+      <div className="hidden" aria-hidden="true">
+        {children}
+      </div>
+
+      <section
+        className={`${styleVariant === "pricing" ? "space-y-0" : "space-y-3"} ${className}`}
+      >
+        {error && <p className="text-sm text-red-600">{error}</p>}
+
+        <div
+          className={
+            styleVariant === "pricing"
+              ? layout === "single"
+                ? "flex justify-center"
+                : "grid grid-cols-1 gap-1 lg:grid-cols-2"
+              : `flex gap-3 ${layout === "single" ? "justify-center" : "flex-wrap items-center"}`
+          }
+        >
+          {registeredItems.map((item) => {
+            const isOwned = effectiveOwnedProductIds.includes(item.productId);
+            const isIncluded =
+              !isOwned &&
+              activeOwnedProductId != null &&
+              isLowerTierThan(item.productId, activeOwnedProductId);
+            const checkoutProductId = resolveCheckoutProductId(item.productId);
+            const matchedProduct = allProducts.find(
+              (p) => p.id === item.productId,
+            );
+            const resolvedTitle =
+              item.title ?? matchedProduct?.name ?? item.productId;
+            const resolvedDescription =
+              item.description ?? matchedProduct?.description;
+            const resolvedImageUrl = matchedProduct?.imageUrl;
+            const resolvedPrice = formatPriceWithInterval(
+              item.productId,
+              allProducts,
+            );
+            const splitPrice = splitPriceLabel(resolvedPrice);
+            const descriptionLines = (resolvedDescription ?? "")
+              .split(/\r?\n/)
+              .map((line) => line.trim())
+              .filter(Boolean)
+              .map((line) => line.replace(/^(?:[-*]\s+|[✔✓]\s*)/, "").trim())
+              .filter(Boolean);
+
+            if (styleVariant === "pricing") {
+              return (
+                <article
+                  key={item.productId}
+                  className={`w-full ${layout === "single" ? "max-w-[680px]" : "max-w-none"} rounded-2xl bg-surface-base ${isIncluded ? "opacity-60" : ""}`}
+                >
+                  {showImages && resolvedImageUrl && (
+                    <div className="p-1">
+                      <img
+                        src={resolvedImageUrl}
+                        alt={resolvedTitle}
+                        className="aspect-[16/9] w-full rounded-xl object-cover"
+                        loading="lazy"
+                      />
+                    </div>
+                  )}
+
+                  <div className="px-6 pb-6 pt-6">
+                    <div className="mb-3 flex min-h-6 items-center justify-between gap-2">
+                      <h3 className="title-s text-foreground-default">
+                        {resolvedTitle}
+                      </h3>
+                      {isOwned ? (
+                        <span className="badge-faded-sm">Owned</span>
+                      ) : isIncluded ? (
+                        <span className="badge-faded-sm">Included</span>
+                      ) : null}
+                    </div>
+
+                    {splitPrice && (
+                      <div className="flex items-baseline gap-1">
+                        <span className="heading-s text-foreground-default">
+                          {splitPrice.main}
+                        </span>
+                        {splitPrice.suffix && (
+                          <span className="title-s text-foreground-placeholder">
+                            {splitPrice.suffix}
+                          </span>
+                        )}
+                        {splitPrice.tail && (
+                          <span className="title-s text-foreground-placeholder">
+                            {splitPrice.tail}
+                          </span>
+                        )}
+                      </div>
+                    )}
+
+                    <div className="mb-4 mt-6 flex min-h-8 items-start">
+                      {checkoutProductId && !isOwned && !isIncluded ? (
+                        <CheckoutButton
+                          productId={checkoutProductId}
+                          disabled={isLoading || !canCheckout}
+                          onCheckout={() => startCheckout(checkoutProductId)}
+                          className={`${pricingCtaVariant === "filled" ? "button-filled" : "button-faded"} w-full`}
+                        >
+                          {activeOwnedProductId ? "Upgrade" : "Buy now"}
+                        </CheckoutButton>
+                      ) : !isOwned && !isIncluded ? (
+                        <CheckoutButton
+                          productId={item.productId}
+                          disabled={isLoading || !canCheckout}
+                          onCheckout={() => startCheckout(item.productId)}
+                          className={`${pricingCtaVariant === "filled" ? "button-filled" : "button-faded"} w-full`}
+                        >
+                          Buy now
+                        </CheckoutButton>
+                      ) : null}
+                    </div>
+
+                    {descriptionLines.length > 0 && (
+                      <div className="w-full pt-4">
+                        <p className="label-m mb-4 font-semibold text-foreground-default">
+                          What&apos;s included:
+                        </p>
+                        <ul className="space-y-2">
+                          {descriptionLines.map((feature) => (
+                            <li
+                              key={feature}
+                              className="flex items-center gap-2"
+                            >
+                              <span className="inline-flex h-5 w-5 shrink-0 items-center justify-center text-foreground-muted">
+                                <svg
+                                  aria-hidden="true"
+                                  viewBox="0 0 24 24"
+                                  fill="none"
+                                  className="h-4 w-4"
+                                >
+                                  <path
+                                    d="M20 6L9 17L4 12"
+                                    stroke="currentColor"
+                                    strokeWidth="2.5"
+                                    strokeLinecap="round"
+                                    strokeLinejoin="round"
+                                  />
+                                </svg>
+                              </span>
+                              <span className="body-m text-foreground-default">
+                                {feature}
+                              </span>
+                            </li>
+                          ))}
+                        </ul>
+                      </div>
+                    )}
+                  </div>
+                </article>
+              );
+            }
+
+            // Legacy style variant
+            return (
+              <article
+                key={item.productId}
+                className={`max-w-sm rounded-xl border p-4 shadow-sm ${
+                  isIncluded
+                    ? "border-zinc-100 bg-zinc-50 opacity-60 dark:border-zinc-800 dark:bg-zinc-900"
+                    : "border-zinc-200 bg-zinc-50 dark:border-zinc-800 dark:bg-zinc-950"
+                }`}
+              >
+                <h3 className="text-base font-semibold text-zinc-900 dark:text-zinc-100">
+                  {resolvedTitle}
+                </h3>
+
+                {resolvedPrice && (
+                  <p
+                    className={`mt-2 text-2xl font-bold ${
+                      isIncluded
+                        ? "text-zinc-400 dark:text-zinc-500"
+                        : "text-zinc-900 dark:text-zinc-100"
+                    }`}
+                  >
+                    {resolvedPrice}
+                  </p>
+                )}
+
+                <div className="mt-4">
+                  {isOwned ? (
+                    <span className="inline-flex rounded-md bg-emerald-100 px-3 py-2 text-sm font-medium text-emerald-700">
+                      Owned
+                    </span>
+                  ) : isIncluded ? (
+                    <span className="inline-flex rounded-md bg-zinc-100 px-3 py-2 text-sm font-medium text-zinc-500 dark:bg-zinc-800 dark:text-zinc-400">
+                      Included
+                    </span>
+                  ) : checkoutProductId ? (
+                    <CheckoutButton
+                      productId={checkoutProductId}
+                      disabled={isLoading || !canCheckout}
+                      onCheckout={() => startCheckout(checkoutProductId)}
+                    >
+                      {activeOwnedProductId ? "Upgrade" : "Buy now"}
+                    </CheckoutButton>
+                  ) : (
+                    <CheckoutButton
+                      productId={item.productId}
+                      disabled={isLoading || !canCheckout}
+                      onCheckout={() => startCheckout(item.productId)}
+                    >
+                      Buy now
+                    </CheckoutButton>
+                  )}
+                </div>
+
+                {resolvedDescription && (
+                  <div
+                    className="creem-prose mt-4 text-sm text-zinc-600 dark:text-zinc-300"
+                    dangerouslySetInnerHTML={{
+                      __html: renderMarkdown(resolvedDescription),
+                    }}
+                  />
+                )}
+              </article>
+            );
+          })}
+        </div>
+      </section>
+    </ProductGroupContext.Provider>
+  );
+};