@umituz/web-payment 0.0.0-stage → 1.0.1

package/src/presentation/portal/create-portal-client.ts

@@ -0,0 +1,202 @@
+
+import type { BillingAdapter } from '../../domain/interfaces';
+import type {
+  BillingCycle,
+  OrderItem,
+  SubscriptionStatus as CoreSubscriptionStatus,
+} from '../../domain/entities';
+import type { Product } from '../../domain/entities';
+import { WindowNavigationStrategy } from '../navigation/navigation.strategy';
+import type { NavigationStrategy } from '../navigation/navigation.strategy';
+import { transformProducts } from './utils';
+import type { BillingApiClient } from './hooks';
+import type {
+  BillingSummary,
+  Invoice,
+  PaymentMethod,
+  PlanTier,
+  Subscription,
+} from './types';
+import { CURRENCY, INVOICE_STATUS, SUBSCRIPTION_STATUS } from './constants';
+
+export interface PortalClientOptions {
+  adapter: BillingAdapter;
+  products: Product[];
+  userId?: string;
+  defaultCycle?: BillingCycle;
+  successUrl?: string;
+  navigation?: NavigationStrategy;
+}
+
+export interface PortalClient extends BillingApiClient {
+  selectPlan: (productId: string, cycle?: BillingCycle) => Promise<void>;
+  openPortal: () => Promise<string>;
+}
+
+function portalStatus(core: CoreSubscriptionStatus['subscriptionStatus']): Subscription['status'] {
+  switch (core) {
+    case 'active':
+      return SUBSCRIPTION_STATUS.ACTIVE;
+    case 'trialing':
+      return SUBSCRIPTION_STATUS.TRIALING;
+    case 'past_due':
+      return SUBSCRIPTION_STATUS.PAST_DUE;
+    case 'unpaid':
+      return SUBSCRIPTION_STATUS.UNPAID;
+    case 'incomplete':
+    case 'incomplete_expired':
+      return SUBSCRIPTION_STATUS.INCOMPLETE;
+    case 'revoked':
+      return SUBSCRIPTION_STATUS.REVOKED;
+    default:
+      return SUBSCRIPTION_STATUS.CANCELED;
+  }
+}
+
+function freeTier(planKey: string): PlanTier {
+  return {
+    id: planKey,
+    name: planKey === 'free' ? 'Free' : planKey,
+    description: '',
+    monthlyPrice: 0,
+    yearlyPrice: 0,
+    currency: CURRENCY.USD,
+    features: [],
+  };
+}
+
+function orderToInvoice(order: OrderItem): Invoice {
+  const paid = order.paid || order.status === 'paid';
+  const date = order.createdAt.length >= 10 ? order.createdAt.slice(0, 10) : order.createdAt;
+  return {
+    id: order.id,
+    number: order.id.slice(-8).toUpperCase(),
+    amount: order.amount,
+    currency: order.currency.toUpperCase(),
+    status: paid ? INVOICE_STATUS.PAID : INVOICE_STATUS.OPEN,
+    date,
+    dueDate: date,
+    ...(paid ? { paidAt: date } : {}),
+    ...(order.invoiceUrl ? { invoiceUrl: order.invoiceUrl } : {}),
+    items: [
+      {
+        description: order.productName ?? order.itemType ?? 'Subscription',
+        quantity: 1,
+        unitPrice: order.amount,
+        amount: order.amount,
+      },
+    ],
+  };
+}
+
+const HOSTED_PORTAL_METHOD: PaymentMethod = {
+  id: 'hosted-portal',
+  type: 'card',
+  isDefault: true,
+  createdAt: new Date(0).toISOString(),
+  card: { last4: '••••', brand: 'Managed in the billing portal', expiryMonth: 0, expiryYear: 0 },
+};
+
+export function createPortalClient(options: PortalClientOptions): PortalClient {
+  const { adapter, products, userId, successUrl } = options;
+  const defaultCycle: BillingCycle = options.defaultCycle ?? 'monthly';
+  const navigation: NavigationStrategy = options.navigation ?? new WindowNavigationStrategy();
+  const tiers = transformProducts(products);
+
+  const productByPlanKey = new Map<string, Product>();
+  for (const product of products) {
+    const key = product.metadata?.planId;
+    if (typeof key === 'string' && key.length > 0) productByPlanKey.set(key, product);
+  }
+
+  async function checkout(productId: string, cycle?: BillingCycle): Promise<void> {
+    const { url } = await adapter.createCheckout({
+      productId,
+      billingCycle: cycle ?? defaultCycle,
+      ...(successUrl ? { successUrl } : {}),
+      ...(userId ? { userId } : {}),
+    });
+    navigation.redirect(url);
+  }
+
+  async function openPortal(): Promise<string> {
+    const url = await adapter.getPortalUrl(userId ?? '');
+    navigation.redirect(url);
+    return url;
+  }
+
+  return {
+    async loadBilling(): Promise<BillingSummary> {
+      const [status, history] = await Promise.all([
+        adapter.getStatus(userId ?? ''),
+        adapter.getBillingHistory(userId ?? ''),
+      ]);
+
+      const tierById = tiers.find((tier) => tier.id === status.plan);
+      const product = productByPlanKey.get(status.plan);
+      const tier =
+        tierById ??
+        (product ? tiers.find((t) => t.id === product.id) : undefined) ??
+        freeTier(status.plan);
+
+      const subscription: Subscription = {
+        id: status.subscriptionId ?? 'none',
+        planId: status.plan,
+        plan: tier,
+        status: portalStatus(status.subscriptionStatus),
+        cycle: status.billingCycle ?? defaultCycle,
+        currentPeriodStart: '',
+        currentPeriodEnd: status.currentPeriodEnd ?? '',
+        ...(status.cancelAtPeriodEnd !== undefined ? { cancelAtPeriodEnd: status.cancelAtPeriodEnd } : {}),
+      };
+
+      const price =
+        subscription.cycle === 'yearly' ? tier.yearlyPrice : tier.monthlyPrice;
+
+      return {
+        subscription,
+        paymentMethods: [],
+        usage: [],
+        recentInvoices: history.map(orderToInvoice),
+        ...(subscription.status === SUBSCRIPTION_STATUS.ACTIVE && subscription.currentPeriodEnd
+          ? {
+              upcomingInvoice: {
+                amount: price,
+                currency: tier.currency,
+                date: subscription.currentPeriodEnd,
+              },
+            }
+          : {}),
+      };
+    },
+
+    updatePlan: (productId: string) => checkout(productId),
+    selectPlan: (productId: string, cycle?: BillingCycle) => checkout(productId, cycle),
+
+    updateCycle: async (cycle: BillingCycle) => {
+      const status = await adapter.getStatus(userId ?? '');
+      const product = productByPlanKey.get(status.plan) ?? tiers.find((t) => t.id === status.plan);
+      if (!product) throw new Error('Cannot switch cycle without a purchasable plan catalog');
+      await checkout(product.id, cycle);
+    },
+
+    cancelSubscription: async () => {
+      await adapter.cancelSubscription();
+    },
+
+    addPaymentMethod: async () => {
+      await openPortal();
+      return HOSTED_PORTAL_METHOD;
+    },
+    removePaymentMethod: () => openPortal().then(() => undefined),
+    setDefaultPaymentMethod: () => openPortal().then(() => undefined),
+
+    getInvoiceUrl: async (invoiceId: string) => {
+      const history = await adapter.getBillingHistory(userId ?? '');
+      const order = history.find((item) => item.id === invoiceId);
+      return order?.invoiceUrl ?? (await openPortal());
+    },
+
+    openPortal,
+  };
+}

