@umituz/web-payment 0.0.0-stage → 1.0.1

package/src/presentation/portal/labels.tsx

@@ -0,0 +1,218 @@
+
+import { createContext, useContext, useMemo } from 'react';
+import type { ReactNode } from 'react';
+import type { InvoiceStatus, SubscriptionStatus } from './types';
+
+export function formatLabel(template: string, params: Record<string, string | number>): string {
+  return template.replace(/\{(\w+)\}/g, (match, key: string) =>
+    key in params ? String(params[key]) : match,
+  );
+}
+
+export interface BillingLabels {
+  common: {
+    loading: string;
+    usage: string;
+  };
+  page: {
+    backToDashboard: string;
+    title: string;
+    description: string;
+    needHelp: string;
+    contactAria: string;
+  };
+  tabs: {
+    overview: string;
+    paymentMethods: string;
+    invoices: string;
+    plan: string;
+  };
+  overview: {
+    currentSubscription: string;
+    trialDaysLeft: string;
+    nextBilling: string;
+    upcomingInvoice: string;
+  };
+  invoices: {
+    empty: string;
+    moreItems: string;
+    due: string;
+    viewInvoice: string;
+    downloadPdf: string;
+  };
+  plan: {
+    title: string;
+    actionsTitle: string;
+    changePlan: string;
+    cancelSubscription: string;
+    confirmCancel: string;
+    cancelling: string;
+    cancelConfirmMessage: string;
+    cancelFailed: string;
+  };
+  planComparison: {
+    monthly: string;
+    yearly: string;
+    monthlyShort: string;
+    yearlyShort: string;
+    save: string;
+    saveWithYearly: string;
+    mostPopular: string;
+    currentPlan: string;
+    selectPlan: string;
+    processing: string;
+    billingCycleLabel: string;
+    radiogroupLabel: string;
+  };
+  paymentMethods: {
+    none: string;
+    add: string;
+    bankAccount: string;
+    expires: string;
+    default: string;
+    setDefault: string;
+    remove: string;
+    removeConfirm: string;
+    confirmRemove: string;
+    cancelRemove: string;
+  };
+  usage: {
+    limit: string;
+    resets: string;
+  };
+  status: Record<SubscriptionStatus, string>;
+  invoiceStatus: Record<InvoiceStatus, string>;
+}
+
+export type BillingLabelsOverrides = {
+  [K in keyof BillingLabels]?: BillingLabels[K] extends string
+    ? string
+    : { [K2 in keyof BillingLabels[K]]?: BillingLabels[K][K2] };
+};
+
+export const DEFAULT_BILLING_LABELS: Readonly<BillingLabels> = Object.freeze({
+  common: Object.freeze({
+    loading: 'Loading…',
+    usage: 'usage',
+  }),
+  page: Object.freeze({
+    backToDashboard: 'Back to dashboard',
+    title: 'Billing',
+    description: 'Manage your subscription, payment methods, and invoices.',
+    needHelp: 'Need help?',
+    contactAria: 'Contact {email}',
+  }),
+  tabs: Object.freeze({
+    overview: 'Overview',
+    paymentMethods: 'Payment Methods',
+    invoices: 'Invoices',
+    plan: 'Plan',
+  }),
+  overview: Object.freeze({
+    currentSubscription: 'Current Subscription',
+    trialDaysLeft: 'days left in trial',
+    nextBilling: 'Next billing:',
+    upcomingInvoice: 'Upcoming Invoice',
+  }),
+  invoices: Object.freeze({
+    empty: 'No invoices yet',
+    moreItems: 'more items',
+    due: 'Due',
+    viewInvoice: 'View invoice',
+    downloadPdf: 'Download PDF',
+  }),
+  plan: Object.freeze({
+    title: 'Current Plan',
+    actionsTitle: 'Plan Actions',
+    changePlan: 'Change Plan',
+    cancelSubscription: 'Cancel Subscription',
+    confirmCancel: 'Click again to confirm',
+    cancelling: 'Cancelling…',
+    cancelConfirmMessage:
+      'Your subscription stays active until the end of the current billing period.',
+    cancelFailed: 'Failed to cancel subscription. Please try again.',
+  }),
+  planComparison: Object.freeze({
+    monthly: 'Monthly',
+    yearly: 'Yearly',
+    monthlyShort: 'mo',
+    yearlyShort: 'yr',
+    save: 'Save {percent}%',
+    saveWithYearly: 'Save {percent}% with yearly billing',
+    mostPopular: 'Most Popular',
+    currentPlan: 'Current Plan',
+    selectPlan: 'Select Plan',
+    processing: 'Processing…',
+    billingCycleLabel: 'Billing cycle',
+    radiogroupLabel: 'Available plans',
+  }),
+  paymentMethods: Object.freeze({
+    none: 'No payment methods on file',
+    add: 'Add Payment Method',
+    bankAccount: 'Bank Account',
+    expires: 'Expires',
+    default: 'Default',
+    setDefault: 'Set as default',
+    remove: 'Remove',
+    removeConfirm: 'Remove this payment method?',
+    confirmRemove: 'Remove',
+    cancelRemove: 'Cancel',
+  }),
+  usage: Object.freeze({
+    limit: 'limit',
+    resets: 'Resets',
+  }),
+  status: Object.freeze({
+    active: 'Active',
+    trialing: 'Trial',
+    past_due: 'Past Due',
+    canceled: 'Canceled',
+    unpaid: 'Unpaid',
+    incomplete: 'Incomplete',
+    revoked: 'Revoked',
+  }),
+  invoiceStatus: Object.freeze({
+    draft: 'Draft',
+    open: 'Open',
+    paid: 'Paid',
+    void: 'Void',
+    uncollectible: 'Uncollectible',
+    refunded: 'Refunded',
+  }),
+});
+
+export function mergeLabels(overrides?: BillingLabelsOverrides): BillingLabels {
+  if (!overrides) return { ...DEFAULT_BILLING_LABELS } as BillingLabels;
+  const merged = { ...DEFAULT_BILLING_LABELS } as BillingLabels;
+  for (const key of Object.keys(overrides) as (keyof BillingLabelsOverrides)[]) {
+    const override = overrides[key];
+    if (override === undefined) continue;
+    const base = DEFAULT_BILLING_LABELS[key];
+    const target = merged as unknown as Record<string, unknown>;
+    if (typeof base === 'string' || typeof override === 'string') {
+      target[key] = override;
+    } else {
+      target[key] = { ...base, ...override };
+    }
+  }
+  return merged;
+}
+
+const BillingLabelsContext = createContext<BillingLabels>(
+  DEFAULT_BILLING_LABELS as BillingLabels,
+);
+
+export function BillingLabelsProvider({
+  labels,
+  children,
+}: {
+  labels?: BillingLabelsOverrides;
+  children: ReactNode;
+}) {
+  const value = useMemo(() => mergeLabels(labels), [labels]);
+  return <BillingLabelsContext.Provider value={value}>{children}</BillingLabelsContext.Provider>;
+}
+
+export function useBillingLabels(): BillingLabels {
+  return useContext(BillingLabelsContext);
+}

