@umituz/web-payment 0.0.0-stage → 1.0.0

package/src/infrastructure/services/memory/create-memory-adapter.ts

@@ -0,0 +1,126 @@
+
+import type { BillingAdapter } from '../../../domain/interfaces';
+import type {
+  CancellationReason,
+  CancelResult,
+  CheckoutParams,
+  CheckoutResult,
+  OrderItem,
+  SubscriptionStatus,
+  SyncResult,
+} from '../../../domain/entities';
+import { isActiveSubscription } from '../../../domain/entities';
+
+export interface MemoryAdapterConfig {
+  initialStatus?: Partial<SubscriptionStatus>;
+  initialHistory?: OrderItem[];
+  checkoutUrlBase?: string;
+  portalUrl?: string;
+  onCheckout?: (params: CheckoutParams) => void;
+  onCancel?: (reason?: CancellationReason) => void;
+}
+
+interface PendingCheckout {
+  id: string;
+  params: CheckoutParams;
+}
+
+export function createMemoryBillingAdapter(config: MemoryAdapterConfig = {}): BillingAdapter {
+  let status: SubscriptionStatus = {
+    plan: 'free',
+    subscriptionStatus: 'none',
+    billingCycle: 'monthly',
+    cancelAtPeriodEnd: false,
+    ...config.initialStatus,
+  };
+
+  const history: OrderItem[] = config.initialHistory ? [...config.initialHistory] : [];
+  const pending = new Map<string, PendingCheckout>();
+  let sequence = 0;
+
+  function checkoutUrl(checkout: PendingCheckout): string {
+    if (checkout.params.successUrl) {
+      return checkout.params.successUrl.replace('{CHECKOUT_ID}', checkout.id);
+    }
+    const base = config.checkoutUrlBase ?? 'https://checkout.example';
+    return `${base.replace(/\/$/, '')}/${checkout.id}`;
+  }
+
+  function fulfill(checkout: PendingCheckout): SubscriptionStatus {
+    const planName = checkout.params.planKey ?? checkout.params.productId ?? checkout.params.productKey ?? 'default';
+    return {
+      ...status,
+      plan: planName,
+      subscriptionStatus: 'active',
+      subscriptionId: `sub_${checkout.id.slice(4)}`,
+      billingCycle: checkout.params.billingCycle ?? status.billingCycle,
+      cancelAtPeriodEnd: false,
+      currentPeriodEnd: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
+    };
+  }
+
+  return {
+    async getStatus(_userId: string): Promise<SubscriptionStatus> {
+      return { ...status };
+    },
+
+    async createCheckout(params: CheckoutParams): Promise<CheckoutResult> {
+      config.onCheckout?.(params);
+      sequence += 1;
+      const checkout: PendingCheckout = {
+        id: `chk_${Date.now()}_${sequence}`,
+        params,
+      };
+      pending.set(checkout.id, checkout);
+      return {
+        id: checkout.id,
+        url: checkoutUrl(checkout),
+      };
+    },
+
+    async syncSubscription(_userId: string, checkoutId?: string): Promise<SyncResult> {
+      const checkout = checkoutId ? pending.get(checkoutId) : undefined;
+      const last = checkout ? undefined : [...pending.values()].pop();
+      const target = checkout ?? last;
+      if (!target) {
+        return { synced: false, plan: status.plan };
+      }
+      status = fulfill(target);
+      pending.delete(target.id);
+      history.unshift({
+        id: `ord_${target.id}`,
+        amount: 0,
+        currency: 'usd',
+        createdAt: new Date().toISOString(),
+        productName: target.params.planKey ?? target.params.productId,
+        status: 'paid',
+        paid: true,
+      });
+      return { synced: true, plan: status.plan };
+    },
+
+    async getBillingHistory(_userId: string): Promise<OrderItem[]> {
+      return [...history];
+    },
+
+    async cancelSubscription(reason?: CancellationReason): Promise<CancelResult> {
+      config.onCancel?.(reason);
+      if (!isActiveSubscription(status)) {
+        return { success: false };
+      }
+      status = {
+        ...status,
+        subscriptionStatus: 'canceled',
+        cancelAtPeriodEnd: true,
+      };
+      return {
+        success: true,
+        endsAt: status.currentPeriodEnd ?? new Date().toISOString(),
+      };
+    },
+
+    async getPortalUrl(_userId: string): Promise<string> {
+      return config.portalUrl ?? 'https://portal.example/billing';
+    },
+  };
+}

package/src/infrastructure/services/product.repository.ts

