@payvia-sdk/sdk 1.1.4

package/README.md

@@ -0,0 +1,463 @@
+# PayVia SDK
+
+A lightweight JavaScript SDK for connecting your Chrome Extension / SaaS app to PayVia, for accepting PayPal payments and managing subscriptions, license validation, tier-based feature gating, trial management and monthly / yearly / lifetime plans.
+
+## Quick Start
+
+The `sample-extension` comes pre-configured with a shared demo project and works out of the box:
+
+1. Open `chrome://extensions/`
+2. Enable "Developer mode"
+3. Click "Load unpacked" and select the `sample-extension` folder
+4. Click the extension icon — everything works!
+
+> **Note:** The demo project is shared across all users and is meant for testing only.
+> To accept real payments, create your own project at [PayVia Dashboard](https://payvia.site/dashboard).
+
+## Installation
+
+### Option 1: Copy directly
+
+Copy `payvia.js` into your extension folder.
+
+### Option 2: npm
+
+```bash
+npm install payvia-sdk
+```
+
+## Basic Usage
+
+### 1. Add to manifest.json
+
+```json
+{
+  "manifest_version": 3,
+  "name": "Your Extension",
+  "permissions": ["storage"],
+  "host_permissions": [
+    "https://api.payvia.site/*",
+    "https://payvia.site/*"
+  ],
+  "background": {
+    "service_worker": "background.js"
+  }
+}
+```
+
+If using Google Identity for automatic user detection, also add:
+```json
+{
+  "permissions": ["storage", "identity", "identity.email"]
+}
+```
+
+### 2. Initialize in background.js
+
+```javascript
+import PayVia from './payvia.js';
+
+const payvia = PayVia('YOUR_API_KEY');
+
+// Check if user has paid
+chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
+  if (request.action === 'checkPaid') {
+    payvia.getUser().then(user => {
+      sendResponse({ paid: user.paid });
+    });
+    return true; // async response
+  }
+});
+```
+
+### 3. Check payment status
+
+```javascript
+const user = await payvia.getUser();
+
+if (user.paid) {
+  enablePremiumFeatures();
+} else {
+  showUpgradeButton();
+}
+```
+
+### 4. Open payment page
+
+```javascript
+// Option 1: Pricing page — shows all plans (recommended)
+await payvia.openPaymentPage({ mode: 'pricing', email: userEmail });
+
+// Option 2: Hosted checkout — specific plan
+await payvia.openPaymentPage({ mode: 'hosted', planId: 'your-plan-id', email: userEmail });
+
+// Option 3: Direct PayPal — no PayVia UI
+await payvia.openPaymentPage({ mode: 'direct', planId: 'your-plan-id', email: userEmail });
+```
+
+### 5. Listen for payment changes
+
+```javascript
+const unsubscribe = payvia.onPaid((user) => {
+  console.log('User just paid!', user);
+  enablePremiumFeatures();
+});
+
+// Call unsubscribe() to stop listening
+```
+
+---
+
+## Checkout Modes
+
+| Mode | Description | When to use |
+|------|-------------|-------------|
+| `pricing` | PayVia plan selection page | **Default** — when you have multiple plans |
+| `hosted` | PayVia checkout for a specific plan | When you have one plan or want to skip selection |
+| `direct` | Straight to PayPal, no PayVia UI | For developers who want full UI control |
+
+---
+
+## User Identity
+
+The SDK automatically identifies users:
+
+1. **Google Identity** — if the extension has the `identity` permission, uses the user's Google email
+2. **Random ID fallback** — generates a persistent `pv_`-prefixed UUID, synced via `chrome.storage.sync`
+
+```javascript
+const identity = await payvia.getIdentity();
+// { id: "user@gmail.com", email: "user@gmail.com", source: "google" }
+// or: { id: "pv_abc123...", email: null, source: "random" }
+```
+
+---
+
+## Tier-Based Feature Gating
+
+Tiers define feature sets (Free/Pro/Super). Plans are pricing options within tiers.
+
+```javascript
+// Check tier level (0=Free, 1=Pro, 2=Super)
+const hasPro = await payvia.hasTierLevel(1); // Pro or above
+
+// Check specific feature
+const canExport = await payvia.hasFeature('export_pdf');
+
+// Get full tier info
+const tier = await payvia.getTier();
+// { id: "...", name: "Pro", level: 1, features: ["export_pdf", "api_access"] }
+
+// Or via user object
+const user = await payvia.getUser();
+// user.tier — tier object
+// user.features — shortcut to user.tier.features
+```
+
+---
+
+## Trial Support
+
+```javascript
+// Start trial on first use (idempotent — safe to call multiple times)
+if (await payvia.isFirstRun()) {
+  const trial = await payvia.startTrial();
+  if (trial) {
+    console.log(`Trial started! ${trial.daysRemaining} days remaining`);
+    // { subscriptionId, status, planId, planName, trialExpiresAt, daysRemaining }
+  }
+  await payvia.markFirstRunDone();
+}
+
+// Check trial status
+const status = await payvia.getTrialStatus();
+// { status, trialExpiresAt, daysRemaining, canConvert, planIds }
+```
+
+Trial info is also available on the user object:
+
+```javascript
+const user = await payvia.getUser();
+// user.isTrial — boolean
+// user.trialExpiresAt — Date or null
+// user.daysRemaining — number or null
+```
+
+---
+
+## License Caching
+
+The SDK caches license data for offline resilience. No setup required — it works automatically.
+
+- **TTL**: 7 days (server-controlled)
+- **Grace period**: 30 days (allows offline access after TTL expires)
+- **Storage**: `chrome.storage.local` (extension) or `localStorage` (web)
+- **Anti-tamper**: HMAC-SHA256 signature verification
+
+```javascript
+// Refresh cache in background (e.g., service worker startup)
+chrome.runtime.onStartup.addListener(async () => {
+  await payvia.refreshLicenseCache();
+});
+
+// Check if data came from cache
+const user = await payvia.getUser();
+if (user.fromCache) {
+  // Using cached data — works offline
+}
+```
+
+---
+
+## API Reference
+
+### `PayVia(apiKey)`
+
+Creates a new PayVia instance.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `apiKey` | string | API key from the PayVia dashboard |
+
+---
+
+### `payvia.getUser(options?)`
+
+Returns the user's payment status and subscription info. Uses cache automatically.
+
+**Options:** `{ forceRefresh: boolean }`
+
+**Returns:** `Promise<PayViaUser>`
+
+```typescript
+interface PayViaUser {
+  id: string;                          // Unique user identifier
+  email: string | null;                // User email (if available)
+  identitySource: 'google' | 'random'; // Identity source
+  paid: boolean;                       // true if ACTIVE or TRIAL
+  status: 'ACTIVE' | 'TRIAL' | 'INACTIVE'; // Subscription status
+  tier: {                              // Current tier (or null)
+    id: string;
+    name: string;
+    level: number;                     // 0=Free, 1=Pro, 2=Super
+    features: string[];
+  } | null;
+  features: string[];                  // Shortcut to tier.features
+  planIds: string[];                   // Purchased plan IDs
+  isTrial: boolean;                    // Whether on trial
+  trialExpiresAt: Date | null;         // Trial expiration date
+  daysRemaining: number | null;        // Trial days remaining
+  fromCache: boolean;                  // true if data came from cache
+  checkedAt: number | null;            // Unix timestamp (ms)
+  ttl: number | null;                  // Cache TTL in ms
+  signature: string | null;            // HMAC anti-tamper signature
+}
+```
+
+---
+
+### `payvia.refresh()`
+
+Force-refreshes user status from the server (bypasses cache).
+
+**Returns:** `Promise<PayViaUser>`
+
+---
+
+### `payvia.refreshLicenseCache()`
+
+Refreshes the license cache if expired. Ideal for background service worker startup.
+
+**Returns:** `Promise<void>`
+
+---
+
+### `payvia.openPaymentPage(options)`
+
+Opens the payment page in a new tab.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `mode` | `'pricing' \| 'hosted' \| 'direct'` | No | Checkout mode (default: `pricing`) |
+| `planId` | string | For hosted/direct | Plan ID to purchase |
+| `email` | string | No | Customer email |
+| `successUrl` | string | For direct | Redirect URL after successful payment |
+| `cancelUrl` | string | For direct | Redirect URL if user cancels |
+
+**Returns:** `Promise<{ mode, pricingUrl? | checkoutUrl? }>`
+
+---
+
+### `payvia.onPaid(callback)`
+
+Listens for payment status changes (polls every 5 seconds).
+
+**Returns:** `Function` — call it to stop listening
+
+---
+
+### `payvia.hasFeature(name)`
+
+Checks if the user's tier includes a specific feature.
+
+**Returns:** `Promise<boolean>`
+
+---
+
+### `payvia.hasTierLevel(level)`
+
+Checks if the user's tier is at or above the required level.
+
+**Returns:** `Promise<boolean>`
+
+---
+
+### `payvia.getTier()`
+
+Returns the user's current tier info.
+
+**Returns:** `Promise<{ id, name, level, features } | null>`
+
+---
+
+### `payvia.getIdentity()`
+
+Returns the current user identity.
+
+**Returns:** `Promise<{ id: string, email: string | null, source: 'google' | 'random' }>`
+
+---
+
+### `payvia.needsEmailForPayment()`
+
+Checks if an email prompt is needed (user has no Google identity).
+
+**Returns:** `Promise<boolean>`
+
+---
+
+### `payvia.getPlans()`
+
+Returns available plans for the project.
+
+**Returns:** `Promise<Plan[]>`
+
+---
+
+### `payvia.startTrial()`
+
+Starts a trial for the current user. Idempotent — safe to call multiple times.
+
+**Returns:** `Promise<{ subscriptionId, status, planId, planName, trialExpiresAt, daysRemaining } | null>`
+
+---
+
+### `payvia.getTrialStatus()`
+
+Returns the trial status for the current user.
+
+**Returns:** `Promise<{ status, trialExpiresAt, daysRemaining, canConvert, planIds }>`
+
+---
+
+### `payvia.isFirstRun()`
+
+Checks if the extension is being used for the first time.
+
+**Returns:** `Promise<boolean>`
+
+---
+
+### `payvia.markFirstRunDone()`
+
+Marks the first run as complete.
+
+---
+
+### `payvia.cancelSubscription(options?)`
+
+Cancels the user's subscription.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `planId` | string | No | Specific plan to cancel |
+| `reason` | string | No | Cancellation reason |
+
+**Returns:** `Promise<{ success, message, canceledPlanId }>`
+
+---
+
+### `payvia.resetLicense()`
+
+Resets the user's license (for testing/demo purposes). Deletes all subscriptions for the current user.
+
+**Returns:** `Promise<{ message }>`
+
+---
+
+## Plan Description Format
+
+In the PayVia Dashboard, you can write plan descriptions with feature lists:
+
+```
+Everything in Free, plus:
++++Unlimited access
++++Priority support
++++Custom features
+Contact us for enterprise plans
+```
+
+Lines starting with `+++` are displayed with a green checkmark on checkout pages.
+
+---
+
+## Sample Extension
+
+See the `sample-extension/` folder for a working example that demonstrates:
+
+1. **Payment status check** — automatic user detection
+2. **Three checkout modes** — Pricing Page, Hosted Checkout, Direct PayPal
+3. **Feature-per-Plan** — each plan unlocks different features
+4. **Smart identity** — Google Identity and Random ID support
+5. **Reset demo** — button to reset license for repeated testing
+
+### Running the sample:
+
+1. Open `chrome://extensions/`
+2. Enable Developer mode
+3. Click "Load unpacked"
+4. Select the `sdk/sample-extension/` folder
+5. Click the extension icon
+
+---
+
+## FAQ
+
+### How is the user identified?
+
+PayVia uses `chrome.storage.sync` to create a unique ID that persists even if the user uninstalls the extension. If the user is signed into Chrome and you have the `identity` permission, identification uses their Google email instead.
+
+### What happens offline?
+
+The SDK uses cached license data with a 7-day TTL and 30-day grace period. During network outages within the grace period, the cached status is returned. If no valid cache exists, `getUser()` returns `{ paid: false, status: 'INACTIVE' }`.
+
+### What's the difference between checkout modes?
+
+- **pricing** — user sees all plans and picks one
+- **hosted** — user sees a styled checkout page for a specific plan
+- **direct** — user is sent straight to PayPal with no PayVia UI
+
+### How do I test in development?
+
+Use PayPal Sandbox credentials and PayPal Sandbox accounts.
+
+---
+
+## Resources
+
+- **Dashboard**: https://payvia.site
+- **API Base URL**: https://api.payvia.site
+- **Sample Extension**: `sample-extension/` in this repo
+- **Sample SaaS App**: `sample-saas/` in this repo
+- **MCP Server** (for AI agents): See [`mcp-server/`](mcp-server/) in this repo
+- **AI Agent Skill**: See [`skill.md`](skill.md) in this repo

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@payvia-sdk/sdk",
+  "version": "1.1.4",
+  "description": "A lightweight JavaScript SDK for connecting your Chrome Extension / SaaS app to PayVia, for accepting PayPal payments and managing subscriptions, license validation, tier-based feature gating, trial management and monthly / yearly / lifetime plans",
+  "main": "payvia.js",
+  "type": "module",
+  "exports": {
+    ".": "./payvia.js"
+  },
+  "files": [
+    "payvia.js",
+    "README.md"
+  ],
+  "keywords": [
+    "paypal",
+    "payments",
+    "chrome-extension",
+    "saas",
+    "subscriptions",
+    "monetization"
+  ],
+  "author": "PayVia",
+  "license": "MIT",
+  "homepage": "https://payvia.site",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Asia-Digital/PayVia-SDK.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Asia-Digital/PayVia-SDK/issues"
+  }
+}