package/src/presentation/portal/hooks/index.ts

@@ -0,0 +1,3 @@
+
+export { useBilling, createStubBillingApiClient } from './useBilling';
+export type { BillingApiClient, UseBillingOptions, UseBillingReturn } from './useBilling';

package/src/presentation/portal/hooks/useBilling.ts

@@ -0,0 +1,240 @@
+
+import { useState, useCallback, useMemo } from 'react';
+import type {
+  BillingSummary,
+  BillingCycle,
+  PaymentMethod,
+  PaymentMethodInput,
+  Invoice,
+} from '../types';
+import { DEFAULT_BILLING_CONFIG } from '../constants';
+
+export type { Invoice };
+
+export interface BillingApiClient {
+  loadBilling: () => Promise<BillingSummary>;
+  updatePlan: (planId: string) => Promise<void>;
+  cancelSubscription: () => Promise<void>;
+  updateCycle: (cycle: BillingCycle) => Promise<void>;
+  addPaymentMethod: (input: PaymentMethodInput) => Promise<PaymentMethod>;
+  removePaymentMethod: (methodId: string) => Promise<void>;
+  setDefaultPaymentMethod: (methodId: string) => Promise<void>;
+  getInvoiceUrl: (invoiceId: string) => Promise<string>;
+}
+
+export interface UseBillingOptions {
+  initialData?: BillingSummary;
+  apiClient: BillingApiClient;
+}
+
+export interface UseBillingReturn {
+  billing: BillingSummary | null;
+  isLoading: boolean;
+  error: string | null;
+  loadBilling: () => Promise<void>;
+  updatePlan: (planId: string) => Promise<void>;
+  cancelSubscription: () => Promise<void>;
+  updateCycle: (cycle: BillingCycle) => Promise<void>;
+  addPaymentMethod: (input: PaymentMethodInput) => Promise<PaymentMethod | null>;
+  removePaymentMethod: (methodId: string) => Promise<void>;
+  setDefaultPaymentMethod: (methodId: string) => Promise<void>;
+  getInvoiceUrl: (invoiceId: string) => Promise<string | null>;
+}
+
+const toErrorMessage = (err: unknown, fallback: string): string => {
+  if (err instanceof Error && err.message) return err.message;
+  return fallback;
+};
+
+const executeBillingAction = async <T>(
+  setIsLoading: (loading: boolean) => void,
+  setError: (message: string | null) => void,
+  fallbackMessage: string,
+  action: () => Promise<T>,
+): Promise<T | null> => {
+  setIsLoading(true);
+  setError(null);
+  try {
+    return await action();
+  } catch (err) {
+    setError(toErrorMessage(err, fallbackMessage));
+    return null;
+  } finally {
+    setIsLoading(false);
+  }
+};
+
+export function useBilling(options: UseBillingOptions): UseBillingReturn {
+  const { initialData, apiClient } = options;
+
+  const [billing, setBilling] = useState<BillingSummary | null>(initialData ?? null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const loadBilling = useCallback(async () => {
+    const result = await executeBillingAction(setIsLoading, setError, 'Failed to load billing', () =>
+      apiClient.loadBilling(),
+    );
+    if (result) setBilling(result);
+  }, [apiClient]);
+
+  const updatePlan = useCallback(
+    async (planId: string) => {
+      await executeBillingAction(setIsLoading, setError, 'Failed to update plan', () =>
+        apiClient.updatePlan(planId).then(() => {
+          setBilling((prev) =>
+            prev
+              ? { ...prev, subscription: { ...prev.subscription, planId } }
+              : prev,
+          );
+        }),
+      );
+    },
+    [apiClient],
+  );
+
+  const cancelSubscription = useCallback(async () => {
+    await executeBillingAction(setIsLoading, setError, 'Failed to cancel subscription', () =>
+      apiClient.cancelSubscription().then(() => {
+        setBilling((prev) =>
+          prev
+            ? {
+                ...prev,
+                subscription: {
+                  ...prev.subscription,
+                  status: 'canceled',
+                  cancelAtPeriodEnd: true,
+                },
+              }
+            : prev,
+        );
+      }),
+    );
+  }, [apiClient]);
+
+  const updateCycle = useCallback(
+    async (cycle: BillingCycle) => {
+      await executeBillingAction(setIsLoading, setError, 'Failed to update cycle', () =>
+        apiClient.updateCycle(cycle).then(() => {
+          setBilling((prev) =>
+            prev
+              ? { ...prev, subscription: { ...prev.subscription, cycle } }
+              : prev,
+          );
+        }),
+      );
+    },
+    [apiClient],
+  );
+
+  const addPaymentMethod = useCallback(
+    async (input: PaymentMethodInput): Promise<PaymentMethod | null> => {
+      return executeBillingAction(setIsLoading, setError, 'Failed to add payment method', () =>
+        apiClient.addPaymentMethod(input).then((method) => {
+          setBilling((prev) =>
+            prev ? { ...prev, paymentMethods: [...prev.paymentMethods, method] } : prev,
+          );
+          return method;
+        }),
+      );
+    },
+    [apiClient],
+  );
+
+  const removePaymentMethod = useCallback(
+    async (methodId: string) => {
+      await executeBillingAction(setIsLoading, setError, 'Failed to remove payment method', () =>
+        apiClient.removePaymentMethod(methodId).then(() => {
+          setBilling((prev) =>
+            prev
+              ? {
+                  ...prev,
+                  paymentMethods: prev.paymentMethods.filter((pm) => pm.id !== methodId),
+                }
+              : prev,
+          );
+        }),
+      );
+    },
+    [apiClient],
+  );
+
+  const setDefaultPaymentMethod = useCallback(
+    async (methodId: string) => {
+      await executeBillingAction(setIsLoading, setError, 'Failed to set default payment method', () =>
+        apiClient.setDefaultPaymentMethod(methodId).then(() => {
+          setBilling((prev) => {
+            if (!prev) return prev;
+            const methods = prev.paymentMethods.map((pm) => ({
+              ...pm,
+              isDefault: pm.id === methodId,
+            }));
+            const defaultPaymentMethod = methods.find((pm) => pm.id === methodId);
+            return { ...prev, paymentMethods: methods, defaultPaymentMethod };
+          });
+        }),
+      );
+    },
+    [apiClient],
+  );
+
+  const getInvoiceUrl = useCallback(
+    async (invoiceId: string): Promise<string | null> => {
+      const result = await executeBillingAction(
+        setIsLoading,
+        setError,
+        'Failed to get invoice URL',
+        () => apiClient.getInvoiceUrl(invoiceId),
+      );
+      return result;
+    },
+    [apiClient],
+  );
+
+  return useMemo(
+    () => ({
+      billing,
+      isLoading,
+      error,
+      loadBilling,
+      updatePlan,
+      cancelSubscription,
+      updateCycle,
+      addPaymentMethod,
+      removePaymentMethod,
+      setDefaultPaymentMethod,
+      getInvoiceUrl,
+    }),
+    [
+      billing,
+      isLoading,
+      error,
+      loadBilling,
+      updatePlan,
+      cancelSubscription,
+      updateCycle,
+      addPaymentMethod,
+      removePaymentMethod,
+      setDefaultPaymentMethod,
+      getInvoiceUrl,
+    ],
+  );
+}
+
+export const createStubBillingApiClient = (
+  overrides?: Partial<BillingApiClient>,
+): BillingApiClient => {
+  const notConfigured: BillingApiClient = {
+    loadBilling: () => Promise.reject(new Error('BillingApiClient not configured')),
+    updatePlan: () => Promise.reject(new Error('BillingApiClient not configured')),
+    cancelSubscription: () => Promise.reject(new Error('BillingApiClient not configured')),
+    updateCycle: () => Promise.reject(new Error('BillingApiClient not configured')),
+    addPaymentMethod: () => Promise.reject(new Error('BillingApiClient not configured')),
+    removePaymentMethod: () => Promise.reject(new Error('BillingApiClient not configured')),
+    setDefaultPaymentMethod: () => Promise.reject(new Error('BillingApiClient not configured')),
+    getInvoiceUrl: () => Promise.reject(new Error('BillingApiClient not configured')),
+  };
+  return { ...notConfigured, ...overrides };
+};
+
+export { DEFAULT_BILLING_CONFIG };

package/src/presentation/portal/index.ts

@@ -0,0 +1,97 @@
+
+export {
+  BillingPortal,
+  BillingLayout,
+  BillingPage,
+  PlanComparison,
+  PaymentMethodsList,
+  InvoiceCard,
+  UsageCard,
+  PortalButton,
+  PortalSpinner,
+  RADIO_GROUP_NAME,
+} from './components';
+export type {
+  PortalButtonProps,
+  PortalButtonVariant,
+  PortalButtonSize,
+} from './components';
+
+export { useBilling, createStubBillingApiClient } from './hooks';
+export type { BillingApiClient, UseBillingOptions, UseBillingReturn } from './hooks';
+
+export {
+  DEFAULT_BILLING_LABELS,
+  BillingLabelsProvider,
+  useBillingLabels,
+  mergeLabels,
+  formatLabel,
+} from './labels';
+export type { BillingLabels, BillingLabelsOverrides } from './labels';
+
+export {
+  formatNumber,
+  formatPrice,
+  calculateDiscount,
+  calculateProratedAmount,
+  getPlanPrice,
+  calculateUsagePercentage,
+  isNearLimit,
+  getStatusTone,
+  getStatusLabel,
+  getInvoiceStatusTone,
+  getInvoiceStatusLabel,
+  formatCardNumber,
+  formatExpiry,
+  getDaysRemaining,
+  isTrialExpiringSoon,
+  getNextBillingDate,
+  groupInvoicesByStatus,
+  calculateInvoiceTotal,
+  sortInvoicesByDate,
+  formatFeature,
+  isPopularPlan,
+  getTrialDaysText,
+  transformProductToPlan,
+  transformProducts,
+} from './utils';
+
+export type {
+  BillingCycle,
+  SubscriptionStatus,
+  PlanType,
+  Currency,
+  PlanTier,
+  Subscription,
+  PaymentMethodType,
+  PaymentMethod,
+  PaymentMethodInput,
+  InvoiceStatus,
+  InvoiceItem,
+  Invoice,
+  UsageMetric,
+  BillingSummary,
+  PlanComparisonProps,
+  PaymentMethodsListProps,
+  InvoiceCardProps,
+  UsageCardProps,
+  BillingPortalProps,
+  BillingTabId,
+  BillingLayoutProps,
+  BillingConfig,
+  BillingPageProps,
+} from './types';
+
+export {
+  SUBSCRIPTION_STATUS,
+  INVOICE_STATUS,
+  CURRENCY,
+  PLAN_TYPE,
+  DEFAULT_BILLING_CONFIG,
+} from './constants';
+export { BILLING_CYCLE } from './types';
+
+export { createPortalClient } from './create-portal-client';
+export type { PortalClient, PortalClientOptions } from './create-portal-client';
+export { TurnkeyBillingPage } from './TurnkeyBillingPage';
+export type { TurnkeyBillingPageProps } from './TurnkeyBillingPage';