@umituz/web-payment 0.0.0-stage → 1.0.0

package/package.json

@@ -1,6 +1,124 @@
 {
   "name": "@umituz/web-payment",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Universal web payment & subscription billing engine with multi-provider architecture (Polar, Stripe, etc.)",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.mjs",
+      "require": "./dist/core.js"
+    },
+    "./products": {
+      "types": "./dist/products.d.ts",
+      "import": "./dist/products.mjs",
+      "require": "./dist/products.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.mjs",
+      "require": "./dist/react.js"
+    },
+    "./portal": {
+      "types": "./dist/portal.d.ts",
+      "import": "./dist/portal.mjs",
+      "require": "./dist/portal.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.mjs",
+      "require": "./dist/server.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "import": "./dist/http.mjs",
+      "require": "./dist/http.js"
+    },
+    "./memory": {
+      "types": "./dist/memory.d.ts",
+      "import": "./dist/memory.mjs",
+      "require": "./dist/memory.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/core.ts src/products.ts src/react.tsx src/portal.ts src/server.ts src/http.ts src/memory.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts src/core.ts src/products.ts src/react.tsx src/portal.ts src/server.ts src/http.ts src/memory.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm run build && npm test",
+    "version:patch": "npm version patch -m 'chore: release v%s'",
+    "version:minor": "npm version minor -m 'chore: release v%s'",
+    "version:major": "npm version major -m 'chore: release v%s'"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "payment",
+    "billing",
+    "subscription",
+    "polar",
+    "stripe",
+    "react",
+    "adapter",
+    "facade",
+    "repository"
+  ],
+  "author": "umituz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/umituz/web-payment.git"
+  },
+  "bugs": {
+    "url": "https://github.com/umituz/web-payment/issues"
+  },
+  "homepage": "https://github.com/umituz/web-payment#readme",
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "lucide-react": "^0.577.0 || ^1.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.20.0",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^26.6.6",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.7",
+    "eslint": "^9.20.0",
+    "eslint-plugin-react-hooks": "^5.1.0",
+    "globals": "^15.14.0",
+    "jsdom": "^25.0.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.23.0",
+    "vitest": "^3.0.0"
+  }
+}

package/src/core.ts

@@ -0,0 +1,81 @@
+
+export {
+  PAYMENT_PROVIDER,
+  PAYMENT_PROVIDER_VALUES,
+  isKnownPaymentProvider,
+} from './domain/enums/payment-provider.enum';
+export type { PaymentProvider } from './domain/enums/payment-provider.enum';
+
+export {
+  SUBSCRIPTION_STATUS,
+  SUBSCRIPTION_STATUS_VALUES,
+  isKnownSubscriptionStatus,
+} from './domain/enums/subscription-status.enum';
+export type { SubscriptionStatusValue } from './domain/enums/subscription-status.enum';
+
+export {
+  BILLING_CYCLE,
+  BILLING_CYCLE_VALUES,
+  isKnownBillingCycle,
+  parseBillingCycle,
+} from './domain/enums/billing-cycle.enum';
+export type { BillingCycle } from './domain/enums/billing-cycle.enum';
+
+export { POLAR_AMOUNT_TYPE } from './domain/enums/amount-type.enum';
+export type { AmountType } from './domain/enums/amount-type.enum';
+
+export {
+  CANCELLATION_REASON,
+  CANCELLATION_REASON_VALUES,
+} from './domain/entities/cancellation.entity';
+export type { CancellationReason, CancelResult } from './domain/entities/cancellation.entity';
+
+export { FREE_SUBSCRIPTION_STATUS, isActiveSubscription } from './domain/entities/subscription.entity';
+export type { SubscriptionStatus } from './domain/entities/subscription.entity';
+export type { CheckoutParams, CheckoutResult } from './domain/entities/checkout.entity';
+export type { OrderItem } from './domain/entities/order.entity';
+export type { SyncResult } from './domain/entities/sync.entity';
+export type {
+  Product,
+  ProductPrice,
+  ProductBenefit,
+  ProductListResponse,
+  ProductListParams,
+  RecurringInterval,
+  PriceType,
+} from './domain/entities/product.entity';
+
+export type { BillingAdapter } from './domain/interfaces';
+export { createMemoryBillingAdapter } from './infrastructure/services/memory/create-memory-adapter';
+export type { MemoryAdapterConfig } from './infrastructure/services/memory/create-memory-adapter';
+
+export { mapProduct, mapProductList } from './domain/mappers/product.mapper';
+export type {
+  ProductDto,
+  ProductPriceDto,
+  ProductBenefitDto,
+  ProductListResponseDto,
+} from './domain/mappers/product.mapper';
+
+export {
+  minorUnitDivisor,
+  toMajorUnits,
+  toMinorUnits,
+} from './domain/utils/minor-units';
+
+export {
+  applyPercentDiscount,
+  normalizeCouponCode,
+} from './domain/utils/percent-discount';
+
+export { formatReceiptNumber } from './infrastructure/utils/receipt.util';
+
+export {
+  buildCheckoutMetadata,
+  readCheckoutMetadata,
+} from './infrastructure/utils/checkout-metadata';
+export type {
+  BuildCheckoutMetadataInput,
+  CheckoutOrderMetadata,
+} from './infrastructure/utils/checkout-metadata';
+

