@umituz/web-polar-payment 1.0.4 → 1.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/web-polar-payment",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Universal Polar.sh subscription billing — Supabase & Firebase adapters",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -20,7 +20,8 @@
     "./presentation": "./src/presentation/index.ts"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --clean --external firebase --external firebase/functions --external firebase/firestore",

package/src/declarations.d.ts

@@ -0,0 +1,2 @@
+declare module 'firebase/functions';
+declare module 'firebase/firestore';

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

@@ -0,0 +1,19 @@
+/**
+ * Cancellation Entity
+ * @description Types for subscription cancellation reasons and outcomes
+ */
+
+export type CancellationReason =
+  | 'too_expensive'
+  | 'missing_features'
+  | 'switched_service'
+  | 'unused'
+  | 'customer_service'
+  | 'low_quality'
+  | 'too_complex'
+  | 'other';
+
+export interface CancelResult {
+  success: boolean;
+  endsAt?: string;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Checkout Entity
+ * @description Types for initiating and following process of checkouts
+ */
+
+export interface CheckoutParams {
+  productId: string;
+  planKey?: string;
+  billingCycle?: 'monthly' | 'yearly';
+  successUrl?: string;
+  /** Injected automatically by PolarProvider — do not pass manually */
+  userId?: string;
+}
+
+export interface CheckoutResult {
+  url: string;
+  id: string;
+}

package/src/domain/entities/index.ts

@@ -0,0 +1,5 @@
+export * from './subscription.entity';
+export * from './order.entity';
+export * from './checkout.entity';
+export * from './cancellation.entity';
+export * from './sync.entity';

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

@@ -0,0 +1,15 @@
+/**
+ * Order Entity
+ * @description Types for billing history items
+ */
+
+export interface OrderItem {
+  id: string;
+  createdAt: string;
+  amount: number;
+  currency: string;
+  status: string;
+  paid: boolean;
+  productName: string;
+  invoiceUrl?: string;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Subscription Entity
+ * @description Types for subscription status and billing cycles
+ */
+
+export type SubscriptionStatusValue =
+  | 'active'
+  | 'canceled'
+  | 'revoked'
+  | 'trialing'
+  | 'past_due'
+  | 'incomplete'
+  | 'incomplete_expired'
+  | 'unpaid'
+  | 'none';
+
+export type BillingCycle = 'monthly' | 'yearly';
+
+export interface SubscriptionStatus {
+  plan: string;
+  subscriptionId?: string;
+  subscriptionStatus: SubscriptionStatusValue;
+  cancelAtPeriodEnd?: boolean;
+  currentPeriodEnd?: string;
+  billingCycle?: BillingCycle;
+  polarCustomerId?: string;
+  /** Token balance (for token-based projects like Aria) */
+  tokens?: number;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Sync Entity
+ * @description Type for subscription synchronization results
+ */
+
+export interface SyncResult {
+  synced: boolean;
+  plan?: string;
+}

package/src/domain/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Domain Layer
+ * Subpath: @umituz/web-polar-payment/domain
+ */
+
+export * from './entities';
+export * from './interfaces';

package/src/domain/interfaces/index.ts

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

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

@@ -0,0 +1,23 @@
+import type {
+  SubscriptionStatus,
+  CheckoutParams,
+  CheckoutResult,
+  OrderItem,
+  CancellationReason,
+  CancelResult,
+  SyncResult,
+} from '../entities';
+
+/**
+ * Backend-agnostic interface every adapter must implement.
+ * @description Contract for Polar billing adapters (Firebase, Supabase, etc.)
+ */
+export interface PolarAdapter {
+  getStatus(userId: string): Promise<SubscriptionStatus>;
+  createCheckout(params: CheckoutParams): Promise<CheckoutResult>;
+  /** checkoutId is read from URL by the context and passed explicitly */
+  syncSubscription(userId: string, checkoutId?: string): Promise<SyncResult>;
+  getBillingHistory(userId: string): Promise<OrderItem[]>;
+  cancelSubscription(reason?: CancellationReason): Promise<CancelResult>;
+  getPortalUrl(userId: string): Promise<string>;
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @umituz/web-polar-payment
+ * Universal Polar.sh subscription billing — Firebase adapter
+ *
+ * ONEMLI: App'ler bu root barrel'i kullanMAMALI.
+ * Subpath import kullanin: "@umituz/web-polar-payment/domain"
+ */
+
+export * from './domain';
+export * from './infrastructure';
+export * from './presentation';

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

@@ -0,0 +1,18 @@
+/**
+ * Billing Constants
+ * @description Standardized subscription states and plan names
+ */
+
+export const SUBSCRIPTION_STATUS = {
+  ACTIVE: 'active' as const,
+  CANCELED: 'canceled' as const,
+  REVOKED: 'revoked' as const,
+  TRIALING: 'trialing' as const,
+  PAST_DUE: 'past_due' as const,
+  INCOMPLETE: 'incomplete' as const,
+  INCOMPLETE_EXPIRED: 'incomplete_expired' as const,
+  UNPAID: 'unpaid' as const,
+  NONE: 'none' as const,
+};
+
+export const FREE_PLAN = 'free';

package/src/infrastructure/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Infrastructure Layer
+ * Subpath: @umituz/web-polar-payment/infrastructure
+ */
+
+export * from './services/firebase-billing.service';
+export * from './constants/billing.constants';
+export * from './utils/normalization.util';

package/src/infrastructure/services/firebase-billing.service.ts

@@ -0,0 +1,132 @@
+import type { PolarAdapter } from '../../domain/interfaces';
+import type {
+  CheckoutParams,
+  CheckoutResult,
+  OrderItem,
+  CancellationReason,
+  CancelResult,
+  SubscriptionStatus,
+  SyncResult,
+} from '../../domain/entities';
+import { normalizeStatus, normalizeBillingCycle } from '../utils/normalization.util';
+
+// We use any for firebase types in implementation to bypass DTS build issues with external packages
+type FirebaseFunctions = any;
+type FirebaseFirestore = any;
+
+export interface FirebaseAdapterConfig {
+  functions: FirebaseFunctions;
+  firestore: FirebaseFirestore;
+  callables?: {
+    createCheckout?: string;
+    syncSubscription?: string;
+    getBillingHistory?: string;
+    cancelSubscription?: string;
+    getPortalUrl?: string;
+  };
+  db?: {
+    usersCollection?: string;
+    planField?: string;
+    billingCycleField?: string;
+    subscriptionIdField?: string;
+    subscriptionStatusField?: string;
+    polarCustomerIdField?: string;
+    cancelAtPeriodEndField?: string;
+    currentPeriodEndField?: string;
+  };
+}
+
+/**
+ * Firebase Billing Service
+ * @description Implementation of PolarAdapter for Firebase Functions and Firestore.
+ */
+export function createFirebaseAdapter(config: FirebaseAdapterConfig): PolarAdapter {
+  const callables = {
+    createCheckout: config.callables?.createCheckout ?? 'createCheckoutSession',
+    sync: config.callables?.syncSubscription ?? 'syncSubscription',
+    billing: config.callables?.getBillingHistory ?? 'getBillingHistory',
+    cancel: config.callables?.cancelSubscription ?? 'cancelSubscription',
+    portal: config.callables?.getPortalUrl ?? 'getCustomerPortalUrl',
+  };
+
+  const db = {
+    collection: config.db?.usersCollection ?? 'users',
+    plan: config.db?.planField ?? 'plan',
+    billingCycle: config.db?.billingCycleField ?? 'billingCycle',
+    subscriptionId: config.db?.subscriptionIdField ?? 'subscriptionId',
+    subscriptionStatus: config.db?.subscriptionStatusField ?? 'subscriptionStatus',
+    polarCustomerId: config.db?.polarCustomerIdField ?? 'polarCustomerId',
+    cancelAtPeriodEnd: config.db?.cancelAtPeriodEndField ?? 'cancelAtPeriodEnd',
+    currentPeriodEnd: config.db?.currentPeriodEndField ?? 'currentPeriodEnd',
+  };
+
+  async function callable<T = unknown, R = unknown>(name: string, data?: T): Promise<R> {
+    const { httpsCallable } = await import('firebase/functions');
+    const fn = (httpsCallable as any)(config.functions, name) as (data?: T) => Promise<{ data: R }>;
+    const result = await fn(data);
+    return result.data;
+  }
+
+  return {
+    async getStatus(userId: string): Promise<SubscriptionStatus> {
+      const { doc, getDoc } = await import('firebase/firestore');
+      const snap = await getDoc((doc as any)(config.firestore, db.collection, userId));
+
+      if (!snap.exists()) {
+        return { plan: 'free', subscriptionStatus: 'none' };
+      }
+
+      const d = snap.data() as Record<string, unknown>;
+
+      let currentPeriodEnd: string | undefined;
+      const rawEnd = d[db.currentPeriodEnd];
+      if (rawEnd != null) {
+        if (typeof rawEnd === 'object' && 'toDate' in (rawEnd as object)) {
+          currentPeriodEnd = (rawEnd as { toDate(): Date }).toDate().toISOString();
+        } else if (typeof rawEnd === 'string') {
+          currentPeriodEnd = rawEnd;
+        }
+      }
+
+      return {
+        plan: (d[db.plan] as string) ?? 'free',
+        billingCycle: normalizeBillingCycle((d[db.billingCycle] as string) ?? 'monthly'),
+        subscriptionId: d[db.subscriptionId] as string | undefined,
+        subscriptionStatus: normalizeStatus((d[db.subscriptionStatus] as string) ?? 'none'),
+        polarCustomerId: d[db.polarCustomerId] as string | undefined,
+        cancelAtPeriodEnd: d[db.cancelAtPeriodEnd] as boolean | undefined,
+        currentPeriodEnd,
+      };
+    },
+
+    async createCheckout(params: CheckoutParams): Promise<CheckoutResult> {
+      return callable<CheckoutParams, CheckoutResult>(callables.createCheckout, params);
+    },
+
+    async syncSubscription(_userId: string, _checkoutId?: string): Promise<SyncResult> {
+      return callable<Record<string, never>, SyncResult>(callables.sync, {});
+    },
+
+    async getBillingHistory(_userId: string): Promise<OrderItem[]> {
+      const result = await callable<Record<string, never>, { orders?: OrderItem[] }>(
+        callables.billing,
+        {},
+      );
+      return result.orders ?? [];
+    },
+
+    async cancelSubscription(reason?: CancellationReason): Promise<CancelResult> {
+      return callable<{ reason?: string }, CancelResult>(callables.cancel, { reason });
+    },
+
+    async getPortalUrl(_userId: string): Promise<string> {
+      const result = await callable<Record<string, never>, { url?: string; customerPortalUrl?: string }>(
+        callables.portal,
+        {},
+      );
+      const url = result.url ?? result.customerPortalUrl;
+      if (!url) throw new Error('No portal URL returned from Cloud Function');
+      return url;
+    },
+  };
+}

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

@@ -0,0 +1,31 @@
+import type { SubscriptionStatusValue, BillingCycle } from '../../domain/entities';
+
+/**
+ * Normalize a raw Polar status string to a known value.
+ * @description Defaults to 'none' for unknown statuses.
+ */
+export function normalizeStatus(raw: string): SubscriptionStatusValue {
+  const map: Record<string, SubscriptionStatusValue> = {
+    active: 'active',
+    trialing: 'trialing',
+    past_due: 'past_due',
+    incomplete: 'incomplete',
+    incomplete_expired: 'incomplete_expired',
+    unpaid: 'unpaid',
+    canceled: 'canceled',
+    cancelled: 'canceled',
+    revoked: 'revoked',
+    none: 'none',
+  };
+  return map[raw?.toLowerCase()] ?? 'none';
+}
+
+/** 
+ * Normalize billing interval
+ * @description Maps 'month'/'year' to 'monthly'/'yearly'
+ */
+export function normalizeBillingCycle(interval: string): BillingCycle {
+  if (interval === 'month' || interval === 'monthly') return 'monthly';
+  if (interval === 'year' || interval === 'yearly') return 'yearly';
+  return 'monthly';
+}

package/src/presentation/components/PolarProvider.tsx

@@ -0,0 +1,128 @@
+import {
+  useEffect,
+  useState,
+  useCallback,
+  useRef,
+  useMemo,
+  type ReactNode,
+} from 'react';
+import type { PolarAdapter } from '../../domain/interfaces';
+import type {
+  SubscriptionStatus,
+  CheckoutParams,
+  CancellationReason,
+  CancelResult,
+  SyncResult,
+  OrderItem,
+} from '../../domain/entities';
+import { PolarContext } from '../hooks/usePolarBilling';
+
+/**
+ * PolarProvider Component
+ * @description Context provider for Polar billing management.
+ */
+
+interface PolarProviderProps {
+  adapter: PolarAdapter;
+  userId?: string;
+  children: ReactNode;
+}
+
+const FREE_STATUS: SubscriptionStatus = {
+  plan: 'free',
+  subscriptionStatus: 'none',
+};
+
+export function PolarProvider({ adapter, userId, children }: PolarProviderProps) {
+  const [status, setStatus] = useState<SubscriptionStatus>(FREE_STATUS);
+  const [loading, setLoading] = useState(true);
+  const adapterRef = useRef(adapter);
+  adapterRef.current = adapter;
+  const refreshAbortRef = useRef<AbortController | null>(null);
+
+  const refresh = useCallback(async () => {
+    const uid = userId?.trim();
+    if (!uid) {
+      setStatus(FREE_STATUS);
+      setLoading(false);
+      return;
+    }
+
+    refreshAbortRef.current?.abort();
+    const ctrl = new AbortController();
+    refreshAbortRef.current = ctrl;
+
+    try {
+      setLoading(true);
+      const s = await adapterRef.current.getStatus(uid);
+      if (!ctrl.signal.aborted) setStatus(s);
+    } catch (err) {
+      if (!ctrl.signal.aborted) {
+        console.error('[polar-billing] getStatus failed:', err);
+        setStatus(FREE_STATUS);
+      }
+    } finally {
+      if (!ctrl.signal.aborted) setLoading(false);
+    }
+  }, [userId]);
+
+  useEffect(() => {
+    refresh();
+    return () => { refreshAbortRef.current?.abort(); };
+  }, [refresh]);
+
+  const startCheckout = useCallback(async (params: CheckoutParams) => {
+    const result = await adapterRef.current.createCheckout({ ...params, userId: userId?.trim() });
+    if (!result.url.startsWith('https://')) {
+      throw new Error('Invalid checkout URL returned');
+    }
+    window.location.href = result.url;
+  }, [userId]);
+
+  const syncSubscription = useCallback(async (): Promise<SyncResult> => {
+    const uid = userId?.trim();
+    if (!uid) return { synced: false };
+
+    const checkoutId = new URLSearchParams(window.location.search).get('checkout_id') ?? undefined;
+    const result = await adapterRef.current.syncSubscription(uid, checkoutId);
+    if (result.synced) await refresh();
+    return result;
+  }, [userId, refresh]);
+
+  const getBillingHistory = useCallback(async (): Promise<OrderItem[]> => {
+    const uid = userId?.trim();
+    if (!uid) return [];
+    return adapterRef.current.getBillingHistory(uid);
+  }, [userId]);
+
+  const cancelSubscription = useCallback(
+    async (reason?: CancellationReason): Promise<CancelResult> => {
+      const result = await adapterRef.current.cancelSubscription(reason);
+      if (result.success) await refresh();
+      return result;
+    },
+    [refresh],
+  );
+
+  const getPortalUrl = useCallback(async (): Promise<string> => {
+    const uid = userId?.trim();
+    if (!uid) throw new Error('No authenticated user');
+    return adapterRef.current.getPortalUrl(uid);
+  }, [userId]);
+
+  const value = useMemo(
+    () => ({
+      status,
+      loading,
+      refresh,
+      startCheckout,
+      syncSubscription,
+      getBillingHistory,
+      cancelSubscription,
+      getPortalUrl,
+    }),
+    [status, loading, refresh, startCheckout, syncSubscription, getBillingHistory, cancelSubscription, getPortalUrl],
+  );
+
+  return <PolarContext.Provider value={value}>{children}</PolarContext.Provider>;
+}

package/src/presentation/hooks/usePolarBilling.ts

@@ -0,0 +1,34 @@
+import { createContext, useContext } from 'react';
+import type {
+  SubscriptionStatus,
+  CheckoutParams,
+  CancellationReason,
+  CancelResult,
+  SyncResult,
+  OrderItem,
+} from '../../domain/entities';
+
+export interface PolarContextValue {
+  status: SubscriptionStatus;
+  loading: boolean;
+  refresh: () => Promise<void>;
+  startCheckout: (params: CheckoutParams) => Promise<void>;
+  syncSubscription: () => Promise<SyncResult>;
+  getBillingHistory: () => Promise<OrderItem[]>;
+  cancelSubscription: (reason?: CancellationReason) => Promise<CancelResult>;
+  getPortalUrl: () => Promise<string>;
+}
+
+export const PolarContext = createContext<PolarContextValue | undefined>(undefined);
+
+/**
+ * usePolarBilling Hook
+ * @description Hook to access Polar billing context
+ */
+export function usePolarBilling(): PolarContextValue {
+  const ctx = useContext(PolarContext);
+  if (!ctx) throw new Error('usePolarBilling must be used within <PolarProvider>');
+  return ctx;
+}
+
+export const useSubscription = usePolarBilling;

package/src/presentation/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Presentation Layer
+ * Subpath: @umituz/web-polar-payment/presentation
+ */
+
+export * from './components/PolarProvider';
+export * from './hooks/usePolarBilling';