@@ -0,0 +1,198 @@
+
+import {
+  API_BASE_URL,
+  API_MAX_PAGE_SIZE,
+} from '../constants/billing.constants';
+import { HttpClient } from '../http/http-client';
+import { FetchHttpClient } from '../http/http-client';
+import { QueryBuilder } from '../query/query-builder';
+import { PageIterator, type Page, type PageFetcher } from '../pagination/page-iterator';
+import { PaginationClamp } from '../utils/pagination-clamp';
+import {
+  mapProduct,
+  mapProductList,
+  type Product,
+  type ProductDto,
+  type ProductListParams,
+  type ProductListResponse,
+} from '../../domain/mappers/product.mapper';
+
+export interface ProductApiConfig {
+  apiToken: string;
+  baseUrl?: string;
+}
+
+export interface ProductRequestOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+
+export class BillingApiError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+    public readonly body?: string,
+  ) {
+    super(message);
+    this.name = 'BillingApiError';
+    Object.setPrototypeOf(this, BillingApiError.prototype);
+  }
+}
+
+export function isBillingApiError(error: unknown): error is BillingApiError {
+  return error instanceof BillingApiError;
+}
+
+interface RawProductPage {
+  items: ProductDto[];
+  pagination: { total_count: number; max_page: number };
+}
+
+export class ProductRepository {
+  private readonly http: HttpClient;
+  private readonly apiToken: string;
+  private readonly baseUrl: string;
+
+  constructor(config: ProductApiConfig, http: HttpClient = new FetchHttpClient()) {
+    this.http = http;
+    this.apiToken = config.apiToken;
+    this.baseUrl = config.baseUrl ?? API_BASE_URL;
+  }
+
+  async list(
+    params?: ProductListParams,
+    options?: ProductRequestOptions,
+  ): Promise<ProductListResponse> {
+    const query = new QueryBuilder({
+      organization_id: params?.organizationId,
+      is_recurring: params?.isRecurring,
+      page: params?.page,
+      limit: this.clampLimit(params?.limit),
+    });
+    const url = `${this.baseUrl}/products?${query.toString()}`;
+
+    const response = await this.http.request<RawProductPage>({
+      method: 'GET',
+      url,
+      headers: this.authHeaders(),
+      signal: options?.signal,
+      timeoutMs: options?.timeoutMs,
+    });
+
+    if (!response.ok) {
+      const body = await response.text();
+      throw new BillingApiError(
+        `Billing API error: ${response.status}`,
+        response.status,
+        body,
+      );
+    }
+
+    return mapProductList(response.data);
+  }
+
+  async findById(
+    productId: string,
+    options?: ProductRequestOptions,
+  ): Promise<Product | null> {
+    const url = `${this.baseUrl}/products/${encodeURIComponent(productId)}`;
+
+    const response = await this.http.request<ProductDto>({
+      method: 'GET',
+      url,
+      headers: this.authHeaders(),
+      signal: options?.signal,
+      timeoutMs: options?.timeoutMs,
+    });
+
+    if (response.status === 404) return null;
+    if (!response.ok) {
+      const body = await response.text();
+      throw new BillingApiError(
+        `Billing API error: ${response.status}`,
+        response.status,
+        body,
+      );
+    }
+
+    if (!response.data) {
+      throw new BillingApiError(
+        'Billing API returned an empty product body',
+        response.status,
+      );
+    }
+
+    return mapProduct(response.data);
+  }
+
+  iterateAll(
+    params?: Omit<ProductListParams, 'page' | 'limit'>,
+    options: { limit?: number; signal?: AbortSignal } = {},
+  ): AsyncIterable<Product> {
+    const limit = this.clampLimit(options.limit);
+    const fetcher: PageFetcher<Product> = {
+      fetchPage: async (page, pageLimit) => {
+        const response = await this.list(
+          { ...params, page, limit: pageLimit },
+          { signal: options.signal },
+        );
+        const pageData: Page<Product> = {
+          items: response.items,
+          page,
+          totalCount: response.pagination.totalCount,
+          maxPage: response.pagination.maxPage,
+          isLast: page >= response.pagination.maxPage,
+        };
+        return pageData;
+      },
+    };
+    return new PageIterator(fetcher, { limit, signal: options.signal });
+  }
+
+  async listAll(
+    params?: Omit<ProductListParams, 'page' | 'limit'>,
+    options: { limit?: number; signal?: AbortSignal } = {},
+  ): Promise<Product[]> {
+    const out: Product[] = [];
+    for await (const product of this.iterateAll(params, options)) {
+      out.push(product);
+    }
+    return out;
+  }
+
+
+  private authHeaders(): Record<string, string> {
+    return { Authorization: `Bearer ${this.apiToken}` };
+  }
+
+  private clampLimit(limit: number | undefined): number | undefined {
+    return PaginationClamp.pageSize(limit, API_MAX_PAGE_SIZE);
+  }
+}
+
+
+const defaultClient = new FetchHttpClient();
+
+export async function getProducts(
+  config: ProductApiConfig,
+  params?: ProductListParams,
+  options?: ProductRequestOptions,
+): Promise<ProductListResponse> {
+  return new ProductRepository(config, defaultClient).list(params, options);
+}
+
+export async function getProductById(
+  config: ProductApiConfig,
+  productId: string,
+  options?: ProductRequestOptions,
+): Promise<Product | null> {
+  return new ProductRepository(config, defaultClient).findById(productId, options);
+}
+
+export async function getAllProducts(
+  config: ProductApiConfig,
+  params?: Omit<ProductListParams, 'page' | 'limit'>,
+  options: { limit?: number; signal?: AbortSignal } = {},
+): Promise<Product[]> {
+  return new ProductRepository(config, defaultClient).listAll(params, options);
+}

