@umituz/web-payment 0.0.0-stage → 1.0.1

package/src/http.ts

@@ -0,0 +1,3 @@
+
+export { createHttpAdapter } from './infrastructure/services/http/create-http-adapter';
+export type { HttpAdapterConfig } from './infrastructure/services/http/create-http-adapter';

package/src/index.ts

@@ -0,0 +1,12 @@
+
+export * from './core';
+export * from './products';
+export * from './react';
+
+export {
+  checkoutIdFromLocationSearch,
+  isSafeCheckoutUrl,
+  redirectToHostedCheckout,
+} from './infrastructure/browser/hosted-checkout';
+
+export { CHECKOUT_ID_PARAM } from './infrastructure/config/billing-env';

package/src/infrastructure/browser/hosted-checkout.ts

@@ -0,0 +1,26 @@
+import { CHECKOUT_ID_PARAM } from '../config/billing-env';
+import { isInsecureUrl, isLoopbackHost } from '../utils/security.util';
+
+export function isSafeCheckoutUrl(url: string): boolean {
+  if (typeof url !== 'string' || url.length === 0) return false;
+  if (url.startsWith('https://')) return true;
+  return isInsecureUrl(url) && isLoopbackHost(url);
+}
+
+export function redirectToHostedCheckout(url: string): void {
+  if (!isSafeCheckoutUrl(url)) throw new Error('invalid_checkout_url');
+  window.location.assign(url);
+}
+
+export function checkoutIdFromLocationSearch(search: string): string | null {
+  const withoutLeading = search.startsWith('?') ? search.slice(1) : search;
+  for (const pair of withoutLeading.split('&')) {
+    const separator = pair.indexOf('=');
+    if (separator === -1) continue;
+    if (pair.slice(0, separator) !== CHECKOUT_ID_PARAM) continue;
+    const value = pair.slice(separator + 1);
+    if (value.length === 0) return null;
+    return decodeURIComponent(value);
+  }
+  return null;
+}

package/src/infrastructure/config/billing-env.ts

@@ -0,0 +1,31 @@
+
+export const CHECKOUT_ID_PARAM = 'checkout_id';
+
+export const CHECKOUT_ID_PLACEHOLDER = '{CHECKOUT_ID}';
+
+export type ProductIdMap = Map<string, string>;
+
+export function parseProductIds(raw: string | undefined): ProductIdMap {
+  const map: ProductIdMap = new Map();
+  if (typeof raw !== 'string' || raw.length === 0) return map;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return map;
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return map;
+  for (const [key, value] of Object.entries(parsed as Record<string, unknown>)) {
+    if (typeof value === 'string' && value.length > 0) map.set(key, value);
+  }
+  return map;
+}
+
+export function productIdOf(ids: ProductIdMap, productKey: string): string | null {
+  return ids.get(productKey) ?? null;
+}
+
+export function successUrlWithCheckoutId(origin: string, returnPath: string): string {
+  const separator = returnPath.includes('?') ? '&' : '?';
+  return `${origin}${returnPath}${separator}${CHECKOUT_ID_PARAM}=${CHECKOUT_ID_PLACEHOLDER}`;
+}

package/src/infrastructure/constants/billing.constants.ts

@@ -0,0 +1,10 @@
+
+export {
+  SUBSCRIPTION_STATUS,
+  SUBSCRIPTION_STATUS_VALUES,
+  isKnownSubscriptionStatus,
+} from '../../domain/enums/subscription-status.enum';
+export type { SubscriptionStatusValue } from '../../domain/enums/subscription-status.enum';
+
+export const API_BASE_URL = 'https://api.polar.sh/v1';
+export const API_MAX_PAGE_SIZE = 100;

package/src/infrastructure/http/http-client.ts