package/src/domain/entities/cancellation.entity.ts

@@ -0,0 +1,28 @@
+export const CANCELLATION_REASON = Object.freeze({
+  TOO_EXPENSIVE: 'too_expensive',
+  MISSING_FEATURES: 'missing_features',
+  SWITCHED_SERVICE: 'switched_service',
+  UNUSED: 'unused',
+  CUSTOMER_SERVICE: 'customer_service',
+  LOW_QUALITY: 'low_quality',
+  TOO_COMPLEX: 'too_complex',
+  OTHER: 'other',
+} as const);
+
+export const CANCELLATION_REASON_VALUES = Object.freeze([
+  CANCELLATION_REASON.TOO_EXPENSIVE,
+  CANCELLATION_REASON.MISSING_FEATURES,
+  CANCELLATION_REASON.SWITCHED_SERVICE,
+  CANCELLATION_REASON.UNUSED,
+  CANCELLATION_REASON.CUSTOMER_SERVICE,
+  CANCELLATION_REASON.LOW_QUALITY,
+  CANCELLATION_REASON.TOO_COMPLEX,
+  CANCELLATION_REASON.OTHER,
+] as const);
+
+export type CancellationReason = (typeof CANCELLATION_REASON_VALUES)[number];
+
+export interface CancelResult {
+  success: boolean;
+  endsAt?: string;
+}

package/src/domain/entities/checkout.entity.ts

@@ -0,0 +1,21 @@
+import type { BillingCycle } from '../enums/billing-cycle.enum';
+
+export interface CheckoutParams {
+  productId?: string;
+  productKey?: string;
+  itemId?: string;
+  couponCode?: string;
+  planKey?: string;
+  billingCycle?: BillingCycle;
+  successUrl?: string;
+  userId?: string;
+  customerEmail?: string;
+  seats?: number;
+  metadata?: Record<string, string | number | boolean>;
+}
+
+export interface CheckoutResult {
+  url: string;
+  id: string;
+}
+

package/src/domain/entities/index.ts

@@ -0,0 +1,10 @@
+export * from './subscription.entity';
+export * from './checkout.entity';
+export * from './order.entity';
+export * from './cancellation.entity';
+export * from './sync.entity';
+export * from './product.entity';
+export { SUBSCRIPTION_STATUS_VALUES, isKnownSubscriptionStatus } from '../enums/subscription-status.enum';
+export type { SubscriptionStatusValue } from '../enums/subscription-status.enum';
+export { BILLING_CYCLE, BILLING_CYCLE_VALUES, isKnownBillingCycle } from '../enums/billing-cycle.enum';
+export type { BillingCycle } from '../enums/billing-cycle.enum';

package/src/domain/entities/order.entity.ts

@@ -0,0 +1,15 @@
+export interface OrderItem {
+  id: string;
+  createdAt: string;
+  amount: number;
+  currency: string;
+  status: string;
+  paid: boolean;
+  productName?: string;
+  itemType?: string;
+  itemId?: string;
+  amountUsd?: number;
+  receiptNumber?: string;
+  invoiceUrl?: string;
+}
+

package/src/domain/entities/product.entity.ts

@@ -0,0 +1,16 @@
+
+export type {
+  Product,
+  ProductPrice,
+  ProductBenefit,
+  ProductListResponse,
+  ProductListParams,
+} from '../mappers/product.mapper';
+
+import type { BillingCycle } from '../enums/billing-cycle.enum';
+
+export type RecurringInterval = 'day' | 'week' | 'month' | 'year';
+
+export type PriceType = 'fixed' | 'custom' | 'free' | 'seat_based' | 'metered_unit';
+
+export type { BillingCycle };

package/src/domain/entities/subscription.entity.ts