package/src/presentation/portal/styles.ts

@@ -0,0 +1,70 @@
+
+import type { CSSProperties } from 'react';
+import { VisualTokens } from '../theme/visual-tokens';
+
+export const visuallyHidden: CSSProperties = {
+  position: 'absolute',
+  width: 1,
+  height: 1,
+  padding: 0,
+  margin: -1,
+  overflow: 'hidden',
+  clip: 'rect(0 0 0 0)',
+  whiteSpace: 'nowrap',
+  border: 0,
+};
+
+export const card: CSSProperties = {
+  background: VisualTokens.color.surfacePrimary,
+  border: `1px solid ${VisualTokens.color.borderSubtle}`,
+  borderRadius: VisualTokens.radius.lg,
+  padding: VisualTokens.spacing.section,
+  boxSizing: 'border-box',
+};
+
+export const cardInteractive: CSSProperties = {
+  ...card,
+  cursor: 'pointer',
+};
+
+export const sectionTitle: CSSProperties = {
+  fontSize: VisualTokens.fontSize.title,
+  fontWeight: VisualTokens.fontWeight.strong,
+  color: VisualTokens.color.textPrimary,
+  margin: 0,
+  marginBottom: VisualTokens.spacing.xl,
+};
+
+export const mutedText: CSSProperties = {
+  color: VisualTokens.color.textMuted,
+  fontSize: VisualTokens.fontSize.body,
+};
+
+export const stack: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: VisualTokens.spacing.xl,
+};
+
+export const row: CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+};
+
+export const autoGrid = (minColumnWidth = 260): CSSProperties => ({
+  display: 'grid',
+  gridTemplateColumns: `repeat(auto-fit, minmax(${minColumnWidth}px, 1fr))`,
+  gap: VisualTokens.spacing.section,
+});
+
+export const alertDanger: CSSProperties = {
+  display: 'flex',
+  alignItems: 'flex-start',
+  gap: VisualTokens.spacing.md,
+  padding: VisualTokens.spacing.lg,
+  borderRadius: VisualTokens.radius.md,
+  border: `1px solid ${VisualTokens.color.borderWarning}`,
+  background: VisualTokens.color.surfaceDangerMuted,
+  color: VisualTokens.color.brandDangerText,
+  fontSize: VisualTokens.fontSize.body,
+};