@@ -0,0 +1,83 @@
+
+export interface HttpRequest {
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  url: string;
+  headers?: Record<string, string>;
+  body?: unknown;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+
+export interface HttpResponse<T> {
+  status: number;
+  ok: boolean;
+  data: T | null;
+  text(): Promise<string>;
+}
+
+export interface HttpClient {
+  request<T>(request: HttpRequest): Promise<HttpResponse<T>>;
+}
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+export class FetchHttpClient implements HttpClient {
+  async request<T>(request: HttpRequest): Promise<HttpResponse<T>> {
+    const init: RequestInit = {
+      method: request.method,
+      headers: {
+        Accept: 'application/json',
+        ...(request.headers ?? {}),
+      },
+    };
+    if (request.body !== undefined) {
+      (init as RequestInit & { body: string }).body = JSON.stringify(request.body);
+      (init.headers as Record<string, string>)['Content-Type'] = 'application/json';
+    }
+
+    const timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeoutMs);
+    const forwardAbort = () => controller.abort();
+    if (request.signal) {
+      if (request.signal.aborted) controller.abort();
+      else request.signal.addEventListener('abort', forwardAbort);
+    }
+    init.signal = controller.signal;
+
+    let response: Response;
+    try {
+      response = await fetch(request.url, init);
+    } catch (error) {
+      if (timedOut && error instanceof Error && error.name === 'AbortError') {
+        throw new DOMException(`Request timed out after ${timeoutMs}ms`, 'TimeoutError');
+      }
+      throw error;
+    } finally {
+      clearTimeout(timer);
+      request.signal?.removeEventListener('abort', forwardAbort);
+    }
+
+    const bodyText = await response.text();
+
+    let data: T | null = null;
+    if (bodyText.length > 0) {
+      try {
+        data = JSON.parse(bodyText) as T;
+      } catch {
+        data = null;
+      }
+    }
+
+    return {
+      status: response.status,
+      ok: response.ok,
+      data,
+      text: async () => bodyText,
+    };
+  }
+}

package/src/infrastructure/pagination/page-iterator.ts

@@ -0,0 +1,43 @@
+
+export interface Page<T> {
+  items: T[];
+  page: number;
+  totalCount: number;
+  maxPage: number;
+  isLast: boolean;
+}
+
+export interface PageFetcher<T> {
+  fetchPage(page: number, limit: number): Promise<Page<T>>;
+}
+
+export interface PageIteratorOptions {
+  limit?: number;
+  signal?: AbortSignal;
+}
+
+export class PageIterator<T> implements AsyncIterable<T> {
+  private readonly fetcher: PageFetcher<T>;
+  private readonly limit: number;
+  private readonly signal?: AbortSignal;
+
+  constructor(fetcher: PageFetcher<T>, options: PageIteratorOptions = {}) {
+    this.fetcher = fetcher;
+    this.limit = options.limit ?? 100;
+    this.signal = options.signal;
+  }
+
+  async *[Symbol.asyncIterator](): AsyncIterator<T> {
+    let page = 1;
+    while (true) {
+      if (this.signal?.aborted) return;
+      const current = await this.fetcher.fetchPage(page, this.limit);
+      for (const item of current.items) {
+        if (this.signal?.aborted) return;
+        yield item;
+      }
+      if (current.isLast || page >= current.maxPage) return;
+      page++;
+    }
+  }
+}

package/src/infrastructure/query/query-builder.ts

@@ -0,0 +1,26 @@
+
+export class QueryBuilder {
+  private readonly params: URLSearchParams;
+
+  constructor(initial?: Record<string, string | number | boolean | undefined | null>) {
+    this.params = new URLSearchParams();
+    if (initial) this.setMany(initial);
+  }
+
+  set(key: string, value: string | number | boolean | undefined | null): this {
+    if (value === undefined || value === null) return this;
+    this.params.set(key, String(value));
+    return this;
+  }
+
+  setMany(values: Record<string, string | number | boolean | undefined | null>): this {
+    for (const [key, value] of Object.entries(values)) {
+      this.set(key, value);
+    }
+    return this;
+  }
+
+  toString(): string {
+    return this.params.toString();
+  }
+}

package/src/infrastructure/services/billing.client.ts