@@ -0,0 +1,24 @@
+import type { SubscriptionStatusValue } from '../enums/subscription-status.enum';
+import type { BillingCycle } from '../enums/billing-cycle.enum';
+
+export interface SubscriptionStatus {
+  plan: string;
+  subscriptionId?: string;
+  subscriptionStatus: SubscriptionStatusValue;
+  cancelAtPeriodEnd?: boolean;
+  currentPeriodEnd?: string;
+  billingCycle?: BillingCycle;
+  providerCustomerId?: string;
+}
+
+export const FREE_SUBSCRIPTION_STATUS: SubscriptionStatus = Object.freeze({
+  plan: 'free',
+  subscriptionStatus: 'none',
+}) as SubscriptionStatus;
+
+export function isActiveSubscription(status: SubscriptionStatus): boolean {
+  return (
+    status.subscriptionStatus === 'active' ||
+    status.subscriptionStatus === 'trialing'
+  );
+}

package/src/domain/entities/sync.entity.ts

@@ -0,0 +1,4 @@
+export interface SyncResult {
+  synced: boolean;
+  plan?: string;
+}

package/src/domain/enums/amount-type.enum.ts

@@ -0,0 +1,10 @@
+
+export const POLAR_AMOUNT_TYPE = Object.freeze({
+  FIXED: 'fixed',
+  CUSTOM: 'custom',
+  FREE: 'free',
+  SEAT_BASED: 'seat_based',
+  METERED_UNIT: 'metered_unit',
+} as const);
+
+export type AmountType = (typeof POLAR_AMOUNT_TYPE)[keyof typeof POLAR_AMOUNT_TYPE];

package/src/domain/enums/billing-cycle.enum.ts

@@ -0,0 +1,30 @@
+
+export const BILLING_CYCLE = Object.freeze({
+  MONTHLY: 'monthly',
+  YEARLY: 'yearly',
+} as const);
+
+export const BILLING_CYCLE_VALUES = Object.freeze([
+  BILLING_CYCLE.MONTHLY,
+  BILLING_CYCLE.YEARLY,
+] as const);
+
+export type BillingCycle = (typeof BILLING_CYCLE_VALUES)[number];
+
+const CANONICAL_BILLING_CYCLES: ReadonlySet<string> = new Set(BILLING_CYCLE_VALUES);
+
+const BILLING_CYCLE_ALIASES: ReadonlyMap<string, BillingCycle> = new Map([
+  [BILLING_CYCLE.MONTHLY, BILLING_CYCLE.MONTHLY],
+  ['month', BILLING_CYCLE.MONTHLY],
+  [BILLING_CYCLE.YEARLY, BILLING_CYCLE.YEARLY],
+  ['year', BILLING_CYCLE.YEARLY],
+]);
+
+export function isKnownBillingCycle(value: unknown): value is BillingCycle {
+  return typeof value === 'string' && CANONICAL_BILLING_CYCLES.has(value.toLowerCase());
+}
+
+export function parseBillingCycle(value: unknown): BillingCycle | null {
+  if (typeof value !== 'string') return null;
+  return BILLING_CYCLE_ALIASES.get(value.toLowerCase()) ?? null;
+}

package/src/domain/enums/index.ts

@@ -0,0 +1,5 @@
+export * from './subscription-status.enum';
+export * from './billing-cycle.enum';
+export * from './amount-type.enum';
+export * from './payment-provider.enum';
+

package/src/domain/enums/payment-provider.enum.ts

@@ -0,0 +1,14 @@
+export const PAYMENT_PROVIDER = {
+  POLAR: 'polar',
+  STRIPE: 'stripe',
+} as const;
+
+export const PAYMENT_PROVIDER_VALUES = Object.values(PAYMENT_PROVIDER);
+
+export type PaymentProvider = (typeof PAYMENT_PROVIDER)[keyof typeof PAYMENT_PROVIDER];
+
+const PAYMENT_PROVIDER_SET: ReadonlySet<string> = new Set<string>(PAYMENT_PROVIDER_VALUES);
+
+export function isKnownPaymentProvider(value: unknown): value is PaymentProvider {
+  return typeof value === 'string' && PAYMENT_PROVIDER_SET.has(value);
+}

package/src/domain/enums/subscription-status.enum.ts