package/src/presentation/portal/types.ts

@@ -0,0 +1,213 @@
+
+import type { ReactNode } from 'react';
+import { BILLING_CYCLE } from '../../domain/enums/billing-cycle.enum';
+import type { BillingCycle } from '../../domain/enums/billing-cycle.enum';
+import { SUBSCRIPTION_STATUS, INVOICE_STATUS, CURRENCY } from './constants';
+import type { BillingLabelsOverrides } from './labels';
+
+export { BILLING_CYCLE };
+export type { BillingCycle } from '../../domain/enums/billing-cycle.enum';
+
+export type SubscriptionStatus = typeof SUBSCRIPTION_STATUS[keyof typeof SUBSCRIPTION_STATUS];
+
+export type InvoiceStatus = typeof INVOICE_STATUS[keyof typeof INVOICE_STATUS];
+
+export type PlanType = string;
+
+export type Currency = typeof CURRENCY[keyof typeof CURRENCY];
+
+export type PlanFeature = string | { text: string; bold?: boolean; included?: boolean };
+
+export interface PlanTier {
+  id: string;
+  type?: PlanType;
+  name: string;
+  description: string;
+  badge?: string;
+  badgeColor?: string;
+  monthlyPrice: number;
+  yearlyPrice: number;
+  currency: Currency;
+  features: PlanFeature[];
+  highlight?: boolean;
+  maxUsers?: number;
+  storageLimit?: number;
+  apiLimit?: number;
+}
+
+export interface Subscription {
+  id: string;
+  planId: string;
+  plan: PlanTier;
+  status: SubscriptionStatus;
+  cycle: BillingCycle;
+  currentPeriodStart: string;
+  currentPeriodEnd: string;
+  cancelAtPeriodEnd?: boolean;
+  trialEnd?: string;
+  seats?: number;
+}
+
+export type PaymentMethodType = 'card' | 'bank_account' | 'wallet';
+
+export interface PaymentMethod {
+  id: string;
+  type: PaymentMethodType;
+  isDefault: boolean;
+  card?: {
+    last4: string;
+    brand: string;
+    expiryMonth: number;
+    expiryYear: number;
+    name?: string;
+  };
+  bankAccount?: {
+    last4: string;
+    bankName: string;
+    accountType?: 'checking' | 'savings';
+  };
+  createdAt: string;
+}
+
+export interface InvoiceItem {
+  description: string;
+  quantity: number;
+  unitPrice: number;
+  amount: number;
+}
+
+export interface Invoice {
+  id: string;
+  number: string;
+  amount: number;
+  currency: string;
+  status: InvoiceStatus;
+  date: string;
+  dueDate: string;
+  paidAt?: string;
+  invoiceUrl?: string;
+  pdfUrl?: string;
+  items?: InvoiceItem[];
+  subtotal?: number;
+  tax?: number;
+  total?: number;
+}
+
+export interface UsageMetric {
+  id: string;
+  name: string;
+  current: number;
+  limit: number;
+  unit: string;
+  resetPeriod: 'daily' | 'monthly' | 'yearly';
+  resetAt?: string;
+}
+
+export interface BillingSummary {
+  subscription: Subscription;
+  paymentMethods: PaymentMethod[];
+  defaultPaymentMethod?: PaymentMethod;
+  upcomingInvoice?: {
+    amount: number;
+    currency: Currency;
+    date: string;
+  };
+  usage: UsageMetric[];
+  recentInvoices: Invoice[];
+}
+
+export type PaymentMethodInput =
+  | {
+      type: 'card';
+      last4: string;
+      brand: string;
+      expiryMonth: number;
+      expiryYear: number;
+      name?: string;
+    }
+  | {
+      type: 'bank_account';
+      last4: string;
+      bankName: string;
+      accountType?: 'checking' | 'savings';
+    };
+
+export interface PlanComparisonProps {
+  plans: PlanTier[];
+  selectedPlan?: string;
+  cycle: BillingCycle;
+  showCycleToggle?: boolean;
+  showFeatures?: boolean;
+  onPlanSelect?: (planId: string) => void;
+  onCycleChange?: (cycle: BillingCycle) => void;
+  loading?: boolean;
+  labels?: BillingLabelsOverrides;
+}
+
+export interface PaymentMethodsListProps {
+  paymentMethods: PaymentMethod[];
+  loading?: boolean;
+  busyId?: string | null;
+  onSetDefault?: (methodId: string) => void;
+  onRemove?: (methodId: string) => void;
+  onAddNew?: () => void;
+}
+
+export interface InvoiceCardProps {
+  invoice: Invoice;
+  compact?: boolean;
+  onClick?: (invoice: Invoice) => void;
+  onDownload?: (invoice: Invoice) => void;
+  locale?: string;
+}
+
+export interface UsageCardProps {
+  metric: UsageMetric;
+  locale?: string;
+  showProgress?: boolean;
+  showLimit?: boolean;
+}
+
+export type BillingTabId = 'overview' | 'payment-methods' | 'invoices' | 'plan';
+
+export interface BillingPortalProps {
+  billing: BillingSummary;
+  loading?: boolean;
+  error?: string;
+  showTabs?: boolean;
+  activeTab?: BillingTabId;
+  locale?: string;
+  onTabChange?: (tab: BillingTabId) => void;
+  onAddPaymentMethod?: () => void;
+  onSetDefaultPaymentMethod?: (methodId: string) => void;
+  onRemovePaymentMethod?: (methodId: string) => void;
+  onViewInvoice?: (invoice: Invoice) => void;
+  onChangePlan?: () => void;
+  onCancelSubscription?: () => void | Promise<void>;
+  labels?: BillingLabelsOverrides;
+}
+
+export interface BillingLayoutProps {
+  config: BillingConfig;
+  children?: ReactNode;
+  onBack?: () => void;
+}
+
+export interface BillingConfig {
+  brandName: string;
+  logo?: ReactNode;
+  plans: PlanTier[];
+  currencies?: Currency[];
+  defaultCurrency?: Currency;
+  enableYearlyDiscount?: boolean;
+  yearlyDiscount?: number;
+  taxRate?: number;
+  supportEmail?: string;
+  cancelRoute?: string;
+  updatePaymentRoute?: string;
+  invoiceHistoryRoute?: string;
+}
+
+export interface BillingPageProps extends Omit<BillingPortalProps, 'showTabs'> {
+  config: BillingConfig;
+}