@@ -0,0 +1,300 @@
+import type { PaymentProvider } from '../../domain/enums/payment-provider.enum';
+import { API_BASE_URL } from '../constants/billing.constants';
+import { HttpClient, FetchHttpClient } from '../http/http-client';
+import { BillingApiError } from './product.repository';
+
+export const SANDBOX_API_BASE_URL = 'https://sandbox-api.polar.sh/v1';
+
+export interface PaymentServerClient {
+  readonly provider: PaymentProvider;
+  createProduct?(params: CreateProductParams): Promise<CreatedProduct>;
+  createCheckout(params: CheckoutSessionParams): Promise<CheckoutSession>;
+  getCheckout(id: string): Promise<CheckoutSession>;
+  createPortalSession?(customerId: string, returnUrl?: string): Promise<PortalSession>;
+  getSubscription?(id: string): Promise<SubscriptionRecord>;
+  listSubscriptions?(filter?: { customerId?: string; productId?: string }): Promise<SubscriptionRecord[]>;
+  updateSubscription?(id: string, patch: { cancelAtPeriodEnd?: boolean }): Promise<SubscriptionRecord>;
+}
+
+export interface BillingClientConfig {
+  apiToken: string;
+  baseUrl?: string;
+  sandbox?: boolean;
+  http?: HttpClient;
+}
+
+export type CheckoutMetadata = Record<string, string | number | boolean>;
+
+export interface CheckoutSessionParams {
+  productId: string;
+  successUrl?: string;
+  customerId?: string;
+  customerEmail?: string;
+  externalCustomerId?: string;
+  amountCents?: number;
+  currency?: string;
+  allowDiscountCodes?: boolean;
+  metadata?: CheckoutMetadata;
+}
+
+export interface CheckoutSession {
+  id: string;
+  url: string;
+  status?: string;
+  customerId?: string;
+  customerEmail?: string;
+  subscriptionId?: string | null;
+  metadata?: CheckoutMetadata;
+}
+
+export interface SubscriptionRecord {
+  id: string;
+  status: string;
+  productId: string;
+  amountCents: number;
+  currency: string;
+  currentPeriodStart?: string;
+  currentPeriodEnd?: string;
+  cancelAtPeriodEnd: boolean;
+  canceledAt?: string | null;
+  endsAt?: string | null;
+  startedAt?: string | null;
+  customerId: string;
+  metadata: Record<string, string>;
+}
+
+export interface PortalSession {
+  url: string;
+}
+
+export interface CreateProductParams {
+  name: string;
+  description?: string;
+  amountCents: number;
+  currency?: string;
+  metadata?: CheckoutMetadata;
+}
+
+export interface CreatedProduct {
+  id: string;
+  name: string;
+}
+
+interface ProductDto {
+  id: string;
+  name?: string | null;
+}
+
+interface CheckoutDto {
+  id: string;
+  url?: string;
+  status?: string;
+  customer_id?: string | null;
+  customer_email?: string | null;
+  subscription_id?: string | null;
+  metadata?: CheckoutMetadata | null;
+}
+
+interface SubscriptionDto {
+  id: string;
+  status: string;
+  product_id: string;
+  amount: number;
+  currency: string;
+  current_period_start?: string | null;
+  current_period_end?: string | null;
+  cancel_at_period_end: boolean;
+  canceled_at?: string | null;
+  ends_at?: string | null;
+  started_at?: string | null;
+  customer_id?: string | null;
+  metadata?: Record<string, string> | null;
+}
+
+interface SubscriptionListDto {
+  items?: SubscriptionDto[];
+  pagination?: { max_page?: number; current_page?: number; total_count?: number };
+}
+
+function resolveBaseUrl(config: BillingClientConfig): string {
+  if (config.baseUrl) return config.baseUrl;
+  return config.sandbox ? SANDBOX_API_BASE_URL : API_BASE_URL;
+}
+
+function mapCheckout(dto: CheckoutDto): CheckoutSession {
+  return {
+    id: dto.id,
+    url: dto.url ?? '',
+    status: dto.status,
+    customerId: dto.customer_id ?? undefined,
+    customerEmail: dto.customer_email ?? undefined,
+    subscriptionId: dto.subscription_id ?? null,
+    metadata: dto.metadata ?? undefined,
+  };
+}
+
+function mapSubscription(dto: SubscriptionDto): SubscriptionRecord {
+  return {
+    id: dto.id,
+    status: dto.status,
+    productId: dto.product_id,
+    amountCents: dto.amount,
+    currency: dto.currency,
+    currentPeriodStart: dto.current_period_start ?? undefined,
+    currentPeriodEnd: dto.current_period_end ?? undefined,
+    cancelAtPeriodEnd: dto.cancel_at_period_end,
+    canceledAt: dto.canceled_at ?? null,
+    endsAt: dto.ends_at ?? null,
+    startedAt: dto.started_at ?? undefined,
+    customerId: dto.customer_id ?? '',
+    metadata: dto.metadata ?? {},
+  };
+}
+
+export class PolarBillingClient implements PaymentServerClient {
+  readonly provider = 'polar' as const;
+  private readonly http: HttpClient;
+  private readonly baseUrl: string;
+  private readonly headers: Record<string, string>;
+
+  constructor(config: BillingClientConfig) {
+    this.http = config.http ?? new FetchHttpClient();
+    this.baseUrl = resolveBaseUrl(config).replace(/\/$/, '');
+    this.headers = { Authorization: `Bearer ${config.apiToken}` };
+  }
+
+  private async request<T>(method: 'GET' | 'POST' | 'PATCH', path: string, body?: unknown): Promise<T> {
+    const response = await this.http.request<T>({
+      method,
+      url: `${this.baseUrl}${path}`,
+      headers: this.headers,
+      body,
+    });
+    if (!response.ok) {
+      throw new BillingApiError(
+        `Billing API ${method} ${path} failed with ${response.status}`,
+        response.status,
+        await response.text(),
+      );
+    }
+    return (response.data ?? {}) as T;
+  }
+
+  async createProduct(params: CreateProductParams): Promise<CreatedProduct> {
+    const dto = await this.request<ProductDto>('POST', '/products', {
+      name: params.name,
+      recurring_interval: null,
+      ...(params.description ? { description: params.description } : {}),
+      prices: [
+        {
+          amount_type: 'fixed',
+          price_currency: params.currency ?? 'usd',
+          price_amount: params.amountCents,
+        },
+      ],
+      ...(params.metadata ? { metadata: params.metadata } : {}),
+    });
+    return { id: dto.id, name: dto.name ?? params.name };
+  }
+
+  async createCheckout(params: CheckoutSessionParams): Promise<CheckoutSession> {
+    const dto = await this.request<CheckoutDto>('POST', '/checkouts', {
+      products: [params.productId],
+      ...(params.amountCents !== undefined
+        ? {
+            prices: {
+              [params.productId]: [
+                {
+                  amount_type: 'fixed',
+                  price_currency: params.currency ?? 'usd',
+                  price_amount: params.amountCents,
+                },
+              ],
+            },
+          }
+        : {}),
+      ...(params.successUrl ? { success_url: params.successUrl } : {}),
+      ...(params.customerId ? { customer_id: params.customerId } : {}),
+      ...(params.customerEmail ? { customer_email: params.customerEmail } : {}),
+      ...(params.externalCustomerId ? { external_customer_id: params.externalCustomerId } : {}),
+      ...(params.allowDiscountCodes !== undefined
+        ? { allow_discount_codes: params.allowDiscountCodes }
+        : {}),
+      ...(params.metadata ? { metadata: params.metadata } : {}),
+    });
+    return mapCheckout(dto);
+  }
+
+  async getCheckout(id: string): Promise<CheckoutSession> {
+    const dto = await this.request<CheckoutDto>('GET', `/checkouts/${encodeURIComponent(id)}`);
+    return mapCheckout(dto);
+  }
+
+  async createPortalSession(customerId: string, returnUrl?: string): Promise<PortalSession> {
+    const dto = await this.request<{ customer_portal_url?: string }>(
+      'POST',
+      '/customer-sessions',
+      {
+        customer_id: customerId,
+        ...(returnUrl ? { return_url: returnUrl } : {}),
+      },
+    );
+    const url = dto.customer_portal_url;
+    if (!url) {
+      throw new BillingApiError('Billing customer portal session returned no URL', 500, JSON.stringify(dto));
+    }
+    return { url };
+  }
+
+  async getSubscription(id: string): Promise<SubscriptionRecord> {
+    const dto = await this.request<SubscriptionDto>('GET', `/subscriptions/${encodeURIComponent(id)}`);
+    return mapSubscription(dto);
+  }
+
+  async listSubscriptions(filter: { customerId?: string; productId?: string } = {}): Promise<SubscriptionRecord[]> {
+    const query = new URLSearchParams();
+    if (filter.customerId) query.set('customer_id', filter.customerId);
+    if (filter.productId) query.set('product_id', filter.productId);
+    const suffix = query.size > 0 ? `?${query.toString()}` : '';
+    const first = await this.request<SubscriptionListDto>('GET', `/subscriptions${suffix}`);
+    const records: SubscriptionDto[] = [...(first.items ?? [])];
+    const maxPage = typeof first.pagination?.max_page === 'number' ? first.pagination.max_page : 1;
+    for (let page = 2; page <= maxPage; page += 1) {
+      const next = await this.request<SubscriptionListDto>(
+        'GET',
+        `/subscriptions${suffix}${suffix ? '&' : '?'}page=${page}`,
+      );
+      records.push(...(next.items ?? []));
+    }
+    return records.map(mapSubscription);
+  }
+
+  async updateSubscription(
+    id: string,
+    patch: { cancelAtPeriodEnd?: boolean },
+  ): Promise<SubscriptionRecord> {
+    const body = patch.cancelAtPeriodEnd !== undefined
+      ? { cancel_at_period_end: patch.cancelAtPeriodEnd }
+      : undefined;
+    const dto = await this.request<SubscriptionDto>(
+      'PATCH',
+      `/subscriptions/${encodeURIComponent(id)}`,
+      body,
+    );
+    return mapSubscription(dto);
+  }
+}
+
+export const BillingClient = PolarBillingClient;
+export type BillingClient = PolarBillingClient;
+
+export type PaymentClientConfig =
+  | ({ provider?: 'polar' } & BillingClientConfig)
+  | { provider: 'stripe'; apiKey: string; [key: string]: unknown };
+
+export function createPaymentClient(config: PaymentClientConfig): PaymentServerClient {
+  if (config.provider === 'stripe') {
+    throw new Error('Stripe provider client is not yet supported. Use provider "polar" or custom adapter.');
+  }
+  return new PolarBillingClient(config);
+}