package/payvia.js

@@ -0,0 +1,696 @@
+/**
+ * PayVia SDK for Chrome Extensions
+ * 
+ * ספריית JavaScript שהסולק מטמיע בתוסף הכרום שלו
+ * מאפשרת בדיקת רישיון, פתיחת חלון תשלום, וניהול מנויים
+ * 
+ * Usage:
+ * ```javascript
+ * import PayVia from './payvia.js';
+ * 
+ * const payvia = PayVia('YOUR_API_KEY');
+ * 
+ * // Check if user paid
+ * const user = await payvia.getUser();
+ * if (user.paid) {
+ *   // Enable premium features
+ * }
+ * 
+ * // Open payment page
+ * payvia.openPaymentPage();
+ * ```
+ */
+
+function PayVia(apiKey) {
+    if (!apiKey) {
+        throw new Error('PayVia: API key is required');
+    }
+
+    const PAYVIA_API_URL = 'https://api.payvia.site';
+
+    const LICENSE_CACHE_KEY = 'payvia_license_cache';
+    const DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+    const GRACE_PERIOD_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+
+    const instance = {};
+    let cachedUser = null;
+    let userPromise = null;
+
+    // ============ License Cache Storage ============
+
+    /**
+     * Get storage interface (chrome.storage.local or localStorage)
+     */
+    function getStorage() {
+        if (typeof chrome !== 'undefined' && chrome.storage && chrome.storage.local) {
+            return {
+                async get(key) {
+                    return new Promise(resolve => {
+                        chrome.storage.local.get([key], result => resolve(result[key]));
+                    });
+                },
+                async set(key, value) {
+                    return new Promise(resolve => {
+                        chrome.storage.local.set({ [key]: value }, resolve);
+                    });
+                }
+            };
+        }
+        // Fallback to localStorage
+        return {
+            async get(key) {
+                const value = localStorage.getItem(key);
+                return value ? JSON.parse(value) : null;
+            },
+            async set(key, value) {
+                localStorage.setItem(key, JSON.stringify(value));
+            }
+        };
+    }
+
+    /**
+     * Get cached license data
+     */
+    async function getCachedLicense() {
+        try {
+            const storage = getStorage();
+            return await storage.get(LICENSE_CACHE_KEY);
+        } catch (error) {
+            console.warn('PayVia: Failed to read license cache', error);
+            return null;
+        }
+    }
+
+    /**
+     * Save license data to cache
+     */
+    async function setCachedLicense(data) {
+        try {
+            const storage = getStorage();
+            await storage.set(LICENSE_CACHE_KEY, data);
+        } catch (error) {
+            console.warn('PayVia: Failed to write license cache', error);
+        }
+    }
+
+    /**
+     * Check if cache is still valid (within TTL)
+     */
+    function isCacheValid(cache) {
+        if (!cache || !cache.checkedAt) return false;
+        const ttl = cache.ttl || DEFAULT_TTL_MS;
+        return Date.now() < cache.checkedAt + ttl;
+    }
+
+    /**
+     * Check if cache is within grace period (expired but still usable offline)
+     */
+    function isWithinGracePeriod(cache) {
+        if (!cache || !cache.checkedAt) return false;
+        const ttl = cache.ttl || DEFAULT_TTL_MS;
+        return Date.now() < cache.checkedAt + ttl + GRACE_PERIOD_MS;
+    }
+
+    let cachedIdentity = null; // Stores { id, email, source }
+
+    /**
+     * Try to get the user's Google account email via chrome.identity
+     * @returns {Promise<{email: string, source: 'google'} | null>}
+     */
+    async function getGoogleIdentity() {
+        return new Promise((resolve) => {
+            if (typeof chrome !== 'undefined' && chrome.identity && chrome.identity.getProfileUserInfo) {
+                chrome.identity.getProfileUserInfo({ accountStatus: 'ANY' }, (userInfo) => {
+                    if (chrome.runtime.lastError) {
+                        console.log('PayVia: Could not get Google identity:', chrome.runtime.lastError.message);
+                        resolve(null);
+                        return;
+                    }
+                    if (userInfo && userInfo.email) {
+                        resolve({ email: userInfo.email, source: 'google' });
+                    } else {
+                        resolve(null);
+                    }
+                });
+            } else {
+                resolve(null);
+            }
+        });
+    }
+
+    /**
+     * Get or generate a random fallback ID
+     * Uses chrome.storage.sync to persist across devices
+     * @returns {Promise<string>}
+     */
+    async function getRandomId() {
+        return new Promise((resolve) => {
+            if (typeof chrome !== 'undefined' && chrome.storage && chrome.storage.sync) {
+                chrome.storage.sync.get(['payvia_user_id'], (result) => {
+                    if (result.payvia_user_id) {
+                        resolve(result.payvia_user_id);
+                    } else {
+                        const newUserId = 'pv_' + generateUUID();
+                        chrome.storage.sync.set({ payvia_user_id: newUserId }, () => {
+                            resolve(newUserId);
+                        });
+                    }
+                });
+            } else {
+                // Fallback for non-extension environments (testing)
+                let userId = localStorage.getItem('payvia_user_id');
+                if (!userId) {
+                    userId = 'pv_' + generateUUID();
+                    localStorage.setItem('payvia_user_id', userId);
+                }
+                resolve(userId);
+            }
+        });
+    }
+
+    /**
+     * Get user identity - tries Google first, falls back to random ID
+     * @returns {Promise<{id: string, email: string | null, source: 'google' | 'random'}>}
+     */
+    async function getUserIdentity() {
+        if (cachedIdentity) {
+            return cachedIdentity;
+        }
+
+        // Try Google Identity first
+        const googleInfo = await getGoogleIdentity();
+        if (googleInfo && googleInfo.email) {
+            cachedIdentity = {
+                id: googleInfo.email,
+                email: googleInfo.email,
+                source: 'google'
+            };
+            console.log('PayVia: Using Google identity:', cachedIdentity.email);
+            return cachedIdentity;
+        }
+
+        // Fall back to random ID
+        const randomId = await getRandomId();
+        cachedIdentity = {
+            id: randomId,
+            email: null,
+            source: 'random'
+        };
+        console.log('PayVia: Using random identity:', cachedIdentity.id);
+        return cachedIdentity;
+    }
+
+    /**
+     * Generate UUID v4
+     */
+    function generateUUID() {
+        return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+            const r = Math.random() * 16 | 0;
+            const v = c === 'x' ? r : (r & 0x3 | 0x8);
+            return v.toString(16);
+        });
+    }
+
+    /**
+     * Make API request to PayVia server
+     */
+    async function apiRequest(endpoint, options = {}) {
+        const response = await fetch(`${PAYVIA_API_URL}${endpoint}`, {
+            ...options,
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-Key': apiKey,
+                ...options.headers,
+            },
+        });
+
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: 'Request failed' }));
+            throw new Error(error.error || 'PayVia API request failed');
+        }
+
+        return response.json();
+    }
+
+    /**
+     * Get user's payment status
+     * Uses cache first, then server. Falls back to cache during network errors.
+     * @param {Object} options - Options
+     * @param {boolean} options.forceRefresh - Force fetch from server
+     * @returns {Promise<PayViaUser>} User object with payment status
+     */
+    instance.getUser = async function (options = {}) {
+        const identity = await getUserIdentity();
+
+        // Check in-memory cache first
+        if (cachedUser && !options.forceRefresh) {
+            return cachedUser;
+        }
+
+        if (userPromise) {
+            return userPromise;
+        }
+
+        userPromise = (async () => {
+            try {
+                // Check persistent cache
+                if (!options.forceRefresh) {
+                    const cached = await getCachedLicense();
+                    if (cached && isCacheValid(cached)) {
+                        cachedUser = buildUserFromCache(identity, cached, true);
+                        return cachedUser;
+                    }
+                }
+
+                // Fetch from server
+                const response = await apiRequest('/api/v1/license/validate', {
+                    method: 'POST',
+                    body: JSON.stringify({ customerId: identity.id, email: identity.email }),
+                });
+
+                // Save to cache
+                const cacheData = {
+                    status: response.status,
+                    planIds: response.planIds || [],
+                    tier: response.tier || null,
+                    isTrial: response.isTrial || false,
+                    trialExpiresAt: response.trialExpiresAt || null,
+                    daysRemaining: response.daysRemaining || null,
+                    checkedAt: response.checkedAt || Date.now(),
+                    ttl: response.ttl || DEFAULT_TTL_MS,
+                    signature: response.signature || null,
+                    version: response.version || null,
+                };
+                await setCachedLicense(cacheData);
+
+                cachedUser = buildUserFromCache(identity, cacheData, false);
+                return cachedUser;
+            } catch (error) {
+                console.error('PayVia: Failed to get user status', error);
+
+                // Try to use cached data if within grace period
+                const cached = await getCachedLicense();
+                if (cached && isWithinGracePeriod(cached)) {
+                    console.log('PayVia: Using cached license (network error, within grace period)');
+                    cachedUser = buildUserFromCache(identity, cached, true);
+                    return cachedUser;
+                }
+
+                // No valid cache, return inactive
+                return {
+                    id: identity.id,
+                    email: identity.email,
+                    identitySource: identity.source,
+                    paid: false,
+                    status: 'INACTIVE',
+                    tier: null,
+                    features: [],
+                    planIds: [],
+                    isTrial: false,
+                    fromCache: false,
+                    error: error.message,
+                };
+            } finally {
+                userPromise = null;
+            }
+        })();
+
+        return userPromise;
+    };
+
+    /**
+     * Build user object from cache data
+     */
+    function buildUserFromCache(identity, cache, fromCache) {
+        return {
+            id: identity.id,
+            email: identity.email,
+            identitySource: identity.source,
+            paid: cache.status === 'ACTIVE' || cache.status === 'TRIAL',
+            status: cache.status,
+            tier: cache.tier || null,
+            features: cache.tier?.features || [],
+            planIds: cache.planIds || [],
+            isTrial: cache.isTrial || false,
+            trialExpiresAt: cache.trialExpiresAt ? new Date(cache.trialExpiresAt) : null,
+            daysRemaining: cache.daysRemaining || null,
+            fromCache: fromCache,
+            checkedAt: cache.checkedAt || null,
+            ttl: cache.ttl || null,
+            signature: cache.signature || null,
+        };
+    }
+
+    /**
+     * Force refresh user status from server
+     * @returns {Promise<PayViaUser>} Updated user object
+     */
+    instance.refresh = async function () {
+        cachedUser = null;
+        return instance.getUser({ forceRefresh: true });
+    };
+
+    /**
+     * Refresh license cache from server (for background refresh)
+     * @returns {Promise<void>}
+     */
+    instance.refreshLicenseCache = async function () {
+        const cached = await getCachedLicense();
+        if (!cached || !isCacheValid(cached)) {
+            await instance.refresh();
+        }
+    };
+
+    /**
+     * Check if user has a specific feature
+     * @param {string} featureName - Feature name to check
+     * @returns {Promise<boolean>}
+     */
+    instance.hasFeature = async function (featureName) {
+        const user = await instance.getUser();
+        if (!user.tier || !user.tier.features) return false;
+        return user.tier.features.includes(featureName);
+    };
+
+    /**
+     * Check if user has a tier at or above the required level
+     * @param {number} requiredLevel - Minimum tier level required
+     * @returns {Promise<boolean>}
+     */
+    instance.hasTierLevel = async function (requiredLevel) {
+        const user = await instance.getUser();
+        if (!user.tier) return false;
+        return user.tier.level >= requiredLevel;
+    };
+
+    /**
+     * Get the user's current tier info
+     * @returns {Promise<{id: string, name: string, level: number, features: string[]}|null>}
+     */
+    instance.getTier = async function () {
+        const user = await instance.getUser();
+        return user.tier || null;
+    };
+
+    /**
+     * Start a trial for the current user
+     * Call this when user first installs/uses the extension
+     * Idempotent: if user already has a trial/active subscription, returns existing info
+     * @returns {Promise<{subscriptionId: string, status: string, planId: string, planName: string, trialExpiresAt: Date, daysRemaining: number} | null>}
+     */
+    instance.startTrial = async function () {
+        try {
+            const identity = await getUserIdentity();
+            const response = await apiRequest('/api/v1/trial/start', {
+                method: 'POST',
+                body: JSON.stringify({
+                    customerId: identity.id,
+                    email: identity.email,
+                }),
+            });
+
+            // Clear cached user so next getUser() fetches fresh data
+            cachedUser = null;
+
+            return {
+                subscriptionId: response.subscriptionId,
+                status: response.status,
+                planId: response.planId,
+                planName: response.planName,
+                trialExpiresAt: new Date(response.trialExpiresAt),
+                daysRemaining: response.daysRemaining,
+            };
+        } catch (error) {
+            console.log('PayVia: Could not start trial:', error.message);
+            return null;
+        }
+    };
+
+    /**
+     * Get trial status for the current user
+     * @returns {Promise<{status: string, trialExpiresAt: Date | null, daysRemaining: number | null, canConvert: boolean, planIds: string[]}>}
+     */
+    instance.getTrialStatus = async function () {
+        try {
+            const identity = await getUserIdentity();
+            const response = await apiRequest('/api/v1/trial/status', {
+                method: 'POST',
+                body: JSON.stringify({ customerId: identity.id }),
+            });
+
+            return {
+                status: response.status,
+                trialExpiresAt: response.trialExpiresAt ? new Date(response.trialExpiresAt) : null,
+                daysRemaining: response.daysRemaining || null,
+                canConvert: response.canConvert,
+                planIds: response.planIds || [],
+            };
+        } catch (error) {
+            console.error('PayVia: Failed to get trial status', error);
+            return {
+                status: 'UNKNOWN',
+                trialExpiresAt: null,
+                daysRemaining: null,
+                canConvert: true,
+                planIds: [],
+            };
+        }
+    };
+
+    /**
+     * Check if this is the first time the extension is being used
+     * @returns {Promise<boolean>}
+     */
+    instance.isFirstRun = async function () {
+        return new Promise((resolve) => {
+            if (typeof chrome !== 'undefined' && chrome.storage && chrome.storage.local) {
+                chrome.storage.local.get(['payvia_first_run_done'], (result) => {
+                    resolve(!result.payvia_first_run_done);
+                });
+            } else {
+                resolve(!localStorage.getItem('payvia_first_run_done'));
+            }
+        });
+    };
+
+    /**
+     * Mark first run as complete
+     */
+    instance.markFirstRunDone = async function () {
+        return new Promise((resolve) => {
+            if (typeof chrome !== 'undefined' && chrome.storage && chrome.storage.local) {
+                chrome.storage.local.set({ payvia_first_run_done: true }, resolve);
+            } else {
+                localStorage.setItem('payvia_first_run_done', 'true');
+                resolve();
+            }
+        });
+    };
+
+    /**
+     * Check if email is required for payment (user has no Google identity)
+     * @returns {Promise<boolean>}
+     */
+    instance.needsEmailForPayment = async function () {
+        const identity = await getUserIdentity();
+        return identity.source === 'random';
+    };
+
+    /**
+     * Get the current user identity info
+     * @returns {Promise<{id: string, email: string | null, source: 'google' | 'random'}>}
+     */
+    instance.getIdentity = async function () {
+        return getUserIdentity();
+    };
+
+    /**
+     * Open payment page for the user
+     * @param {Object} options - Payment options
+     * @param {string} options.planId - Plan ID to purchase (required for direct/hosted modes)
+     * @param {string} options.email - Customer email
+     * @param {'pricing'|'hosted'|'direct'} options.mode - Checkout mode:
+     *   - 'pricing': Shows all plans for user to choose (default, most secure)
+     *   - 'hosted': Goes directly to checkout for specific plan
+     *   - 'direct': Bypasses PayVia, goes straight to PayPal
+     * @param {string} options.successUrl - URL to redirect after successful payment (direct mode only)
+     * @param {string} options.cancelUrl - URL to redirect if user cancels (direct mode only)
+     */
+    instance.openPaymentPage = async function (options = {}) {
+        const identity = await getUserIdentity();
+        const customerEmail = options.email || identity.email;
+        const mode = options.mode || 'pricing';
+
+        const PAYVIA_BASE_URL = 'https://payvia.site';
+
+        if (mode === 'pricing') {
+            // Pricing mode: Get secure token, show all plans
+            if (!customerEmail) {
+                throw new Error('Email is required for payment. Please provide an email address.');
+            }
+
+            const tokenResponse = await apiRequest('/api/v1/checkout/token', {
+                method: 'POST',
+                body: JSON.stringify({
+                    customerId: identity.id,
+                    customerEmail: customerEmail,
+                    mode: 'pricing',
+                }),
+            });
+
+            const pricingUrl = `${PAYVIA_BASE_URL}/pricing?token=${encodeURIComponent(tokenResponse.token)}`;
+
+            if (typeof chrome !== 'undefined' && chrome.tabs) {
+                chrome.tabs.create({ url: pricingUrl });
+            } else {
+                window.open(pricingUrl, '_blank');
+            }
+
+            return { mode: 'pricing', pricingUrl };
+        } else if (mode === 'hosted') {
+            // Hosted mode: Get secure token, go to specific plan checkout
+            if (!options.planId) {
+                throw new Error('planId is required for hosted mode');
+            }
+            if (!customerEmail) {
+                throw new Error('Email is required for payment. Please provide an email address.');
+            }
+
+            const tokenResponse = await apiRequest('/api/v1/checkout/token', {
+                method: 'POST',
+                body: JSON.stringify({
+                    customerId: identity.id,
+                    customerEmail: customerEmail,
+                    planId: options.planId,
+                    mode: 'checkout',
+                }),
+            });
+
+            const checkoutUrl = `${PAYVIA_BASE_URL}/checkout?token=${encodeURIComponent(tokenResponse.token)}`;
+
+            if (typeof chrome !== 'undefined' && chrome.tabs) {
+                chrome.tabs.create({ url: checkoutUrl });
+            } else {
+                window.open(checkoutUrl, '_blank');
+            }
+
+            return { mode: 'hosted', checkoutUrl };
+        } else {
+            // Direct mode: Call API and redirect straight to PayPal (original behavior)
+            if (!options.planId) {
+                throw new Error('planId is required for direct mode');
+            }
+
+            try {
+                const response = await apiRequest('/api/v1/checkout-session', {
+                    method: 'POST',
+                    body: JSON.stringify({
+                        planId: options.planId,
+                        customerId: identity.id,
+                        customerEmail: customerEmail || '',
+                        successUrl: options.successUrl || 'https://payvia.site/success',
+                        cancelUrl: options.cancelUrl || 'https://payvia.site/cancel',
+                    }),
+                });
+
+                // Open PayPal checkout in new tab
+                if (response.checkoutUrl) {
+                    if (typeof chrome !== 'undefined' && chrome.tabs) {
+                        chrome.tabs.create({ url: response.checkoutUrl });
+                    } else {
+                        window.open(response.checkoutUrl, '_blank');
+                    }
+                }
+
+                return response;
+            } catch (error) {
+                console.error('PayVia: Failed to open payment page', error);
+                throw error;
+            }
+        }
+    };
+
+    /**
+     * Listen for payment status changes
+     * @param {Function} callback - Called when payment status changes
+     */
+    instance.onPaid = function (callback) {
+        // Poll for status changes every 5 seconds when tab is visible
+        let lastPaidStatus = null;
+
+        const checkStatus = async () => {
+            const user = await instance.refresh();
+            if (lastPaidStatus !== null && lastPaidStatus !== user.paid) {
+                callback(user);
+            }
+            lastPaidStatus = user.paid;
+        };
+
+        // Check immediately
+        checkStatus();
+
+        // Set up polling
+        const intervalId = setInterval(checkStatus, 5000);
+
+        // Return cleanup function
+        return () => clearInterval(intervalId);
+    };
+
+    /**
+     * Get available plans for this project
+     * @returns {Promise<Plan[]>} List of available plans
+     */
+    instance.getPlans = async function () {
+        try {
+            const response = await apiRequest('/api/v1/plans');
+            return response;
+        } catch (error) {
+            console.error('PayVia: Failed to get plans', error);
+            return [];
+        }
+    };
+
+    /**
+     * Reset the user's license (delete all subscriptions).
+     * This is for demo/testing purposes only.
+     * @returns {Promise<{message: string}>}
+     */
+    instance.resetLicense = async function () {
+        const identity = await getUserIdentity();
+        const response = await apiRequest('/api/v1/license/reset', {
+            method: 'POST',
+            body: JSON.stringify({ customerId: identity.id }),
+        });
+        cachedUser = null;
+        return response;
+    };
+
+    /**
+     * Cancel a subscription for the current user
+     * @param {Object} options - Cancel options
+     * @param {string} options.planId - Specific plan to cancel (optional)
+     * @param {string} options.reason - Cancellation reason (optional)
+     * @returns {Promise<{success: boolean, message: string, canceledPlanId: string}>}
+     */
+    instance.cancelSubscription = async function (options = {}) {
+        const identity = await getUserIdentity();
+
+        const response = await apiRequest('/api/v1/license/cancel', {
+            method: 'POST',
+            body: JSON.stringify({
+                customerId: identity.id,
+                planId: options.planId || null,
+                reason: options.reason || 'User requested cancellation',
+            }),
+        });
+
+        // Clear cached user so next getUser() fetches fresh data
+        cachedUser = null;
+
+        return response;
+    };
+
+    return instance;
+}
+
+export default PayVia;