package/src/presentation/portal/utils/billing.ts

@@ -0,0 +1,193 @@
+
+import type { VisualTone } from '../../theme/visual-tokens';
+import { toMajorUnits } from '../../../domain/utils/minor-units';
+import type {
+  BillingCycle,
+  Invoice,
+  InvoiceStatus,
+  PlanTier,
+  SubscriptionStatus,
+  UsageMetric,
+} from '../types';
+
+export function formatNumber(num: number, locale: string = 'en-US'): string {
+  return new Intl.NumberFormat(locale).format(num);
+}
+
+export function formatPrice(amount: number, currency: string = 'USD'): string {
+  const localeMap: Record<string, string> = {
+    USD: 'en-US',
+    EUR: 'de-DE',
+    GBP: 'en-GB',
+    TRY: 'tr-TR',
+    JPY: 'ja-JP',
+  };
+
+  return new Intl.NumberFormat(localeMap[currency] ?? 'en-US', {
+    style: 'currency',
+    currency,
+  }).format(toMajorUnits(amount, currency));
+}
+
+export function calculateDiscount(monthlyPrice: number, yearlyPrice: number): number {
+  if (monthlyPrice <= 0) return 0;
+  const yearlyMonthly = yearlyPrice / 12;
+  const discount = ((monthlyPrice - yearlyMonthly) / monthlyPrice) * 100;
+  return Math.round(Math.max(discount, 0));
+}
+
+export function calculateProratedAmount(
+  amount: number,
+  daysUsed: number,
+  totalDays: number,
+): number {
+  if (totalDays === 0) return 0;
+  return (amount / totalDays) * daysUsed;
+}
+
+export function getPlanPrice(plan: PlanTier, cycle: BillingCycle): number {
+  return cycle === 'monthly' ? plan.monthlyPrice : plan.yearlyPrice;
+}
+
+export function calculateUsagePercentage(metric: UsageMetric): number {
+  if (metric.limit === 0) return 0;
+  return Math.min((metric.current / metric.limit) * 100, 100);
+}
+
+export function isNearLimit(metric: UsageMetric, threshold: number = 80): boolean {
+  return calculateUsagePercentage(metric) >= threshold;
+}
+
+export function getStatusTone(status: SubscriptionStatus): VisualTone {
+  const toneMap: Record<SubscriptionStatus, VisualTone> = {
+    active: 'active',
+    trialing: 'active',
+    past_due: 'warning',
+    canceled: 'neutral',
+    unpaid: 'danger',
+    incomplete: 'warning',
+    revoked: 'danger',
+  };
+  return toneMap[status] ?? 'neutral';
+}
+
+export function getStatusLabel(status: SubscriptionStatus): string {
+  const labelMap: Record<SubscriptionStatus, string> = {
+    active: 'Active',
+    trialing: 'Trial',
+    past_due: 'Past Due',
+    canceled: 'Canceled',
+    unpaid: 'Unpaid',
+    incomplete: 'Incomplete',
+    revoked: 'Revoked',
+  };
+  return labelMap[status] || status;
+}
+
+export function getInvoiceStatusTone(status: InvoiceStatus): VisualTone {
+  const toneMap: Record<InvoiceStatus, VisualTone> = {
+    draft: 'neutral',
+    open: 'warning',
+    paid: 'active',
+    void: 'neutral',
+    uncollectible: 'danger',
+    refunded: 'neutral',
+  };
+  return toneMap[status] ?? 'neutral';
+}
+
+export function getInvoiceStatusLabel(status: InvoiceStatus): string {
+  const labelMap: Record<InvoiceStatus, string> = {
+    draft: 'Draft',
+    open: 'Open',
+    paid: 'Paid',
+    void: 'Void',
+    uncollectible: 'Uncollectible',
+    refunded: 'Refunded',
+  };
+  return labelMap[status] || status;
+}
+
+export function formatCardNumber(last4: string, brand: string): string {
+  return `${brand.toUpperCase()} •••• ${last4}`;
+}
+
+export function formatExpiry(month: number, year: number): string {
+  return `${String(month).padStart(2, '0')}/${String(year).slice(-2)}`;
+}
+
+export function getDaysRemaining(endDate: string): number {
+  const end = new Date(endDate);
+  const now = new Date();
+  const diff = end.getTime() - now.getTime();
+  return Math.max(0, Math.ceil(diff / (1000 * 60 * 60 * 24)));
+}
+
+export function isTrialExpiringSoon(trialEnd: string, daysThreshold: number = 7): boolean {
+  const daysRemaining = getDaysRemaining(trialEnd);
+  return daysRemaining > 0 && daysRemaining <= daysThreshold;
+}
+
+export function getNextBillingDate(currentPeriodEnd: string, cycle: BillingCycle): Date {
+  const nextDate = new Date(currentPeriodEnd);
+
+  if (cycle === 'monthly') {
+    nextDate.setMonth(nextDate.getMonth() + 1);
+  } else {
+    nextDate.setFullYear(nextDate.getFullYear() + 1);
+  }
+
+  return nextDate;
+}
+
+export function groupInvoicesByStatus(invoices: Invoice[]): Record<InvoiceStatus, Invoice[]> {
+  const grouped: Record<InvoiceStatus, Invoice[]> = {
+    draft: [],
+    open: [],
+    paid: [],
+    void: [],
+    uncollectible: [],
+    refunded: [],
+  };
+
+  invoices.forEach((invoice) => {
+    grouped[invoice.status].push(invoice);
+  });
+
+  return grouped;
+}
+
+export function calculateInvoiceTotal(invoices: Invoice[], status?: InvoiceStatus): number {
+  const filtered = status ? invoices.filter((inv) => inv.status === status) : invoices;
+  return filtered.reduce((sum, inv) => sum + inv.amount, 0);
+}
+
+export function sortInvoicesByDate(invoices: Invoice[], order: 'asc' | 'desc' = 'desc'): Invoice[] {
+  return [...invoices].sort((a, b) => {
+    const dateA = new Date(a.date).getTime();
+    const dateB = new Date(b.date).getTime();
+    return order === 'asc' ? dateA - dateB : dateB - dateA;
+  });
+}
+
+export function formatFeature(
+  feature: string | { text: string; bold?: boolean; included?: boolean },
+): { text: string; bold?: boolean; included?: boolean } {
+  if (typeof feature === 'string') {
+    return { text: feature, included: true };
+  }
+  return feature;
+}
+
+export function isPopularPlan(plan: PlanTier, plans: PlanTier[]): boolean {
+  const middleIndex = Math.floor(plans.length / 2);
+  return plans[middleIndex]?.id === plan.id;
+}
+
+export function getTrialDaysText(trialEnd: string): string {
+  const days = getDaysRemaining(trialEnd);
+
+  if (days === 0) return 'Trial ends today';
+  if (days === 1) return '1 day left';
+  return `${days} days left`;
+}