package/src/infrastructure/services/create-billing-client.ts

@@ -0,0 +1,23 @@
+import { BillingClient, PolarBillingClient } from './billing.client';
+
+export function sandboxEnabled(raw: string | boolean | undefined): boolean {
+  if (typeof raw === 'boolean') return raw;
+  return raw === 'true';
+}
+
+export function createPolarClient(config: {
+  apiToken: string | undefined;
+  sandbox?: string | boolean | undefined;
+}): PolarBillingClient {
+  return new PolarBillingClient({
+    apiToken: config.apiToken ?? '',
+    ...(sandboxEnabled(config.sandbox) ? { sandbox: true } : {}),
+  });
+}
+
+export function createBillingClient(config: {
+  apiToken: string | undefined;
+  sandbox?: string | boolean | undefined;
+}): BillingClient {
+  return createPolarClient(config);
+}

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

@@ -0,0 +1,123 @@
+
+import type { BillingAdapter } from '../../../domain/interfaces';
+import type {
+  CancellationReason,
+  CancelResult,
+  CheckoutParams,
+  CheckoutResult,
+  OrderItem,
+  SubscriptionStatus,
+  SyncResult,
+} from '../../../domain/entities';
+
+export interface HttpAdapterConfig {
+  baseUrl?: string;
+  fetchImpl?: typeof fetch;
+  getUserId?: () => string | undefined | Promise<string | undefined>;
+  getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+}
+
+interface ErrorEnvelope {
+  error?: string | { message?: string };
+  message?: string;
+}
+
+function errorMessage(status: number, body: unknown): string {
+  const envelope = (body ?? {}) as ErrorEnvelope;
+  const errorDetail = typeof envelope.error === 'string' ? envelope.error : envelope.error?.message;
+  const detail = errorDetail ?? envelope.message ?? 'Billing request failed';
+  return `${detail} (HTTP ${status})`;
+}
+
+export function createHttpAdapter(config: HttpAdapterConfig = {}): BillingAdapter {
+  const baseUrl = (config.baseUrl ?? '/api/billing').replace(/\/$/, '');
+  const doFetch = config.fetchImpl ?? globalThis.fetch.bind(globalThis);
+
+  async function request<T>(
+    method: 'GET' | 'POST',
+    path: string,
+    body?: Record<string, unknown>,
+    explicitUserId?: string,
+  ): Promise<T> {
+    const userId = explicitUserId || (config.getUserId ? await config.getUserId() : undefined);
+    const headers: Record<string, string> = {
+      Accept: 'application/json',
+      ...(config.getHeaders ? await config.getHeaders() : {}),
+    };
+    const withUser = { ...(userId ? { userId } : {}), ...(body ?? {}) };
+    if (Object.keys(withUser).length > 0) headers['Content-Type'] = 'application/json';
+
+    const query = userId && method === 'GET' ? `?userId=${encodeURIComponent(userId)}` : '';
+    const response = await doFetch(`${baseUrl}${path}${query}`, {
+      method,
+      headers,
+      ...(method === 'POST' && Object.keys(withUser).length > 0 ? { body: JSON.stringify(withUser) } : {}),
+    });
+
+    let data: unknown = null;
+    const text = await response.text();
+    if (text.length > 0) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = null;
+      }
+    }
+    if (!response.ok) {
+      throw new Error(errorMessage(response.status, data));
+    }
+    return data as T;
+  }
+
+  return {
+    getStatus(userId: string) {
+      return request<SubscriptionStatus>('GET', '/status', undefined, userId);
+    },
+
+    createCheckout(params: CheckoutParams) {
+      return request<CheckoutResult>(
+        'POST',
+        '/checkout',
+        {
+          ...(params.productId ? { productId: params.productId } : {}),
+          ...(params.productKey ? { productKey: params.productKey } : {}),
+          ...(params.itemId ? { itemId: params.itemId } : {}),
+          ...(params.couponCode ? { couponCode: params.couponCode } : {}),
+          ...(params.billingCycle ? { billingCycle: params.billingCycle } : {}),
+          ...(params.successUrl ? { successUrl: params.successUrl } : {}),
+          ...(params.planKey ? { planKey: params.planKey } : {}),
+          ...(params.customerEmail ? { customerEmail: params.customerEmail } : {}),
+          ...(params.seats !== undefined ? { seats: params.seats } : {}),
+          ...(params.metadata ? { metadata: params.metadata } : {}),
+        },
+        params.userId,
+      );
+    },
+
+    syncSubscription(userId: string, checkoutId?: string) {
+      return request<SyncResult>('POST', '/sync', checkoutId ? { checkoutId } : undefined, userId);
+    },
+
+    async getBillingHistory(userId: string) {
+      const result = await request<OrderItem[] | { items?: OrderItem[]; orders?: OrderItem[] }>(
+        'GET',
+        '/history',
+        undefined,
+        userId,
+      );
+      if (Array.isArray(result)) return result;
+      return result.orders ?? result.items ?? [];
+    },
+
+    cancelSubscription(reason?: CancellationReason) {
+      return request<CancelResult>('POST', '/cancel', {
+        ...(reason ? { reason } : {}),
+      });
+    },
+
+    async getPortalUrl(userId: string) {
+      const result = await request<string | { url: string }>('GET', '/portal', undefined, userId);
+      return typeof result === 'string' ? result : result.url;
+    },
+  };
+}