package/src/infrastructure/utils/checkout-metadata.ts

@@ -0,0 +1,55 @@
+
+export interface CheckoutOrderMetadata {
+  userId: string;
+  itemType: string;
+  itemId: string;
+  couponCode?: string;
+}
+
+export interface BuildCheckoutMetadataInput {
+  userId: string;
+  itemType: string;
+  itemId: string;
+  couponCode?: string;
+  extra?: Record<string, string>;
+}
+
+function asNonEmptyString(value: unknown): string | undefined {
+  if (typeof value !== 'string' || value.length === 0) return undefined;
+  return value;
+}
+
+export function buildCheckoutMetadata(
+  input: BuildCheckoutMetadataInput,
+): Record<string, string> {
+  const meta: Record<string, string> = {
+    userId: input.userId,
+    itemType: input.itemType,
+    itemId: input.itemId,
+  };
+  if (input.couponCode && input.couponCode.trim().length > 0) {
+    meta.couponCode = input.couponCode.trim();
+  }
+  if (input.extra) {
+    for (const [key, value] of Object.entries(input.extra)) {
+      if (typeof value === 'string' && value.length > 0) {
+        meta[key] = value;
+      }
+    }
+  }
+  return meta;
+}
+
+export function readCheckoutMetadata(
+  metadata: Record<string, unknown> | undefined,
+  allowedItemTypes: readonly string[],
+): CheckoutOrderMetadata | null {
+  if (metadata === undefined) return null;
+  const userId = asNonEmptyString(metadata.userId);
+  const itemType = asNonEmptyString(metadata.itemType);
+  const itemId = asNonEmptyString(metadata.itemId);
+  if (!userId || !itemType || !itemId) return null;
+  if (!allowedItemTypes.includes(itemType)) return null;
+  const couponCode = asNonEmptyString(metadata.couponCode);
+  return { userId, itemType, itemId, ...(couponCode ? { couponCode } : {}) };
+}

package/src/infrastructure/utils/date-renderer.ts

@@ -0,0 +1,53 @@
+
+const DEFAULT_LOCALE = 'en-US';
+
+const ISO_DATE_DISPLAY_LENGTH = 10;
+const FALLBACK_DATE_LABEL = 'soon';
+const FALLBACK_LONG_DATE = '—';
+
+export class DateRenderer {
+  private readonly dateLength: number;
+  private readonly shortFormatter: Intl.DateTimeFormat;
+  private readonly longFormatter: Intl.DateTimeFormat;
+
+  constructor(
+    locale: string = DEFAULT_LOCALE,
+    dateLength: number = ISO_DATE_DISPLAY_LENGTH,
+  ) {
+    this.dateLength = dateLength;
+    this.shortFormatter = new Intl.DateTimeFormat(locale, {
+      year: 'numeric',
+      month: 'short',
+      day: 'numeric',
+    });
+    this.longFormatter = new Intl.DateTimeFormat(locale, {
+      year: 'numeric',
+      month: 'long',
+      day: 'numeric',
+    });
+  }
+
+  short(iso: string | null | undefined): string {
+    if (!iso) return FALLBACK_LONG_DATE;
+    return iso.slice(0, this.dateLength);
+  }
+
+  renewal(iso: string | null | undefined, fallback: string = FALLBACK_DATE_LABEL): string {
+    const date = DateRenderer.parse(iso);
+    if (!date) return fallback;
+    return this.shortFormatter.format(date);
+  }
+
+  long(iso: string | null | undefined): string {
+    if (!iso) return FALLBACK_LONG_DATE;
+    const date = DateRenderer.parse(iso);
+    if (!date) return iso;
+    return this.longFormatter.format(date);
+  }
+
+  static parse(iso: string | null | undefined): Date | null {
+    if (!iso) return null;
+    const date = new Date(iso);
+    return Number.isNaN(date.getTime()) ? null : date;
+  }
+}

package/src/infrastructure/utils/money-formatter.ts