@@ -0,0 +1,32 @@
+
+export const SUBSCRIPTION_STATUS = {
+  ACTIVE: 'active',
+  CANCELED: 'canceled',
+  REVOKED: 'revoked',
+  TRIALING: 'trialing',
+  PAST_DUE: 'past_due',
+  INCOMPLETE: 'incomplete',
+  INCOMPLETE_EXPIRED: 'incomplete_expired',
+  UNPAID: 'unpaid',
+  NONE: 'none',
+} as const;
+
+export const SUBSCRIPTION_STATUS_VALUES = Object.freeze([
+  SUBSCRIPTION_STATUS.ACTIVE,
+  SUBSCRIPTION_STATUS.CANCELED,
+  SUBSCRIPTION_STATUS.REVOKED,
+  SUBSCRIPTION_STATUS.TRIALING,
+  SUBSCRIPTION_STATUS.PAST_DUE,
+  SUBSCRIPTION_STATUS.INCOMPLETE,
+  SUBSCRIPTION_STATUS.INCOMPLETE_EXPIRED,
+  SUBSCRIPTION_STATUS.UNPAID,
+  SUBSCRIPTION_STATUS.NONE,
+] as const);
+
+export type SubscriptionStatusValue = (typeof SUBSCRIPTION_STATUS_VALUES)[number];
+
+const SUBSCRIPTION_STATUS_SET: ReadonlySet<string> = new Set(SUBSCRIPTION_STATUS_VALUES);
+
+export function isKnownSubscriptionStatus(value: unknown): value is SubscriptionStatusValue {
+  return typeof value === 'string' && SUBSCRIPTION_STATUS_SET.has(value.toLowerCase());
+}

package/src/domain/index.ts

@@ -0,0 +1,5 @@
+export * from './entities';
+export * from './interfaces';
+export * from './enums';
+export * from './mappers/product.mapper';
+export * from './utils/minor-units';

package/src/domain/interfaces/billing-adapter.interface.ts

@@ -0,0 +1,18 @@
+import type {
+  SubscriptionStatus,
+  CheckoutParams,
+  CheckoutResult,
+  OrderItem,
+  CancellationReason,
+  CancelResult,
+  SyncResult,
+} from '../entities';
+
+export interface BillingAdapter {
+  getStatus(userId: string): Promise<SubscriptionStatus>;
+  createCheckout(params: CheckoutParams): Promise<CheckoutResult>;
+  syncSubscription(userId: string, checkoutId?: string): Promise<SyncResult>;
+  getBillingHistory(userId: string): Promise<OrderItem[]>;
+  cancelSubscription(reason?: CancellationReason): Promise<CancelResult>;
+  getPortalUrl(userId: string): Promise<string>;
+}

package/src/domain/interfaces/index.ts

@@ -0,0 +1 @@
+export * from './billing-adapter.interface';

package/src/domain/mappers/product.mapper.ts

