@tagadapay/plugin-sdk 2.7.0 → 2.7.2

package/dist/react/hooks/usePluginConfig.js

@@ -105,15 +105,16 @@ const loadLocalDevConfig = async (configVariant = 'default') => {
     }
 };
 /**
- * Load production config from headers and meta tags
+ * Load production config from meta tags
+ * Meta tags are injected by the plugin middleware during HTML serving
+ * This avoids making an additional HEAD request (~300ms savings)
  */
 const loadProductionConfig = async () => {
     try {
-        // Get headers
-        const response = await fetch(window.location.href, { method: 'HEAD' });
-        const storeId = response.headers.get('X-Plugin-Store-Id') || undefined;
-        const accountId = response.headers.get('X-Plugin-Account-Id') || undefined;
-        const basePath = response.headers.get('X-Plugin-Base-Path') || '/';
+        // Read store/account info from meta tags (injected by middleware)
+        const storeId = document.querySelector('meta[name="x-plugin-store-id"]')?.getAttribute('content') || undefined;
+        const accountId = document.querySelector('meta[name="x-plugin-account-id"]')?.getAttribute('content') || undefined;
+        const basePath = document.querySelector('meta[name="x-plugin-base-path"]')?.getAttribute('content') || '/';
         // Get deployment config from meta tags
         let config = {};
         try {
@@ -127,9 +128,16 @@ const loadProductionConfig = async () => {
         catch {
             // Deployment config is optional
         }
+        console.log('🚀 Plugin config loaded from meta tags (no HEAD request needed):', {
+            storeId,
+            accountId,
+            basePath,
+            configKeys: Object.keys(config)
+        });
         return { storeId, accountId, basePath, config };
     }
-    catch {
+    catch (error) {
+        console.warn('⚠️ Failed to load plugin config from meta tags:', error);
         return { basePath: '/', config: {} };
     }
 };

package/dist/v2/core/index.d.ts

@@ -4,5 +4,6 @@
  */
 export * from './utils';
 export * from './resources';
+export * from './pathRemapping';
 export * from './googleAutocomplete';
 export * from './isoData';

package/dist/v2/core/index.js

@@ -6,6 +6,8 @@
 export * from './utils';
 // Export resources (axios-based API clients)
 export * from './resources';
+// Export path remapping helpers (framework-agnostic)
+export * from './pathRemapping';
 // Export legacy files that are still needed
 export * from './googleAutocomplete';
 export * from './isoData';

package/dist/v2/core/pathRemapping.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Path Remapping Helpers - Production Ready
+ *
+ * Framework-agnostic utility for handling path remapping from TagadaPay routing
+ * Includes error handling, SSR compatibility, performance optimizations, and edge case handling
+ *
+ * @packageDocumentation
+ */
+/**
+ * Path information including both external and internal paths
+ */
+export interface PathInfo {
+    /** The path shown in the browser URL bar (external/remapped path) */
+    externalPath: string;
+    /** The path that the plugin expects (internal/original path) */
+    internalPath: string | null;
+    /** Whether path remapping is active */
+    isRemapped: boolean;
+    /** The full URL including protocol, host, query, and hash */
+    fullUrl: string;
+    /** Query parameters from the URL */
+    query: URLSearchParams;
+    /** URL hash without the # symbol */
+    hash: string;
+}
+/**
+ * Get the internal path that the plugin expects
+ *
+ * Reads from the meta tag injected by TagadaPay middleware.
+ * Results are cached for performance.
+ *
+ * @returns The internal path from meta tag, or null if no remapping is active
+ * @throws {Error} If called in a non-browser environment (SSR)
+ *
+ * @example
+ * ```typescript
+ * const internalPath = getInternalPath();
+ * if (internalPath) {
+ *   console.log('Remapped from external to:', internalPath);
+ * }
+ * ```
+ */
+export declare function getInternalPath(): string | null;
+/**
+ * Check if path remapping is currently active
+ *
+ * @returns true if a remapped path is configured, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isPathRemapped()) {
+ *   console.log('User is viewing a remapped URL');
+ * }
+ * ```
+ */
+export declare function isPathRemapped(): boolean;
+/**
+ * Get comprehensive path mapping information
+ *
+ * Returns both the external (browser) path and internal (plugin) path,
+ * along with query parameters and hash.
+ *
+ * @returns {PathInfo} Complete path information object
+ * @throws {Error} If called in a non-browser environment (SSR)
+ *
+ * @example
+ * ```typescript
+ * const pathInfo = getPathInfo();
+ * console.log('Browser shows:', pathInfo.externalPath);
+ * console.log('Plugin expects:', pathInfo.internalPath);
+ * console.log('Query params:', pathInfo.query.get('id'));
+ * ```
+ */
+export declare function getPathInfo(): PathInfo;
+export declare function shouldMatchRoute(internalPath: string): boolean;
+/**
+ * Get the current matched path
+ *
+ * Returns the actual path in the browser if it matches the given internal path.
+ * Useful when you need the actual URL path for constructing links or API calls.
+ *
+ * @param internalPath - The plugin's defined path
+ * @returns The current browser path if it matches, null otherwise
+ *
+ * @example
+ * ```typescript
+ * const matchedPath = getMatchedPath('/hello');
+ * if (matchedPath) {
+ *   console.log('Matched at:', matchedPath); // Could be /hello or /hello2
+ * }
+ * ```
+ */
+export declare function getMatchedPath(internalPath: string): string | null;
+/**
+ * Manually clear the internal path cache
+ *
+ * Useful for testing or when you know the meta tag has changed.
+ * Normally you don't need to call this as it's handled automatically.
+ *
+ * @example
+ * ```typescript
+ * // After dynamically updating the meta tag
+ * document.querySelector('meta[name="x-plugin-internal-path"]')
+ *   ?.setAttribute('content', '/new-path');
+ * clearInternalPathCache();
+ * ```
+ */
+export declare function clearInternalPathCache(): void;
+/**
+ * Check if running in a browser environment
+ *
+ * Useful for conditional logic in universal/isomorphic code.
+ *
+ * @returns true if in browser, false if in SSR/Node environment
+ *
+ * @example
+ * ```typescript
+ * if (isBrowserEnvironment()) {
+ *   // Safe to use window/document
+ *   const path = getInternalPath();
+ * }
+ * ```
+ */
+export declare function isBrowserEnvironment(): boolean;
+/**
+ * Get debug information about the current routing state
+ *
+ * Returns detailed information for debugging path remapping issues.
+ * Only available in development mode.
+ *
+ * @returns Debug information object
+ *
+ * @example
+ * ```typescript
+ * const debug = getDebugInfo();
+ * console.table(debug);
+ * ```
+ */
+export declare function getDebugInfo(): Record<string, any>;
+/**
+ * Cleanup function to remove event listeners
+ *
+ * Call this when unmounting the plugin or cleaning up resources.
+ * Important for preventing memory leaks in SPAs.
+ *
+ * @example
+ * ```typescript
+ * // In React
+ * useEffect(() => {
+ *   return () => {
+ *     cleanupPathRemapping();
+ *   };
+ * }, []);
+ * ```
+ */
+export declare function cleanupPathRemapping(): void;

package/dist/v2/core/pathRemapping.js

@@ -0,0 +1,440 @@
+/**
+ * Path Remapping Helpers - Production Ready
+ *
+ * Framework-agnostic utility for handling path remapping from TagadaPay routing
+ * Includes error handling, SSR compatibility, performance optimizations, and edge case handling
+ *
+ * @packageDocumentation
+ */
+// ============================================================================
+// Private Cache
+// ============================================================================
+/**
+ * Cache for internal path lookup to avoid repeated DOM queries
+ * Cleared on navigation events
+ */
+let internalPathCache = undefined;
+/**
+ * Flag to check if we're in a browser environment
+ * Prevents errors during SSR
+ */
+const isBrowser = typeof window !== 'undefined' && typeof document !== 'undefined';
+/**
+ * Store original history methods for cleanup
+ */
+const originalPushState = isBrowser ? history.pushState.bind(history) : null;
+const originalReplaceState = isBrowser ? history.replaceState.bind(history) : null;
+/**
+ * Clear the internal path cache
+ * Called automatically on navigation events
+ */
+function clearCache() {
+    internalPathCache = undefined;
+}
+// Setup cache invalidation on navigation (only in browser)
+if (isBrowser) {
+    // Clear cache on history navigation
+    window.addEventListener('popstate', clearCache);
+    // Clear cache on hash change
+    window.addEventListener('hashchange', clearCache);
+    // Intercept pushState and replaceState to clear cache
+    history.pushState = function (...args) {
+        clearCache();
+        return originalPushState.apply(this, args);
+    };
+    history.replaceState = function (...args) {
+        clearCache();
+        return originalReplaceState.apply(this, args);
+    };
+}
+// ============================================================================
+// Core Functions
+// ============================================================================
+/**
+ * Get the internal path that the plugin expects
+ *
+ * Reads from the meta tag injected by TagadaPay middleware.
+ * Results are cached for performance.
+ *
+ * @returns The internal path from meta tag, or null if no remapping is active
+ * @throws {Error} If called in a non-browser environment (SSR)
+ *
+ * @example
+ * ```typescript
+ * const internalPath = getInternalPath();
+ * if (internalPath) {
+ *   console.log('Remapped from external to:', internalPath);
+ * }
+ * ```
+ */
+export function getInternalPath() {
+    // SSR check
+    if (!isBrowser) {
+        if (typeof process !== 'undefined' && process.env.NODE_ENV === 'development') {
+            console.warn('[TagadaPay SDK] getInternalPath() called in SSR context');
+        }
+        return null;
+    }
+    // Return cached value if available
+    if (internalPathCache !== undefined) {
+        return internalPathCache;
+    }
+    try {
+        // Query the meta tag
+        const metaTag = document.querySelector('meta[name="x-plugin-internal-path"]');
+        if (!metaTag) {
+            internalPathCache = null;
+            return null;
+        }
+        // Get and validate the content
+        const content = metaTag.getAttribute('content');
+        if (!content || content.trim() === '') {
+            if (typeof process !== 'undefined' && process.env.NODE_ENV === 'development') {
+                console.warn('[TagadaPay SDK] Meta tag found but content is empty');
+            }
+            internalPathCache = null;
+            return null;
+        }
+        // Validate path format
+        const trimmedContent = content.trim();
+        if (!trimmedContent.startsWith('/')) {
+            if (typeof process !== 'undefined' && process.env.NODE_ENV === 'development') {
+                console.warn(`[TagadaPay SDK] Invalid internal path format: "${trimmedContent}" (must start with /)`);
+            }
+            internalPathCache = null;
+            return null;
+        }
+        // Cache and return
+        internalPathCache = trimmedContent;
+        return trimmedContent;
+    }
+    catch (error) {
+        // Log error in development
+        if (typeof process !== 'undefined' && process.env.NODE_ENV === 'development') {
+            console.error('[TagadaPay SDK] Error reading internal path:', error);
+        }
+        internalPathCache = null;
+        return null;
+    }
+}
+/**
+ * Check if path remapping is currently active
+ *
+ * @returns true if a remapped path is configured, false otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isPathRemapped()) {
+ *   console.log('User is viewing a remapped URL');
+ * }
+ * ```
+ */
+export function isPathRemapped() {
+    return getInternalPath() !== null;
+}
+/**
+ * Get comprehensive path mapping information
+ *
+ * Returns both the external (browser) path and internal (plugin) path,
+ * along with query parameters and hash.
+ *
+ * @returns {PathInfo} Complete path information object
+ * @throws {Error} If called in a non-browser environment (SSR)
+ *
+ * @example
+ * ```typescript
+ * const pathInfo = getPathInfo();
+ * console.log('Browser shows:', pathInfo.externalPath);
+ * console.log('Plugin expects:', pathInfo.internalPath);
+ * console.log('Query params:', pathInfo.query.get('id'));
+ * ```
+ */
+export function getPathInfo() {
+    // SSR check
+    if (!isBrowser) {
+        throw new Error('[TagadaPay SDK] getPathInfo() cannot be called in SSR context');
+    }
+    try {
+        const externalPath = window.location.pathname;
+        const internalPath = getInternalPath();
+        const query = new URLSearchParams(window.location.search);
+        const hash = window.location.hash.replace(/^#/, '');
+        return {
+            externalPath,
+            internalPath,
+            isRemapped: internalPath !== null,
+            fullUrl: window.location.href,
+            query,
+            hash,
+        };
+    }
+    catch (error) {
+        // Fallback to safe defaults
+        if (typeof process !== 'undefined' && process.env.NODE_ENV === 'development') {
+            console.error('[TagadaPay SDK] Error getting path info:', error);
+        }
+        return {
+            externalPath: '/',
+            internalPath: null,
+            isRemapped: false,
+            fullUrl: '',
+            query: new URLSearchParams(),
+            hash: '',
+        };
+    }
+}
+/**
+ * Check if the current URL should match a given internal path
+ *
+ * Handles path remapping automatically. Use this for catch-all routing
+ * implementations where you need to check multiple paths.
+ *
+ * @param internalPath - The plugin's defined path (must start with /)
+ * @returns true if current URL should render this path's component
+ * @throws {Error} If internalPath is invalid
+ *
+ * @example
+ * ```typescript
+ * // In a catch-all route handler
+ * if (shouldMatchRoute('/hello')) {
+ *   return <HelloPage />;
+ * }
+ * if (shouldMatchRoute('/about')) {
+ *   return <AboutPage />;
+ * }
+ * ```
+ */
+/**
+ * Helper function to match a path against a pattern using path-to-regexp
+ * @param pathname - The actual path to test
+ * @param pattern - The pattern to match against (can include :params)
+ * @returns true if the path matches the pattern
+ */
+function matchesPathPattern(pathname, pattern) {
+    try {
+        // Exact match (no pattern)
+        if (pathname === pattern) {
+            return true;
+        }
+        // Check if pattern contains parameters (e.g., :id, :name)
+        if (!pattern.includes(':')) {
+            // No parameters - use simple prefix matching
+            return pathname.startsWith(pattern);
+        }
+        // Use path-to-regexp for parameterized patterns
+        // Import dynamically to avoid bundle size issues
+        const { match } = require('path-to-regexp');
+        const matchFn = match(pattern, { decode: decodeURIComponent, end: false });
+        const result = matchFn(pathname);
+        return result !== false;
+    }
+    catch (error) {
+        // Fallback to exact match if path-to-regexp fails
+        if (typeof process !== 'undefined' && process.env.NODE_ENV === 'development') {
+            console.warn(`[TagadaPay SDK] Pattern matching failed for "${pattern}":`, error);
+        }
+        return pathname === pattern || pathname.startsWith(pattern);
+    }
+}
+export function shouldMatchRoute(internalPath) {
+    // Validate input
+    if (typeof internalPath !== 'string') {
+        throw new Error(`[TagadaPay SDK] internalPath must be a string, got ${typeof internalPath}`);
+    }
+    if (internalPath.trim() === '') {
+        throw new Error('[TagadaPay SDK] internalPath cannot be empty');
+    }
+    if (!internalPath.startsWith('/')) {
+        throw new Error(`[TagadaPay SDK] internalPath must start with /, got "${internalPath}"`);
+    }
+    // SSR check
+    if (!isBrowser) {
+        return false;
+    }
+    try {
+        const currentPath = window.location.pathname;
+        const remappedInternalPath = getInternalPath();
+        // If remapped, check if the remapped internal path matches the pattern
+        if (remappedInternalPath) {
+            return matchesPathPattern(remappedInternalPath, internalPath);
+        }
+        // No remapping - check if current path matches the pattern
+        return matchesPathPattern(currentPath, internalPath);
+    }
+    catch (error) {
+        if (typeof process !== 'undefined' && process.env.NODE_ENV === 'development') {
+            console.error('[TagadaPay SDK] Error in shouldMatchRoute:', error);
+        }
+        return false;
+    }
+}
+/**
+ * Get the current matched path
+ *
+ * Returns the actual path in the browser if it matches the given internal path.
+ * Useful when you need the actual URL path for constructing links or API calls.
+ *
+ * @param internalPath - The plugin's defined path
+ * @returns The current browser path if it matches, null otherwise
+ *
+ * @example
+ * ```typescript
+ * const matchedPath = getMatchedPath('/hello');
+ * if (matchedPath) {
+ *   console.log('Matched at:', matchedPath); // Could be /hello or /hello2
+ * }
+ * ```
+ */
+export function getMatchedPath(internalPath) {
+    // Validate input
+    if (typeof internalPath !== 'string' || !internalPath.startsWith('/')) {
+        if (typeof process !== 'undefined' && process.env.NODE_ENV === 'development') {
+            console.warn(`[TagadaPay SDK] Invalid internalPath: "${internalPath}"`);
+        }
+        return null;
+    }
+    // SSR check
+    if (!isBrowser) {
+        return null;
+    }
+    try {
+        const currentPath = window.location.pathname;
+        const remappedInternalPath = getInternalPath();
+        // If current path matches internal path
+        if (currentPath === internalPath ||
+            (remappedInternalPath === internalPath && currentPath !== internalPath)) {
+            return currentPath;
+        }
+        return null;
+    }
+    catch (error) {
+        if (typeof process !== 'undefined' && process.env.NODE_ENV === 'development') {
+            console.error('[TagadaPay SDK] Error in getMatchedPath:', error);
+        }
+        return null;
+    }
+}
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Manually clear the internal path cache
+ *
+ * Useful for testing or when you know the meta tag has changed.
+ * Normally you don't need to call this as it's handled automatically.
+ *
+ * @example
+ * ```typescript
+ * // After dynamically updating the meta tag
+ * document.querySelector('meta[name="x-plugin-internal-path"]')
+ *   ?.setAttribute('content', '/new-path');
+ * clearInternalPathCache();
+ * ```
+ */
+export function clearInternalPathCache() {
+    clearCache();
+}
+/**
+ * Check if running in a browser environment
+ *
+ * Useful for conditional logic in universal/isomorphic code.
+ *
+ * @returns true if in browser, false if in SSR/Node environment
+ *
+ * @example
+ * ```typescript
+ * if (isBrowserEnvironment()) {
+ *   // Safe to use window/document
+ *   const path = getInternalPath();
+ * }
+ * ```
+ */
+export function isBrowserEnvironment() {
+    return isBrowser;
+}
+/**
+ * Get debug information about the current routing state
+ *
+ * Returns detailed information for debugging path remapping issues.
+ * Only available in development mode.
+ *
+ * @returns Debug information object
+ *
+ * @example
+ * ```typescript
+ * const debug = getDebugInfo();
+ * console.table(debug);
+ * ```
+ */
+export function getDebugInfo() {
+    if (!isBrowser) {
+        return {
+            environment: 'SSR/Node',
+            error: 'Not in browser environment',
+        };
+    }
+    try {
+        const pathInfo = getPathInfo();
+        const metaTag = document.querySelector('meta[name="x-plugin-internal-path"]');
+        return {
+            environment: 'Browser',
+            externalPath: pathInfo.externalPath,
+            internalPath: pathInfo.internalPath,
+            isRemapped: pathInfo.isRemapped,
+            fullUrl: pathInfo.fullUrl,
+            query: Object.fromEntries(pathInfo.query.entries()),
+            hash: pathInfo.hash,
+            metaTagExists: !!metaTag,
+            metaTagContent: metaTag?.getAttribute('content') || null,
+            cacheHit: internalPathCache !== undefined,
+            cachedValue: internalPathCache,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    catch (error) {
+        return {
+            environment: 'Browser',
+            error: String(error),
+        };
+    }
+}
+// ============================================================================
+// Cleanup
+// ============================================================================
+/**
+ * Cleanup function to remove event listeners
+ *
+ * Call this when unmounting the plugin or cleaning up resources.
+ * Important for preventing memory leaks in SPAs.
+ *
+ * @example
+ * ```typescript
+ * // In React
+ * useEffect(() => {
+ *   return () => {
+ *     cleanupPathRemapping();
+ *   };
+ * }, []);
+ * ```
+ */
+export function cleanupPathRemapping() {
+    if (!isBrowser)
+        return;
+    try {
+        window.removeEventListener('popstate', clearCache);
+        window.removeEventListener('hashchange', clearCache);
+        // Restore original history methods
+        if (originalPushState) {
+            history.pushState = originalPushState;
+        }
+        if (originalReplaceState) {
+            history.replaceState = originalReplaceState;
+        }
+        clearCache();
+    }
+    catch (error) {
+        if (typeof process !== 'undefined' && process.env.NODE_ENV === 'development') {
+            console.error('[TagadaPay SDK] Error during cleanup:', error);
+        }
+    }
+}

package/dist/v2/core/resources/credits.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Credits Resource Client
+ * Handles credits-related API operations
+ */
+import { ApiClient } from './apiClient';
+export interface CreditTransaction {
+    id: string;
+    amount: number;
+    type: 'earn' | 'spend' | 'adjustment';
+    description: string;
+    createdAt: string;
+    sourceId: string | null;
+    sourceType: string | null;
+}
+export interface CustomerCredits {
+    balance: number;
+    lifetimeEarned: number;
+    lifetimeSpent: number;
+    transactions: CreditTransaction[];
+}
+export interface RedeemProductResponse {
+    success: boolean;
+    orderId: string;
+    creditsSpent: number;
+    remainingCredits: number;
+}
+export declare class CreditsResource {
+    private apiClient;
+    constructor(apiClient: ApiClient);
+    /**
+     * Get customer credit balance and transaction history
+     */
+    getCustomerCredits(customerId: string, storeId: string): Promise<CustomerCredits>;
+    /**
+     * Redeem a product using credits
+     */
+    redeemProduct(data: {
+        productId?: string;
+        variantId: string;
+        quantity?: number;
+    }): Promise<RedeemProductResponse>;
+}