@@ -0,0 +1,39 @@
+
+import { minorUnitDivisor } from '../../domain/utils/minor-units';
+
+const DEFAULT_LOCALE = 'en-US';
+const DEFAULT_CURRENCY = 'USD';
+
+export interface MoneyFormatOptions {
+  locale?: string;
+  fallbackCurrency?: string;
+  maximumFractionDigits?: number;
+}
+
+export class MoneyFormatter {
+  private readonly locale: string;
+
+  constructor(locale: string = DEFAULT_LOCALE) {
+    this.locale = locale;
+  }
+
+  format(
+    amount: number | undefined,
+    currency: string | undefined,
+    options: MoneyFormatOptions = {},
+  ): string {
+    if (amount === undefined || amount === null) {
+      return 'Custom';
+    }
+    const code = (currency ?? options.fallbackCurrency ?? DEFAULT_CURRENCY).toUpperCase();
+    try {
+      return new Intl.NumberFormat(this.locale, {
+        style: 'currency',
+        currency: code,
+        maximumFractionDigits: options.maximumFractionDigits ?? 2,
+      }).format(amount / minorUnitDivisor(code));
+    } catch {
+      return `${amount} ${code}`;
+    }
+  }
+}

package/src/infrastructure/utils/normalization.util.ts

@@ -0,0 +1,22 @@
+
+import {
+  SUBSCRIPTION_STATUS,
+  isKnownSubscriptionStatus,
+  type SubscriptionStatusValue,
+} from '../../domain/enums/subscription-status.enum';
+import {
+  BILLING_CYCLE,
+  parseBillingCycle,
+  type BillingCycle,
+} from '../../domain/enums/billing-cycle.enum';
+
+export function normalizeStatus(raw: string | null | undefined): SubscriptionStatusValue {
+  if (typeof raw !== 'string') return SUBSCRIPTION_STATUS.NONE;
+  return isKnownSubscriptionStatus(raw) ? raw : SUBSCRIPTION_STATUS.NONE;
+}
+
+export function normalizeBillingCycle(
+  interval: string | null | undefined,
+): BillingCycle {
+  return parseBillingCycle(interval) ?? BILLING_CYCLE.MONTHLY;
+}

package/src/infrastructure/utils/pagination-clamp.ts

@@ -0,0 +1,11 @@
+
+import { API_MAX_PAGE_SIZE } from '../constants/billing.constants';
+
+export const MIN_PAGE_SIZE = 1;
+
+export class PaginationClamp {
+  static pageSize(raw: number | undefined, max: number = API_MAX_PAGE_SIZE): number {
+    if (raw === undefined) return max;
+    return Math.min(Math.max(MIN_PAGE_SIZE, raw), max);
+  }
+}

package/src/infrastructure/utils/receipt.util.ts

@@ -0,0 +1,6 @@
+export function formatReceiptNumber(id: string, prefix = 'RCP'): string {
+  if (!id || typeof id !== 'string') return `${prefix}-00000000`;
+  const clean = id.replace(/[^a-zA-Z0-9]/g, '');
+  const tail = clean.length >= 8 ? clean.slice(-8) : clean.padStart(8, '0');
+  return `${prefix}-${tail.toUpperCase()}`;
+}

package/src/infrastructure/utils/security.util.ts

@@ -0,0 +1,23 @@
+
+const LOOPBACK_HOSTS: ReadonlySet<string> = new Set(['localhost', '127.0.0.1', '0.0.0.0', '[::1]']);
+
+export function isValidCheckoutUrl(url: string): boolean {
+  return typeof url === 'string' && (url.startsWith('https://') || url.startsWith('http://'));
+}
+
+export function isInsecureUrl(url: string): boolean {
+  return typeof url === 'string' && url.startsWith('http://');
+}
+
+export function isLoopbackHost(url: string): boolean {
+  try {
+    const host = new URL(url).hostname.toLowerCase();
+    return LOOPBACK_HOSTS.has(host);
+  } catch {
+    return false;
+  }
+}
+
+export function isProductionInsecureUrl(url: string): boolean {
+  return isInsecureUrl(url) && !isLoopbackHost(url);
+}

package/src/infrastructure/utils/type-guards.util.ts

@@ -0,0 +1,23 @@
+
+export function asString(value: unknown): string | undefined {
+  return typeof value === 'string' ? value : undefined;
+}
+
+export function asBoolean(value: unknown): boolean | undefined {
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+export function isTimestamp(value: unknown): value is { toDate(): Date } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'toDate' in value &&
+    typeof (value as { toDate?: unknown }).toDate === 'function'
+  );
+}
+
+export function asRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object'
+    ? (value as Record<string, unknown>)
+    : {};
+}

package/src/infrastructure/utils/validation.util.ts

@@ -0,0 +1,10 @@
+
+export function normalizeUserId(userId: string | undefined): string | undefined {
+  if (typeof userId !== 'string') return undefined;
+  const trimmed = userId.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+export function isValidProductId(productId: unknown): productId is string {
+  return typeof productId === 'string' && productId.trim().length > 0;
+}