@umituz/web-polar-payment 1.0.20 → 1.0.22

package/dist/index.js

@@ -118,14 +118,24 @@ function PolarProvider({ adapter, userId, children }) {
       throw new Error("[polar-billing] Invalid productId: must be a non-empty string");
     }
     const uid = userIdRef.current;
-    const result = await adapterRef.current.createCheckout({ ...params, userId: uid ?? void 0 });
-    if (!isValidCheckoutUrl(result.url)) {
-      throw new Error("[polar-billing] Invalid checkout URL returned: URL must start with https:// or http://");
+    if (!uid) {
+      throw new Error("[polar-billing] Cannot start checkout: No authenticated user");
     }
-    if (isProductionInsecureUrl(result.url)) {
-      throw new Error("[polar-billing] ERROR: Using insecure http:// URL in production environment");
+    try {
+      const result = await adapterRef.current.createCheckout({ ...params, userId: uid });
+      if (!isValidCheckoutUrl(result.url)) {
+        throw new Error("[polar-billing] Invalid checkout URL returned: URL must start with https:// or http://");
+      }
+      if (isProductionInsecureUrl(result.url)) {
+        throw new Error("[polar-billing] ERROR: Using insecure http:// URL in production environment");
+      }
+      window.location.href = result.url;
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new Error(`[polar-billing] Checkout failed: ${error.message}`);
+      }
+      throw error;
     }
-    window.location.href = result.url;
   }, []);
   const syncSubscription = (0, import_react2.useCallback)(async () => {
     const uid = userIdRef.current;
@@ -337,6 +347,14 @@ function isTimestamp(value) {
 }
 
 // src/infrastructure/services/firebase-billing.service.ts
+var FirebaseBillingError = class extends Error {
+  constructor(message, code, originalError) {
+    super(message);
+    this.code = code;
+    this.originalError = originalError;
+    this.name = "FirebaseBillingError";
+  }
+};
 function createFirebaseAdapter(config) {
   const functions = config.functions;
   const firestore = config.firestore;
@@ -357,15 +375,7 @@ function createFirebaseAdapter(config) {
     cancelAtPeriodEnd: config.db?.cancelAtPeriodEndField ?? "cancelAtPeriodEnd",
     currentPeriodEnd: config.db?.currentPeriodEndField ?? "currentPeriodEnd"
   };
-  let httpsCallableCache = null;
   let firestoreCache = null;
-  async function getHttpsCallable() {
-    if (!httpsCallableCache) {
-      const mod = await import("firebase/functions");
-      httpsCallableCache = mod.httpsCallable(functions);
-    }
-    return httpsCallableCache;
-  }
   async function getFirestore() {
     if (!firestoreCache) {
       const mod = await import("firebase/firestore");
@@ -374,62 +384,126 @@ function createFirebaseAdapter(config) {
     return firestoreCache;
   }
   async function callable(name, data) {
-    const httpsCallable = await getHttpsCallable();
-    const fn = httpsCallable(name);
-    const result = await fn(data);
-    return result.data;
+    try {
+      const { httpsCallable: hc } = await import("firebase/functions");
+      const fn = hc(functions, name);
+      const result = await fn(data);
+      return result.data;
+    } catch (error) {
+      if (error && typeof error === "object") {
+        const err = error;
+        throw new FirebaseBillingError(
+          err.message || `Function ${name} failed`,
+          err.code,
+          error
+        );
+      }
+      throw new FirebaseBillingError(
+        `Unknown error calling ${name}`,
+        "unknown",
+        error
+      );
+    }
+  }
+  function validateUserId(userId) {
+    if (!userId || typeof userId !== "string" || userId.trim() === "") {
+      throw new FirebaseBillingError("User ID is required and cannot be empty", "invalid-argument");
+    }
   }
   return {
     async getStatus(userId) {
-      const { doc, getDoc } = await getFirestore();
-      const docRef = doc(firestore, db.collection, userId);
-      const snap = await getDoc(docRef);
-      const exists = snap.exists;
-      if (!exists) {
-        return { plan: "free", subscriptionStatus: "none" };
-      }
-      const d = snap.data();
-      let currentPeriodEnd;
-      const rawEnd = d[db.currentPeriodEnd];
-      if (rawEnd != null) {
-        if (isTimestamp(rawEnd)) {
-          currentPeriodEnd = rawEnd.toDate().toISOString();
-        } else if (typeof rawEnd === "string") {
-          currentPeriodEnd = rawEnd;
+      try {
+        const { doc, getDoc } = await getFirestore();
+        const docRef = doc(firestore, db.collection, userId);
+        const snap = await getDoc(docRef);
+        const exists = snap.exists;
+        if (!exists) {
+          return { plan: "free", subscriptionStatus: "none" };
         }
+        const d = snap.data();
+        let currentPeriodEnd;
+        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
+        };
+      } catch (error) {
+        if (error instanceof FirebaseBillingError) throw error;
+        throw new FirebaseBillingError("Failed to load subscription status", "status-load-failed", error);
       }
-      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) {
-      return callable(callables.createCheckout, params);
+      if (!params.productId || typeof params.productId !== "string" || params.productId.trim() === "") {
+        throw new FirebaseBillingError("Product ID is required", "invalid-argument");
+      }
+      try {
+        return await callable(callables.createCheckout, params);
+      } catch (error) {
+        if (error instanceof FirebaseBillingError) throw error;
+        throw new FirebaseBillingError("Failed to create checkout session", "checkout-failed", error);
+      }
     },
     async syncSubscription(userId, checkoutId) {
-      return callable(callables.sync, { userId, checkoutId });
+      validateUserId(userId);
+      try {
+        return await callable(
+          callables.sync,
+          { userId, checkoutId }
+        );
+      } catch (error) {
+        if (error instanceof FirebaseBillingError) throw error;
+        throw new FirebaseBillingError("Failed to sync subscription", "sync-failed", error);
+      }
     },
     async getBillingHistory(userId) {
-      const result = await callable(
-        callables.billing,
-        { userId }
-      );
-      return result.orders ?? [];
+      validateUserId(userId);
+      try {
+        const result = await callable(
+          callables.billing,
+          { userId }
+        );
+        return result.orders ?? [];
+      } catch (error) {
+        if (error instanceof FirebaseBillingError) throw error;
+        console.error("[FirebaseBilling] Failed to load billing history:", error);
+        return [];
+      }
     },
     async cancelSubscription(reason) {
-      return callable(callables.cancel, { reason });
+      try {
+        return await callable(callables.cancel, { reason });
+      } catch (error) {
+        if (error instanceof FirebaseBillingError) throw error;
+        throw new FirebaseBillingError("Failed to cancel subscription", "cancel-failed", error);
+      }
     },
     async getPortalUrl(userId) {
-      const result = await callable(
-        callables.portal,
-        { userId }
-      );
-      return result.url;
+      validateUserId(userId);
+      try {
+        const result = await callable(
+          callables.portal,
+          { userId }
+        );
+        if (!result?.url || typeof result.url !== "string") {
+          throw new FirebaseBillingError("Invalid portal URL returned", "invalid-response");
+        }
+        return result.url;
+      } catch (error) {
+        if (error instanceof FirebaseBillingError) throw error;
+        throw new FirebaseBillingError("Failed to get customer portal URL", "portal-failed", error);
+      }
     }
   };
 }

package/dist/index.mjs

@@ -81,14 +81,24 @@ function PolarProvider({ adapter, userId, children }) {
       throw new Error("[polar-billing] Invalid productId: must be a non-empty string");
     }
     const uid = userIdRef.current;
-    const result = await adapterRef.current.createCheckout({ ...params, userId: uid ?? void 0 });
-    if (!isValidCheckoutUrl(result.url)) {
-      throw new Error("[polar-billing] Invalid checkout URL returned: URL must start with https:// or http://");
+    if (!uid) {
+      throw new Error("[polar-billing] Cannot start checkout: No authenticated user");
     }
-    if (isProductionInsecureUrl(result.url)) {
-      throw new Error("[polar-billing] ERROR: Using insecure http:// URL in production environment");
+    try {
+      const result = await adapterRef.current.createCheckout({ ...params, userId: uid });
+      if (!isValidCheckoutUrl(result.url)) {
+        throw new Error("[polar-billing] Invalid checkout URL returned: URL must start with https:// or http://");
+      }
+      if (isProductionInsecureUrl(result.url)) {
+        throw new Error("[polar-billing] ERROR: Using insecure http:// URL in production environment");
+      }
+      window.location.href = result.url;
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new Error(`[polar-billing] Checkout failed: ${error.message}`);
+      }
+      throw error;
     }
-    window.location.href = result.url;
   }, []);
   const syncSubscription = useCallback(async () => {
     const uid = userIdRef.current;
@@ -300,6 +310,14 @@ function isTimestamp(value) {
 }
 
 // src/infrastructure/services/firebase-billing.service.ts
+var FirebaseBillingError = class extends Error {
+  constructor(message, code, originalError) {
+    super(message);
+    this.code = code;
+    this.originalError = originalError;
+    this.name = "FirebaseBillingError";
+  }
+};
 function createFirebaseAdapter(config) {
   const functions = config.functions;
   const firestore = config.firestore;
@@ -320,15 +338,7 @@ function createFirebaseAdapter(config) {
     cancelAtPeriodEnd: config.db?.cancelAtPeriodEndField ?? "cancelAtPeriodEnd",
     currentPeriodEnd: config.db?.currentPeriodEndField ?? "currentPeriodEnd"
   };
-  let httpsCallableCache = null;
   let firestoreCache = null;
-  async function getHttpsCallable() {
-    if (!httpsCallableCache) {
-      const mod = await import("firebase/functions");
-      httpsCallableCache = mod.httpsCallable(functions);
-    }
-    return httpsCallableCache;
-  }
   async function getFirestore() {
     if (!firestoreCache) {
       const mod = await import("firebase/firestore");
@@ -337,62 +347,126 @@ function createFirebaseAdapter(config) {
     return firestoreCache;
   }
   async function callable(name, data) {
-    const httpsCallable = await getHttpsCallable();
-    const fn = httpsCallable(name);
-    const result = await fn(data);
-    return result.data;
+    try {
+      const { httpsCallable: hc } = await import("firebase/functions");
+      const fn = hc(functions, name);
+      const result = await fn(data);
+      return result.data;
+    } catch (error) {
+      if (error && typeof error === "object") {
+        const err = error;
+        throw new FirebaseBillingError(
+          err.message || `Function ${name} failed`,
+          err.code,
+          error
+        );
+      }
+      throw new FirebaseBillingError(
+        `Unknown error calling ${name}`,
+        "unknown",
+        error
+      );
+    }
+  }
+  function validateUserId(userId) {
+    if (!userId || typeof userId !== "string" || userId.trim() === "") {
+      throw new FirebaseBillingError("User ID is required and cannot be empty", "invalid-argument");
+    }
   }
   return {
     async getStatus(userId) {
-      const { doc, getDoc } = await getFirestore();
-      const docRef = doc(firestore, db.collection, userId);
-      const snap = await getDoc(docRef);
-      const exists = snap.exists;
-      if (!exists) {
-        return { plan: "free", subscriptionStatus: "none" };
-      }
-      const d = snap.data();
-      let currentPeriodEnd;
-      const rawEnd = d[db.currentPeriodEnd];
-      if (rawEnd != null) {
-        if (isTimestamp(rawEnd)) {
-          currentPeriodEnd = rawEnd.toDate().toISOString();
-        } else if (typeof rawEnd === "string") {
-          currentPeriodEnd = rawEnd;
+      try {
+        const { doc, getDoc } = await getFirestore();
+        const docRef = doc(firestore, db.collection, userId);
+        const snap = await getDoc(docRef);
+        const exists = snap.exists;
+        if (!exists) {
+          return { plan: "free", subscriptionStatus: "none" };
         }
+        const d = snap.data();
+        let currentPeriodEnd;
+        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
+        };
+      } catch (error) {
+        if (error instanceof FirebaseBillingError) throw error;
+        throw new FirebaseBillingError("Failed to load subscription status", "status-load-failed", error);
       }
-      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) {
-      return callable(callables.createCheckout, params);
+      if (!params.productId || typeof params.productId !== "string" || params.productId.trim() === "") {
+        throw new FirebaseBillingError("Product ID is required", "invalid-argument");
+      }
+      try {
+        return await callable(callables.createCheckout, params);
+      } catch (error) {
+        if (error instanceof FirebaseBillingError) throw error;
+        throw new FirebaseBillingError("Failed to create checkout session", "checkout-failed", error);
+      }
     },
     async syncSubscription(userId, checkoutId) {
-      return callable(callables.sync, { userId, checkoutId });
+      validateUserId(userId);
+      try {
+        return await callable(
+          callables.sync,
+          { userId, checkoutId }
+        );
+      } catch (error) {
+        if (error instanceof FirebaseBillingError) throw error;
+        throw new FirebaseBillingError("Failed to sync subscription", "sync-failed", error);
+      }
     },
     async getBillingHistory(userId) {
-      const result = await callable(
-        callables.billing,
-        { userId }
-      );
-      return result.orders ?? [];
+      validateUserId(userId);
+      try {
+        const result = await callable(
+          callables.billing,
+          { userId }
+        );
+        return result.orders ?? [];
+      } catch (error) {
+        if (error instanceof FirebaseBillingError) throw error;
+        console.error("[FirebaseBilling] Failed to load billing history:", error);
+        return [];
+      }
     },
     async cancelSubscription(reason) {
-      return callable(callables.cancel, { reason });
+      try {
+        return await callable(callables.cancel, { reason });
+      } catch (error) {
+        if (error instanceof FirebaseBillingError) throw error;
+        throw new FirebaseBillingError("Failed to cancel subscription", "cancel-failed", error);
+      }
     },
     async getPortalUrl(userId) {
-      const result = await callable(
-        callables.portal,
-        { userId }
-      );
-      return result.url;
+      validateUserId(userId);
+      try {
+        const result = await callable(
+          callables.portal,
+          { userId }
+        );
+        if (!result?.url || typeof result.url !== "string") {
+          throw new FirebaseBillingError("Invalid portal URL returned", "invalid-response");
+        }
+        return result.url;
+      } catch (error) {
+        if (error instanceof FirebaseBillingError) throw error;
+        throw new FirebaseBillingError("Failed to get customer portal URL", "portal-failed", error);
+      }
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/web-polar-payment",
-  "version": "1.0.20",
+  "version": "1.0.22",
   "description": "Universal Polar.sh subscription billing — Firebase adapter",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package/src/infrastructure/index.ts

@@ -1,4 +1,5 @@
 export * from './services/firebase-billing.service';
+export * from './services/polar-api.service';
 export * from './constants/billing.constants';
 export * from './utils/normalization.util';
 export * from './utils/validations.util';

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

@@ -13,8 +13,6 @@ import { asString, asBoolean, isTimestamp } from '../utils/firebase-helpers.util
 
 type FirestoreDoc = (firestore: unknown, collectionPath: string, docId: string) => unknown;
 type FirestoreGetDoc = (ref: unknown) => Promise<{ exists: boolean; data(): Record<string, unknown> }>;
-type HttpsCallableFn = <T = unknown, R = unknown>(data?: T) => Promise<{ data: R }>;
-type HttpsCallable = (name: string) => HttpsCallableFn;
 
 export interface FirebaseAdapterConfig {
   functions: unknown;
@@ -38,6 +36,20 @@ export interface FirebaseAdapterConfig {
   };
 }
 
+/**
+ * Custom error class for Firebase billing operations
+ */
+export class FirebaseBillingError extends Error {
+  constructor(
+    message: string,
+    public code?: string,
+    public originalError?: unknown
+  ) {
+    super(message);
+    this.name = 'FirebaseBillingError';
+  }
+}
+
 export function createFirebaseAdapter(config: FirebaseAdapterConfig): PolarAdapter {
   const functions = config.functions;
   const firestore = config.firestore;
@@ -61,17 +73,8 @@ export function createFirebaseAdapter(config: FirebaseAdapterConfig): PolarAdapt
     currentPeriodEnd: config.db?.currentPeriodEndField ?? 'currentPeriodEnd',
   };
 
-  let httpsCallableCache: HttpsCallable | null = null;
   let firestoreCache: { doc: FirestoreDoc; getDoc: FirestoreGetDoc } | null = null;
 
-  async function getHttpsCallable(): Promise<HttpsCallable> {
-    if (!httpsCallableCache) {
-      const mod = await import('firebase/functions');
-      httpsCallableCache = mod.httpsCallable(functions) as HttpsCallable;
-    }
-    return httpsCallableCache;
-  }
-
   async function getFirestore(): Promise<{ doc: FirestoreDoc; getDoc: FirestoreGetDoc }> {
     if (!firestoreCache) {
       const mod = await import('firebase/firestore');
@@ -80,73 +83,153 @@ export function createFirebaseAdapter(config: FirebaseAdapterConfig): PolarAdapt
     return firestoreCache;
   }
 
+  /**
+   * Call a Firebase callable function with proper error handling
+   */
   async function callable<T = unknown, R = unknown>(name: string, data?: T): Promise<R> {
-    const httpsCallable = await getHttpsCallable();
-    const fn = httpsCallable(name) as (data?: T) => Promise<{ data: R }>;
-    const result = await fn(data);
-    return result.data;
+    try {
+      const { httpsCallable: hc } = await import('firebase/functions');
+      const fn = hc(functions, name) as (data?: T) => Promise<{ data: R }>;
+      const result = await fn(data);
+      return result.data;
+    } catch (error) {
+      // Handle Firebase Functions errors
+      if (error && typeof error === 'object') {
+        const err = error as { code?: string; message?: string };
+        throw new FirebaseBillingError(
+          err.message || `Function ${name} failed`,
+          err.code,
+          error
+        );
+      }
+      throw new FirebaseBillingError(
+        `Unknown error calling ${name}`,
+        'unknown',
+        error
+      );
+    }
+  }
+
+  /**
+   * Validate userId is not empty
+   */
+  function validateUserId(userId: string | undefined): void {
+    if (!userId || typeof userId !== 'string' || userId.trim() === '') {
+      throw new FirebaseBillingError('User ID is required and cannot be empty', 'invalid-argument');
+    }
   }
 
   return {
     async getStatus(userId: string): Promise<SubscriptionStatus> {
-      const { doc, getDoc } = await getFirestore();
-      const docRef = doc(firestore, db.collection, userId);
-      const snap = await getDoc(docRef);
-
-      const exists = (snap as { exists: boolean }).exists;
-      if (!exists) {
-        return { plan: 'free', subscriptionStatus: 'none' };
-      }
+      try {
+        const { doc, getDoc } = await getFirestore();
+        const docRef = doc(firestore, db.collection, userId);
+        const snap = await getDoc(docRef);
+
+        const exists = (snap as { exists: boolean }).exists;
+        if (!exists) {
+          return { plan: 'free', subscriptionStatus: 'none' };
+        }
 
-      const d = snap.data();
+        const d = snap.data();
 
-      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;
+        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,
-      };
+        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,
+        };
+      } catch (error) {
+        if (error instanceof FirebaseBillingError) throw error;
+        throw new FirebaseBillingError('Failed to load subscription status', 'status-load-failed', error);
+      }
     },
 
     async createCheckout(params: CheckoutParams): Promise<CheckoutResult> {
-      return callable<CheckoutParams, CheckoutResult>(callables.createCheckout, params);
+      // Validate checkout params
+      if (!params.productId || typeof params.productId !== 'string' || params.productId.trim() === '') {
+        throw new FirebaseBillingError('Product ID is required', 'invalid-argument');
+      }
+
+      try {
+        return await callable<CheckoutParams, CheckoutResult>(callables.createCheckout, params);
+      } catch (error) {
+        if (error instanceof FirebaseBillingError) throw error;
+        throw new FirebaseBillingError('Failed to create checkout session', 'checkout-failed', error);
+      }
     },
 
     async syncSubscription(userId: string, checkoutId?: string): Promise<SyncResult> {
-      return callable<{ userId: string; checkoutId?: string }, SyncResult>(callables.sync, { userId, checkoutId });
+      validateUserId(userId);
+
+      try {
+        return await callable<{ userId: string; checkoutId?: string }, SyncResult>(
+          callables.sync,
+          { userId, checkoutId }
+        );
+      } catch (error) {
+        if (error instanceof FirebaseBillingError) throw error;
+        throw new FirebaseBillingError('Failed to sync subscription', 'sync-failed', error);
+      }
     },
 
     async getBillingHistory(userId: string): Promise<OrderItem[]> {
-      const result = await callable<{ userId: string }, { orders?: OrderItem[] }>(
-        callables.billing,
-        { userId },
-      );
-      return result.orders ?? [];
+      validateUserId(userId);
+
+      try {
+        const result = await callable<{ userId: string }, { orders?: OrderItem[] }>(
+          callables.billing,
+          { userId }
+        );
+        return result.orders ?? [];
+      } catch (error) {
+        if (error instanceof FirebaseBillingError) throw error;
+        // Return empty array on error instead of throwing
+        console.error('[FirebaseBilling] Failed to load billing history:', error);
+        return [];
+      }
     },
 
     async cancelSubscription(reason?: CancellationReason): Promise<CancelResult> {
-      return callable<{ reason?: string }, CancelResult>(callables.cancel, { reason });
+      try {
+        return await callable<{ reason?: string }, CancelResult>(callables.cancel, { reason });
+      } catch (error) {
+        if (error instanceof FirebaseBillingError) throw error;
+        throw new FirebaseBillingError('Failed to cancel subscription', 'cancel-failed', error);
+      }
     },
 
     async getPortalUrl(userId: string): Promise<string> {
-      const result = await callable<{ userId: string }, { url: string }>(
-        callables.portal,
-        { userId },
-      );
-      return result.url;
+      validateUserId(userId);
+
+      try {
+        const result = await callable<{ userId: string }, { url: string }>(
+          callables.portal,
+          { userId }
+        );
+
+        if (!result?.url || typeof result.url !== 'string') {
+          throw new FirebaseBillingError('Invalid portal URL returned', 'invalid-response');
+        }
+
+        return result.url;
+      } catch (error) {
+        if (error instanceof FirebaseBillingError) throw error;
+        throw new FirebaseBillingError('Failed to get customer portal URL', 'portal-failed', error);
+      }
     },
   };
 }

package/src/presentation/components/PolarProvider.tsx

@@ -79,17 +79,30 @@ export function PolarProvider({ adapter, userId, children }: PolarProviderProps)
     }
 
     const uid = userIdRef.current;
-    const result = await adapterRef.current.createCheckout({ ...params, userId: uid ?? undefined });
-
-    if (!isValidCheckoutUrl(result.url)) {
-      throw new Error('[polar-billing] Invalid checkout URL returned: URL must start with https:// or http://');
+    if (!uid) {
+      throw new Error('[polar-billing] Cannot start checkout: No authenticated user');
     }
 
-    if (isProductionInsecureUrl(result.url)) {
-      throw new Error('[polar-billing] ERROR: Using insecure http:// URL in production environment');
-    }
+    try {
+      const result = await adapterRef.current.createCheckout({ ...params, userId: uid });
+
+      if (!isValidCheckoutUrl(result.url)) {
+        throw new Error('[polar-billing] Invalid checkout URL returned: URL must start with https:// or http://');
+      }
+
+      if (isProductionInsecureUrl(result.url)) {
+        throw new Error('[polar-billing] ERROR: Using insecure http:// URL in production environment');
+      }
 
-    window.location.href = result.url;
+      // Navigate to checkout URL
+      window.location.href = result.url;
+    } catch (error) {
+      // Re-throw with additional context
+      if (error instanceof Error) {
+        throw new Error(`[polar-billing] Checkout failed: ${error.message}`);
+      }
+      throw error;
+    }
   }, []);
 
   const syncSubscription = useCallback(async (): Promise<SyncResult> => {