@@ -0,0 +1,176 @@
+
+import type { AmountType } from '../enums/amount-type.enum';
+import { parseBillingCycle, type BillingCycle } from '../enums/billing-cycle.enum';
+
+
+export interface ProductDto {
+  id: string;
+  name: string;
+  description: string | null;
+  is_recurring: boolean;
+  recurring_interval: string | null;
+  is_archived: boolean;
+  organization_id: string;
+  prices: ProductPriceDto[];
+  benefits: ProductBenefitDto[];
+  metadata: Record<string, unknown>;
+  created_at: string;
+  modified_at: string | null;
+}
+
+export interface ProductPriceDto {
+  id: string;
+  type: string;
+  amount_type: string;
+  amount?: number;
+  currency: string;
+  recurring_interval?: string;
+  is_archived: boolean;
+  product_id: string;
+  legacy?: boolean;
+}
+
+export interface ProductBenefitDto {
+  id: string;
+  type: string;
+  description: string | null;
+  properties: Record<string, unknown>;
+}
+
+export interface ProductListResponseDto {
+  items: ProductDto[];
+  pagination: {
+    total_count: number;
+    max_page: number;
+  };
+}
+
+
+export interface ProductPrice {
+  id: string;
+  type: AmountType;
+  amountType: AmountType;
+  amount?: number;
+  currency: string;
+  recurringInterval?: BillingCycle;
+  isArchived: boolean;
+  productId: string;
+  legacy?: boolean;
+}
+
+export interface ProductBenefit {
+  id: string;
+  type: string;
+  description: string | null;
+  properties: Record<string, unknown>;
+}
+
+export interface Product {
+  id: string;
+  name: string;
+  description: string | null;
+  isRecurring: boolean;
+  recurringInterval: BillingCycle | null;
+  isArchived: boolean;
+  organizationId: string;
+  prices: ProductPrice[];
+  benefits: ProductBenefit[];
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  modifiedAt: string | null;
+}
+
+export interface ProductListResponse {
+  items: Product[];
+  pagination: {
+    totalCount: number;
+    maxPage: number;
+  };
+}
+
+export interface ProductListParams {
+  organizationId?: string;
+  isRecurring?: boolean;
+  page?: number;
+  limit?: number;
+}
+
+
+const KNOWN_AMOUNT_TYPES: ReadonlySet<string> = new Set([
+  'fixed',
+  'custom',
+  'free',
+  'seat_based',
+  'metered_unit',
+]);
+
+function toAmountType(raw: string | undefined): AmountType {
+  if (raw && KNOWN_AMOUNT_TYPES.has(raw)) return raw as AmountType;
+  return 'fixed';
+}
+
+function toBillingCycle(interval: string | null | undefined): BillingCycle | null {
+  return parseBillingCycle(interval);
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' ? (value as Record<string, unknown>) : {};
+}
+
+function toPrice(dto: ProductPriceDto): ProductPrice {
+  return {
+    id: String(dto.id),
+    type: toAmountType(dto.type),
+    amountType: toAmountType(dto.amount_type),
+    amount: typeof dto.amount === 'number' ? dto.amount : undefined,
+    currency: String(dto.currency),
+    recurringInterval: toBillingCycle(dto.recurring_interval) ?? undefined,
+    isArchived: Boolean(dto.is_archived),
+    productId: String(dto.product_id),
+    legacy: Boolean(dto.legacy),
+  };
+}
+
+function toBenefit(dto: ProductBenefitDto): ProductBenefit {
+  return {
+    id: String(dto.id),
+    type: String(dto.type),
+    description: dto.description ?? null,
+    properties: asRecord(dto.properties),
+  };
+}
+
+export function mapProduct(dto: ProductDto | null | undefined): Product {
+  if (!dto || typeof dto !== 'object') {
+    throw new TypeError('mapProduct: expected a product DTO object');
+  }
+  return {
+    id: String(dto.id),
+    name: String(dto.name),
+    description: dto.description ?? null,
+    isRecurring: Boolean(dto.is_recurring),
+    recurringInterval: toBillingCycle(dto.recurring_interval),
+    isArchived: Boolean(dto.is_archived),
+    organizationId: String(dto.organization_id),
+    prices: Array.isArray(dto.prices) ? dto.prices.map(toPrice) : [],
+    benefits: Array.isArray(dto.benefits) ? dto.benefits.map(toBenefit) : [],
+    metadata: asRecord(dto.metadata),
+    createdAt: String(dto.created_at),
+    modifiedAt: dto.modified_at ?? null,
+  };
+}
+
+export function mapProductList(
+  dto: ProductListResponseDto | null | undefined,
+): ProductListResponse {
+  if (!dto || typeof dto !== 'object') {
+    return { items: [], pagination: { totalCount: 0, maxPage: 1 } };
+  }
+  return {
+    items: Array.isArray(dto.items) ? dto.items.map(mapProduct) : [],
+    pagination: {
+      totalCount: Number(dto.pagination?.total_count ?? 0),
+      maxPage: Number(dto.pagination?.max_page ?? 1),
+    },
+  };
+}

package/src/domain/utils/minor-units.ts

@@ -0,0 +1,20 @@
+
+const MINOR_UNIT_DIVISOR = 100;
+
+const ZERO_DECIMAL_CURRENCIES: ReadonlySet<string> = new Set([
+  'JPY', 'KRW', 'VND', 'CLP', 'PYG', 'XAF', 'XOF', 'BIF', 'DJF', 'GNF', 'XPF',
+]);
+
+export function minorUnitDivisor(currency: string): number {
+  return ZERO_DECIMAL_CURRENCIES.has(currency.toUpperCase())
+    ? 1
+    : MINOR_UNIT_DIVISOR;
+}
+
+export function toMajorUnits(amount: number, currency: string): number {
+  return amount / minorUnitDivisor(currency);
+}
+
+export function toMinorUnits(amount: number, currency: string): number {
+  return Math.round(amount * minorUnitDivisor(currency));
+}

package/src/domain/utils/percent-discount.ts

@@ -0,0 +1,17 @@
+
+export function normalizeCouponCode(code: unknown): string | null {
+  if (typeof code !== 'string') return null;
+  const normalized = code.trim().toUpperCase();
+  return normalized.length > 0 ? normalized : null;
+}
+
+export function applyPercentDiscount(
+  baseAmount: number,
+  percent: number,
+  minimumAmount: number,
+): number {
+  if (!Number.isFinite(baseAmount) || baseAmount <= 0) return 0;
+  if (!Number.isFinite(percent) || percent <= 0) return Math.round(baseAmount);
+  const discounted = Math.round(baseAmount * (1 - percent / 100));
+  return Math.max(minimumAmount, discounted);
+}