@umituz/web-polar-payment 1.0.5 → 1.0.7

package/dist/index.d.mts

@@ -85,11 +85,11 @@ interface PolarAdapter {
     getPortalUrl(userId: string): Promise<string>;
 }
 
-type FirebaseFunctions = any;
-type FirebaseFirestore = any;
 interface FirebaseAdapterConfig {
-    functions: FirebaseFunctions;
-    firestore: FirebaseFirestore;
+    /** Firebase Functions instance from firebase/functions */
+    functions: unknown;
+    /** Firebase Firestore instance from firebase/firestore */
+    firestore: unknown;
     callables?: {
         createCheckout?: string;
         syncSubscription?: string;
@@ -133,12 +133,12 @@ declare const FREE_PLAN = "free";
 
 /**
  * Normalize a raw Polar status string to a known value.
- * @description Defaults to 'none' for unknown statuses.
+ * @description Defaults to 'none' for unknown statuses or non-string input.
  */
 declare function normalizeStatus(raw: string): SubscriptionStatusValue;
 /**
  * Normalize billing interval
- * @description Maps 'month'/'year' to 'monthly'/'yearly'
+ * @description Maps 'month'/'year' to 'monthly'/'yearly'. Defaults to 'monthly' for unknown values or non-string input.
  */
 declare function normalizeBillingCycle(interval: string): BillingCycle;
 

package/dist/index.d.ts

@@ -85,11 +85,11 @@ interface PolarAdapter {
     getPortalUrl(userId: string): Promise<string>;
 }
 
-type FirebaseFunctions = any;
-type FirebaseFirestore = any;
 interface FirebaseAdapterConfig {
-    functions: FirebaseFunctions;
-    firestore: FirebaseFirestore;
+    /** Firebase Functions instance from firebase/functions */
+    functions: unknown;
+    /** Firebase Firestore instance from firebase/firestore */
+    firestore: unknown;
     callables?: {
         createCheckout?: string;
         syncSubscription?: string;
@@ -133,12 +133,12 @@ declare const FREE_PLAN = "free";
 
 /**
  * Normalize a raw Polar status string to a known value.
- * @description Defaults to 'none' for unknown statuses.
+ * @description Defaults to 'none' for unknown statuses or non-string input.
  */
 declare function normalizeStatus(raw: string): SubscriptionStatusValue;
 /**
  * Normalize billing interval
- * @description Maps 'month'/'year' to 'monthly'/'yearly'
+ * @description Maps 'month'/'year' to 'monthly'/'yearly'. Defaults to 'monthly' for unknown values or non-string input.
  */
 declare function normalizeBillingCycle(interval: string): BillingCycle;
 

package/dist/index.js

@@ -56,16 +56,32 @@ function normalizeStatus(raw) {
     revoked: "revoked",
     none: "none"
   };
-  return map[raw?.toLowerCase()] ?? "none";
+  if (typeof raw !== "string") return "none";
+  return map[raw.toLowerCase()] ?? "none";
 }
 function normalizeBillingCycle(interval) {
-  if (interval === "month" || interval === "monthly") return "monthly";
-  if (interval === "year" || interval === "yearly") return "yearly";
+  if (typeof interval !== "string") return "monthly";
+  const normalized = interval.toLowerCase();
+  if (normalized === "month" || normalized === "monthly") return "monthly";
+  if (normalized === "year" || normalized === "yearly") return "yearly";
   return "monthly";
 }
 
 // src/infrastructure/services/firebase-billing.service.ts
+function asString(value) {
+  if (typeof value === "string") return value;
+  return void 0;
+}
+function asBoolean(value) {
+  if (typeof value === "boolean") return value;
+  return void 0;
+}
+function isTimestamp(value) {
+  return typeof value === "object" && value !== null && "toDate" in value && typeof value.toDate === "function";
+}
 function createFirebaseAdapter(config) {
+  const functions = config.functions;
+  const firestore = config.firestore;
   const callables = {
     createCheckout: config.callables?.createCheckout ?? "createCheckoutSession",
     sync: config.callables?.syncSubscription ?? "syncSubscription",
@@ -85,14 +101,14 @@ function createFirebaseAdapter(config) {
   };
   async function callable(name, data) {
     const { httpsCallable } = await import("firebase/functions");
-    const fn = httpsCallable(config.functions, name);
+    const fn = httpsCallable(functions, name);
     const result = await fn(data);
     return result.data;
   }
   return {
     async getStatus(userId) {
       const { doc, getDoc } = await import("firebase/firestore");
-      const snap = await getDoc(doc(config.firestore, db.collection, userId));
+      const snap = await getDoc(doc(firestore, db.collection, userId));
       if (!snap.exists()) {
         return { plan: "free", subscriptionStatus: "none" };
       }
@@ -100,19 +116,19 @@ function createFirebaseAdapter(config) {
       let currentPeriodEnd;
       const rawEnd = d[db.currentPeriodEnd];
       if (rawEnd != null) {
-        if (typeof rawEnd === "object" && "toDate" in rawEnd) {
+        if (isTimestamp(rawEnd)) {
           currentPeriodEnd = rawEnd.toDate().toISOString();
         } else if (typeof rawEnd === "string") {
           currentPeriodEnd = rawEnd;
         }
       }
       return {
-        plan: d[db.plan] ?? "free",
-        billingCycle: normalizeBillingCycle(d[db.billingCycle] ?? "monthly"),
-        subscriptionId: d[db.subscriptionId],
-        subscriptionStatus: normalizeStatus(d[db.subscriptionStatus] ?? "none"),
-        polarCustomerId: d[db.polarCustomerId],
-        cancelAtPeriodEnd: d[db.cancelAtPeriodEnd],
+        plan: asString(d[db.plan]) ?? "free",
+        billingCycle: normalizeBillingCycle(asString(d[db.billingCycle]) ?? "monthly"),
+        subscriptionId: asString(d[db.subscriptionId]),
+        subscriptionStatus: normalizeStatus(asString(d[db.subscriptionStatus]) ?? "none"),
+        polarCustomerId: asString(d[db.polarCustomerId]),
+        cancelAtPeriodEnd: asBoolean(d[db.cancelAtPeriodEnd]),
         currentPeriodEnd
       };
     },
@@ -177,6 +193,11 @@ var FREE_STATUS = {
   plan: "free",
   subscriptionStatus: "none"
 };
+function normalizeUserId(userId) {
+  if (typeof userId !== "string") return void 0;
+  const trimmed = userId.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
 function PolarProvider({ adapter, userId, children }) {
   const [status, setStatus] = (0, import_react2.useState)(FREE_STATUS);
   const [loading, setLoading] = (0, import_react2.useState)(true);
@@ -184,7 +205,7 @@ function PolarProvider({ adapter, userId, children }) {
   adapterRef.current = adapter;
   const refreshAbortRef = (0, import_react2.useRef)(null);
   const refresh = (0, import_react2.useCallback)(async () => {
-    const uid = userId?.trim();
+    const uid = normalizeUserId(userId);
     if (!uid) {
       setStatus(FREE_STATUS);
       setLoading(false);
@@ -213,14 +234,15 @@ function PolarProvider({ adapter, userId, children }) {
     };
   }, [refresh]);
   const startCheckout = (0, import_react2.useCallback)(async (params) => {
-    const result = await adapterRef.current.createCheckout({ ...params, userId: userId?.trim() });
+    const uid = normalizeUserId(userId);
+    const result = await adapterRef.current.createCheckout({ ...params, userId: uid });
     if (!result.url.startsWith("https://")) {
-      throw new Error("Invalid checkout URL returned");
+      throw new Error("[polar-billing] Invalid checkout URL returned: URL must start with https://");
     }
     window.location.href = result.url;
   }, [userId]);
   const syncSubscription = (0, import_react2.useCallback)(async () => {
-    const uid = userId?.trim();
+    const uid = normalizeUserId(userId);
     if (!uid) return { synced: false };
     const checkoutId = new URLSearchParams(window.location.search).get("checkout_id") ?? void 0;
     const result = await adapterRef.current.syncSubscription(uid, checkoutId);
@@ -228,7 +250,7 @@ function PolarProvider({ adapter, userId, children }) {
     return result;
   }, [userId, refresh]);
   const getBillingHistory = (0, import_react2.useCallback)(async () => {
-    const uid = userId?.trim();
+    const uid = normalizeUserId(userId);
     if (!uid) return [];
     return adapterRef.current.getBillingHistory(uid);
   }, [userId]);
@@ -241,8 +263,8 @@ function PolarProvider({ adapter, userId, children }) {
     [refresh]
   );
   const getPortalUrl = (0, import_react2.useCallback)(async () => {
-    const uid = userId?.trim();
-    if (!uid) throw new Error("No authenticated user");
+    const uid = normalizeUserId(userId);
+    if (!uid) throw new Error("[polar-billing] Cannot get portal URL: No authenticated user");
     return adapterRef.current.getPortalUrl(uid);
   }, [userId]);
   const value = (0, import_react2.useMemo)(

package/dist/index.mjs

@@ -12,16 +12,32 @@ function normalizeStatus(raw) {
     revoked: "revoked",
     none: "none"
   };
-  return map[raw?.toLowerCase()] ?? "none";
+  if (typeof raw !== "string") return "none";
+  return map[raw.toLowerCase()] ?? "none";
 }
 function normalizeBillingCycle(interval) {
-  if (interval === "month" || interval === "monthly") return "monthly";
-  if (interval === "year" || interval === "yearly") return "yearly";
+  if (typeof interval !== "string") return "monthly";
+  const normalized = interval.toLowerCase();
+  if (normalized === "month" || normalized === "monthly") return "monthly";
+  if (normalized === "year" || normalized === "yearly") return "yearly";
   return "monthly";
 }
 
 // src/infrastructure/services/firebase-billing.service.ts
+function asString(value) {
+  if (typeof value === "string") return value;
+  return void 0;
+}
+function asBoolean(value) {
+  if (typeof value === "boolean") return value;
+  return void 0;
+}
+function isTimestamp(value) {
+  return typeof value === "object" && value !== null && "toDate" in value && typeof value.toDate === "function";
+}
 function createFirebaseAdapter(config) {
+  const functions = config.functions;
+  const firestore = config.firestore;
   const callables = {
     createCheckout: config.callables?.createCheckout ?? "createCheckoutSession",
     sync: config.callables?.syncSubscription ?? "syncSubscription",
@@ -41,14 +57,14 @@ function createFirebaseAdapter(config) {
   };
   async function callable(name, data) {
     const { httpsCallable } = await import("firebase/functions");
-    const fn = httpsCallable(config.functions, name);
+    const fn = httpsCallable(functions, name);
     const result = await fn(data);
     return result.data;
   }
   return {
     async getStatus(userId) {
       const { doc, getDoc } = await import("firebase/firestore");
-      const snap = await getDoc(doc(config.firestore, db.collection, userId));
+      const snap = await getDoc(doc(firestore, db.collection, userId));
       if (!snap.exists()) {
         return { plan: "free", subscriptionStatus: "none" };
       }
@@ -56,19 +72,19 @@ function createFirebaseAdapter(config) {
       let currentPeriodEnd;
       const rawEnd = d[db.currentPeriodEnd];
       if (rawEnd != null) {
-        if (typeof rawEnd === "object" && "toDate" in rawEnd) {
+        if (isTimestamp(rawEnd)) {
           currentPeriodEnd = rawEnd.toDate().toISOString();
         } else if (typeof rawEnd === "string") {
           currentPeriodEnd = rawEnd;
         }
       }
       return {
-        plan: d[db.plan] ?? "free",
-        billingCycle: normalizeBillingCycle(d[db.billingCycle] ?? "monthly"),
-        subscriptionId: d[db.subscriptionId],
-        subscriptionStatus: normalizeStatus(d[db.subscriptionStatus] ?? "none"),
-        polarCustomerId: d[db.polarCustomerId],
-        cancelAtPeriodEnd: d[db.cancelAtPeriodEnd],
+        plan: asString(d[db.plan]) ?? "free",
+        billingCycle: normalizeBillingCycle(asString(d[db.billingCycle]) ?? "monthly"),
+        subscriptionId: asString(d[db.subscriptionId]),
+        subscriptionStatus: normalizeStatus(asString(d[db.subscriptionStatus]) ?? "none"),
+        polarCustomerId: asString(d[db.polarCustomerId]),
+        cancelAtPeriodEnd: asBoolean(d[db.cancelAtPeriodEnd]),
         currentPeriodEnd
       };
     },
@@ -139,6 +155,11 @@ var FREE_STATUS = {
   plan: "free",
   subscriptionStatus: "none"
 };
+function normalizeUserId(userId) {
+  if (typeof userId !== "string") return void 0;
+  const trimmed = userId.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
 function PolarProvider({ adapter, userId, children }) {
   const [status, setStatus] = useState(FREE_STATUS);
   const [loading, setLoading] = useState(true);
@@ -146,7 +167,7 @@ function PolarProvider({ adapter, userId, children }) {
   adapterRef.current = adapter;
   const refreshAbortRef = useRef(null);
   const refresh = useCallback(async () => {
-    const uid = userId?.trim();
+    const uid = normalizeUserId(userId);
     if (!uid) {
       setStatus(FREE_STATUS);
       setLoading(false);
@@ -175,14 +196,15 @@ function PolarProvider({ adapter, userId, children }) {
     };
   }, [refresh]);
   const startCheckout = useCallback(async (params) => {
-    const result = await adapterRef.current.createCheckout({ ...params, userId: userId?.trim() });
+    const uid = normalizeUserId(userId);
+    const result = await adapterRef.current.createCheckout({ ...params, userId: uid });
     if (!result.url.startsWith("https://")) {
-      throw new Error("Invalid checkout URL returned");
+      throw new Error("[polar-billing] Invalid checkout URL returned: URL must start with https://");
     }
     window.location.href = result.url;
   }, [userId]);
   const syncSubscription = useCallback(async () => {
-    const uid = userId?.trim();
+    const uid = normalizeUserId(userId);
     if (!uid) return { synced: false };
     const checkoutId = new URLSearchParams(window.location.search).get("checkout_id") ?? void 0;
     const result = await adapterRef.current.syncSubscription(uid, checkoutId);
@@ -190,7 +212,7 @@ function PolarProvider({ adapter, userId, children }) {
     return result;
   }, [userId, refresh]);
   const getBillingHistory = useCallback(async () => {
-    const uid = userId?.trim();
+    const uid = normalizeUserId(userId);
     if (!uid) return [];
     return adapterRef.current.getBillingHistory(uid);
   }, [userId]);
@@ -203,8 +225,8 @@ function PolarProvider({ adapter, userId, children }) {
     [refresh]
   );
   const getPortalUrl = useCallback(async () => {
-    const uid = userId?.trim();
-    if (!uid) throw new Error("No authenticated user");
+    const uid = normalizeUserId(userId);
+    if (!uid) throw new Error("[polar-billing] Cannot get portal URL: No authenticated user");
     return adapterRef.current.getPortalUrl(uid);
   }, [userId]);
   const value = useMemo(

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@umituz/web-polar-payment",
-  "version": "1.0.5",
-  "description": "Universal Polar.sh subscription billing — Supabase & Firebase adapters",
+  "version": "1.0.7",
+  "description": "Universal Polar.sh subscription billing — Firebase adapter",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -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,167 @@
+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';
+
+/**
+ * Type guard to safely extract string value from unknown Firestore data
+ */
+function asString(value: unknown): string | undefined {
+  if (typeof value === 'string') return value;
+  return undefined;
+}
+
+/**
+ * Type guard to safely extract boolean value from unknown Firestore data
+ */
+function asBoolean(value: unknown): boolean | undefined {
+  if (typeof value === 'boolean') return value;
+  return undefined;
+}
+
+/**
+ * Type guard to safely check if value is an object with toDate method
+ */
+function isTimestamp(value: unknown): value is { toDate(): Date } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'toDate' in value &&
+    typeof (value as { toDate: unknown }).toDate === 'function'
+  );
+}
+
+// Internal type aliases for Firebase SDK compatibility
+// Using 'any' internally to avoid DTS build issues with external Firebase packages
+type FirebaseFunctions = any;
+type FirebaseFirestore = any;
+
+export interface FirebaseAdapterConfig {
+  /** Firebase Functions instance from firebase/functions */
+  functions: unknown;
+  /** Firebase Firestore instance from firebase/firestore */
+  firestore: unknown;
+  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 {
+  // Cast internally to Firebase types for implementation
+  const functions = config.functions as FirebaseFunctions;
+  const firestore = config.firestore as FirebaseFirestore;
+
+  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)(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)(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 (isTimestamp(rawEnd)) {
+          currentPeriodEnd = rawEnd.toDate().toISOString();
+        } else if (typeof rawEnd === 'string') {
+          currentPeriodEnd = rawEnd;
+        }
+      }
+
+      return {
+        plan: asString(d[db.plan]) ?? 'free',
+        billingCycle: normalizeBillingCycle(asString(d[db.billingCycle]) ?? 'monthly'),
+        subscriptionId: asString(d[db.subscriptionId]),
+        subscriptionStatus: normalizeStatus(asString(d[db.subscriptionStatus]) ?? 'none'),
+        polarCustomerId: asString(d[db.polarCustomerId]),
+        cancelAtPeriodEnd: asBoolean(d[db.cancelAtPeriodEnd]),
+        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,35 @@
+import type { SubscriptionStatusValue, BillingCycle } from '../../domain/entities';
+
+/**
+ * Normalize a raw Polar status string to a known value.
+ * @description Defaults to 'none' for unknown statuses or non-string input.
+ */
+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',
+  };
+
+  if (typeof raw !== 'string') return 'none';
+  return map[raw.toLowerCase()] ?? 'none';
+}
+
+/**
+ * Normalize billing interval
+ * @description Maps 'month'/'year' to 'monthly'/'yearly'. Defaults to 'monthly' for unknown values or non-string input.
+ */
+export function normalizeBillingCycle(interval: string): BillingCycle {
+  if (typeof interval !== 'string') return 'monthly';
+  const normalized = interval.toLowerCase();
+  if (normalized === 'month' || normalized === 'monthly') return 'monthly';
+  if (normalized === 'year' || normalized === 'yearly') return 'yearly';
+  return 'monthly';
+}

package/src/presentation/components/PolarProvider.tsx

@@ -0,0 +1,135 @@
+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',
+};
+
+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 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 = normalizeUserId(userId);
+    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 uid = normalizeUserId(userId);
+    const result = await adapterRef.current.createCheckout({ ...params, userId: uid });
+    if (!result.url.startsWith('https://')) {
+      throw new Error('[polar-billing] Invalid checkout URL returned: URL must start with https://');
+    }
+    window.location.href = result.url;
+  }, [userId]);
+
+  const syncSubscription = useCallback(async (): Promise<SyncResult> => {
+    const uid = normalizeUserId(userId);
+    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 = normalizeUserId(userId);
+    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 = normalizeUserId(userId);
+    if (!uid) throw new Error('[polar-billing] Cannot get portal URL: 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';