@explorins/pers-sdk 1.1.2 → 1.1.3

package/dist/index.js

@@ -0,0 +1,4164 @@
+import { jwtDecode } from 'jwt-decode';
+import Web3 from 'web3';
+import { ChainTypes as ChainTypes$1, getSmartContractInstance, getAddressTokenBalanceByContract, getTokenUri, getTokenOfOwnerByIndex } from '@explorins/web3-ts';
+import { FetchRequest, JsonRpcProvider } from 'ethers';
+
+/**
+ * PERS SDK Configuration interfaces
+ */
+/**
+ * Default configuration values
+ */
+const DEFAULT_PERS_CONFIG = {
+    environment: 'production',
+    apiVersion: 'v2',
+    timeout: 30000,
+    retries: 3
+};
+/**
+ * Internal function to construct API root from environment
+ * Now defaults to production and v2
+ */
+function buildApiRoot(environment = 'production', version = 'v2') {
+    const baseUrls = {
+        development: 'https://explorins-loyalty.ngrok.io',
+        staging: `https://dev.api.pers.ninja/${version}`,
+        production: `https://api.pers.ninja/${version}`
+    };
+    return `${baseUrls[environment]}`;
+}
+/**
+ * Merge user config with defaults
+ */
+function mergeWithDefaults(config) {
+    return {
+        ...DEFAULT_PERS_CONFIG,
+        ...config,
+        environment: config.environment ?? DEFAULT_PERS_CONFIG.environment,
+        apiVersion: config.apiVersion ?? DEFAULT_PERS_CONFIG.apiVersion,
+        timeout: config.timeout ?? DEFAULT_PERS_CONFIG.timeout,
+        retries: config.retries ?? DEFAULT_PERS_CONFIG.retries
+    };
+}
+
+// packages/pers-sdk/src/core/pers-api-client.ts
+/**
+ * PERS API Client - Core platform-agnostic client for PERS backend
+ */
+class PersApiClient {
+    constructor(httpClient, config) {
+        this.httpClient = httpClient;
+        this.config = config;
+        // Merge user config with defaults (production + v2)
+        this.mergedConfig = mergeWithDefaults(config);
+        // Build API root from merged environment and version
+        this.apiRoot = buildApiRoot(this.mergedConfig.environment, this.mergedConfig.apiVersion);
+    }
+    /**
+     * Get request headers including auth token and project key
+     */
+    async getHeaders() {
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        // Add authentication token
+        if (this.mergedConfig.authProvider) {
+            const token = await this.mergedConfig.authProvider.getToken();
+            if (token) {
+                headers['Authorization'] = `Bearer ${token}`;
+            }
+        }
+        // Add project key
+        if (this.mergedConfig.authProvider) {
+            const projectKey = await this.mergedConfig.authProvider.getProjectKey();
+            if (projectKey) {
+                headers['x-project-key'] = projectKey;
+            }
+        }
+        else if (this.mergedConfig.apiProjectKey) {
+            // Fallback to config project key if no auth provider
+            headers['x-project-key'] = this.mergedConfig.apiProjectKey;
+        }
+        return headers;
+    }
+    /**
+     * Make a request with proper headers, auth, and error handling
+     */
+    async request(method, endpoint, body, options) {
+        const { retryCount = 0, responseType = 'json' } = options || {};
+        const url = `${this.apiRoot}${endpoint}`;
+        // ✅ DEBUGGING: Add extensive logging for CSV endpoint
+        const isCSVEndpoint = endpoint.includes('/export/csv');
+        const requestOptions = {
+            headers: await this.getHeaders(),
+            timeout: this.mergedConfig.timeout,
+            responseType
+        };
+        try {
+            let result;
+            switch (method) {
+                case 'GET':
+                    result = await this.httpClient.get(url, requestOptions);
+                    break;
+                case 'POST':
+                    result = await this.httpClient.post(url, body, requestOptions);
+                    break;
+                case 'PUT':
+                    result = await this.httpClient.put(url, body, requestOptions);
+                    break;
+                case 'DELETE':
+                    result = await this.httpClient.delete(url, requestOptions);
+                    break;
+                default:
+                    throw new Error(`Unsupported HTTP method: ${method}`);
+            }
+            return result;
+        }
+        catch (error) {
+            if (isCSVEndpoint) {
+                console.error('❌ [PERS API CLIENT] CSV Request failed:', error);
+            }
+            // Handle 401 errors with automatic token refresh
+            const apiError = error;
+            if (apiError.status === 401 && retryCount === 0 && this.mergedConfig.authProvider?.onTokenExpired) {
+                try {
+                    await this.mergedConfig.authProvider.onTokenExpired();
+                    // Retry once with refreshed token
+                    return this.request(method, endpoint, body, { ...options, retryCount: 1 });
+                }
+                catch (refreshError) {
+                    throw new PersApiError(`Authentication refresh failed: ${refreshError}`, endpoint, method, 401);
+                }
+            }
+            throw new PersApiError(`PERS API request failed: ${apiError.message || error}`, endpoint, method, apiError.status);
+        }
+    }
+    /**
+     * Generic GET request
+     */
+    async get(endpoint, responseType) {
+        return this.request('GET', endpoint, undefined, { responseType });
+    }
+    /**
+     * Generic POST request
+     */
+    async post(endpoint, body) {
+        return this.request('POST', endpoint, body);
+    }
+    /**
+     * Generic PUT request
+     */
+    async put(endpoint, body) {
+        return this.request('PUT', endpoint, body);
+    }
+    /**
+     * Generic DELETE request
+     */
+    async delete(endpoint) {
+        return this.request('DELETE', endpoint);
+    }
+    /**
+     * Get current configuration (returns merged config)
+     */
+    getConfig() {
+        return this.mergedConfig;
+    }
+    /**
+     * Get original user configuration
+     */
+    getOriginalConfig() {
+        return this.config;
+    }
+}
+class PersApiError extends Error {
+    constructor(message, endpoint, method, statusCode) {
+        super(message);
+        this.endpoint = endpoint;
+        this.method = method;
+        this.statusCode = statusCode;
+        this.name = 'PersApiError';
+    }
+}
+/**
+ * PERS API Client - Core platform-agnostic client for PERS backend
+ */
+/*import { HttpClient, RequestOptions } from './abstractions/http-client';
+import { PersConfig, buildApiRoot, mergeWithDefaults } from './pers-config';
+
+export class PersApiClient {
+  private readonly apiRoot: string;
+  private readonly mergedConfig: ReturnType<typeof mergeWithDefaults>;
+
+  constructor(
+    private httpClient: HttpClient,
+    private config: PersConfig
+  ) {
+    // Merge user config with defaults (production + v2)
+    this.mergedConfig = mergeWithDefaults(config);
+    
+    // Build API root from merged environment and version
+    this.apiRoot = buildApiRoot(this.mergedConfig.environment, this.mergedConfig.apiVersion);
+  }
+
+  /**
+   * Get request headers including auth token and project key
+   */
+/*private async getHeaders(): Promise<Record<string, string>> {
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+  };
+
+  // Add authentication token
+  if (this.mergedConfig.authProvider) {
+    const token = await this.mergedConfig.authProvider.getToken();
+    if (token) {
+      headers['Authorization'] = `Bearer ${token}`;
+    }
+  }
+
+  // Add project key
+  if (this.mergedConfig.authProvider) {
+    const projectKey = await this.mergedConfig.authProvider.getProjectKey();
+    if (projectKey) {
+      headers['x-project-key'] = projectKey;
+    }
+  } else if(this.mergedConfig.apiProjectKey) {
+    // Fallback to config project key if no auth provider
+    headers['x-project-key'] = this.mergedConfig.apiProjectKey;
+  }
+
+  return headers;
+}
+
+/**
+ * Make a request with proper headers, auth, and error handling
+ */
+/*private async request<T>(
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE',
+  endpoint: string,
+  body?: any,
+  options?: { retryCount?: number }
+): Promise<T> {
+  const { retryCount = 0 } = options || {};
+  const url = `${this.apiRoot}${endpoint}`;
+  
+  const requestOptions: RequestOptions = {
+    headers: await this.getHeaders(),
+    timeout: this.mergedConfig.timeout,
+  };
+
+  try {
+    switch (method) {
+      case 'GET':
+        return await this.httpClient.get<T>(url, requestOptions);
+      case 'POST':
+        return await this.httpClient.post<T>(url, body, requestOptions);
+      case 'PUT':
+        return await this.httpClient.put<T>(url, body, requestOptions);
+      case 'DELETE':
+        return await this.httpClient.delete<T>(url, requestOptions);
+      default:
+        throw new Error(`Unsupported HTTP method: ${method}`);
+    }
+  } catch (error: any) {
+    // Handle 401 errors with automatic token refresh
+    if (error.status === 401 && retryCount === 0 && this.mergedConfig.authProvider?.onTokenExpired) {
+      try {
+        await this.mergedConfig.authProvider.onTokenExpired();
+        // Retry once with refreshed token
+        return this.request<T>(method, endpoint, body, { ...options, retryCount: 1 });
+      } catch (refreshError) {
+        throw new PersApiError(
+          `Authentication refresh failed: ${refreshError}`,
+          endpoint,
+          method,
+          401
+        );
+      }
+    }
+
+    throw new PersApiError(
+      `PERS API request failed: ${error.message || error}`,
+      endpoint,
+      method,
+      error.status
+    );
+  }
+}
+
+/**
+ * Generic GET request
+ */
+/*async get<T>(endpoint: string): Promise<T> {
+  return this.request<T>('GET', endpoint);
+}
+
+/**
+ * Generic POST request
+ */
+/*async post<T>(endpoint: string, body?: any): Promise<T> {
+  return this.request<T>('POST', endpoint, body);
+}
+
+/**
+ * Generic PUT request
+ */
+/*async put<T>(endpoint: string, body?: any): Promise<T> {
+  return this.request<T>('PUT', endpoint, body);
+}
+
+/**
+ * Generic DELETE request
+ */
+/*async delete<T>(endpoint: string): Promise<T> {
+  return this.request<T>('DELETE', endpoint);
+}
+
+/**
+ * Get current configuration (returns merged config)
+ */
+/*getConfig(): ReturnType<typeof mergeWithDefaults> {
+  return this.mergedConfig;
+}
+
+/**
+ * Get original user configuration
+ */
+/*getOriginalConfig(): PersConfig {
+  return this.config;
+}
+}
+
+export class PersApiError extends Error {
+constructor(
+  message: string,
+  public endpoint: string,
+  public method: string,
+  public statusCode?: number
+) {
+  super(message);
+  this.name = 'PersApiError';
+}
+}*/
+
+/**
+ * Creates a platform-agnostic AuthProvider from simple configuration
+ *
+ * This factory function is completely platform-agnostic and can be used
+ * across Angular, React, Vue, Node.js, or any other JavaScript environment.
+ *
+ * Features:
+ * - Token caching with refresh support
+ * - Automatic token refresh on expiration
+ * - Configurable token providers
+ * - Platform-independent (no localStorage assumptions)
+ *
+ * @param config - Simple auth configuration
+ * @returns AuthProvider implementation
+ */
+function createAuthProvider(config) {
+    // Store current token for refresh scenarios and caching
+    let currentToken = config.token || null;
+    let isRefreshing = false; // Prevent concurrent refresh attempts
+    let refreshPromise = null;
+    return {
+        authType: config.authType || 'user',
+        async getToken() {
+            // If currently refreshing, wait for it to complete
+            if (isRefreshing && refreshPromise) {
+                await refreshPromise;
+                return currentToken;
+            }
+            // Use cached current token (updated after refresh)
+            if (currentToken) {
+                return currentToken;
+            }
+            // Custom token provider function (always fresh)
+            if (config.tokenProvider) {
+                const token = await config.tokenProvider();
+                currentToken = token; // Cache for future calls
+                return token;
+            }
+            // No token available
+            return null;
+        },
+        async getProjectKey() {
+            return config.projectKey || null;
+        },
+        async onTokenExpired() {
+            // Prevent concurrent refresh attempts
+            if (isRefreshing) {
+                if (refreshPromise) {
+                    await refreshPromise;
+                }
+                return;
+            }
+            // No refresh logic provided
+            if (!config.onTokenExpired) {
+                console.warn('Token expired but no refresh logic provided');
+                currentToken = null; // Clear expired token
+                return;
+            }
+            // Start refresh process
+            isRefreshing = true;
+            refreshPromise = (async () => {
+                try {
+                    // Execute refresh logic (should update token source)
+                    await config.onTokenExpired();
+                    // After refresh, get the new token
+                    if (config.tokenProvider) {
+                        const newToken = await config.tokenProvider();
+                        if (newToken && newToken !== currentToken) {
+                            currentToken = newToken;
+                            // Notify about successful token refresh
+                            if (config.onTokenRefreshed) {
+                                config.onTokenRefreshed(newToken);
+                            }
+                        }
+                        else {
+                            console.warn('Token refresh completed but no new token received');
+                            currentToken = null;
+                        }
+                    }
+                    else {
+                        // For static token configs, clear the token since we can't refresh
+                        console.warn('Token expired for static token config - clearing token');
+                        currentToken = null;
+                    }
+                }
+                catch (error) {
+                    console.error('Token refresh failed:', error);
+                    currentToken = null; // Clear token on refresh failure
+                    throw error; // Re-throw to let SDK handle the error
+                }
+                finally {
+                    isRefreshing = false;
+                    refreshPromise = null;
+                }
+            })();
+            await refreshPromise;
+        }
+    };
+}
+/**
+ * Platform-specific localStorage token provider for browsers
+ * This is a convenience function for browser environments
+ */
+/* export function createBrowserTokenProvider(tokenKey: string = 'userJwt'): () => Promise<string | null> {
+  return async () => {
+    if (typeof localStorage !== 'undefined') {
+      return localStorage.getItem(tokenKey);
+    }
+    return null;
+  };
+} */
+/**
+ * Platform-specific environment variable token provider for Node.js
+ * This is a convenience function for Node.js environments
+ */
+/* export function createNodeTokenProvider(envVar: string = 'JWT_TOKEN'): () => Promise<string | null> {
+  return async () => {
+    if (typeof process !== 'undefined' && process.env) {
+      return process.env[envVar] || null;
+    }
+    return null;
+  };
+} */
+
+/**
+ * PERS SDK - Minimal platform-agnostic client with built-in authentication
+ * Authentication is now handled at the SDK core level for better scalability
+ */
+/**
+ * Minimal PERS SDK - API client with authentication built-in
+ * Platform adapters provide auth providers and HTTP clients
+ */
+class PersSDK {
+    constructor(httpClient, config) {
+        this.apiClient = new PersApiClient(httpClient, config);
+    }
+    /**
+     * Get the API client for direct PERS API calls
+     * This is the main interface - keep it simple!
+     */
+    api() {
+        return this.apiClient;
+    }
+    /**
+     * Quick config check
+     */
+    isProduction() {
+        return this.apiClient.getConfig().environment === 'production';
+    }
+}
+/**
+ * Simple factory function
+ */
+function createPersSDK(httpClient, config) {
+    return new PersSDK(httpClient, config);
+}
+
+/**
+ * Platform-Agnostic Business API Client
+ *
+ * Updated to match the new RESTful /businesses endpoints.
+ * Uses @explorins/pers-shared DTOs for full type safety and consistency with backend.
+ */
+class BusinessApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+        this.basePath = '/businesses';
+    }
+    // ==========================================
+    // 🌐 BUSINESS TYPES MANAGEMENT
+    // ==========================================
+    /**
+     * Get all business types (project key required)
+     *
+     * Endpoint: GET /businesses/types
+     * Auth: @ApiSecurity('projectKey')
+     */
+    async getAllBusinessTypes() {
+        return this.apiClient.get(`${this.basePath}/types`);
+    }
+    /**
+     * ADMIN: Create business type
+     *
+     * Endpoint: POST /businesses/types
+     * Auth: @TenantAdmin()
+     */
+    async createBusinessType(dto) {
+        return this.apiClient.post(`${this.basePath}/types`, dto);
+    }
+    /**
+     * ADMIN: Update business type
+     *
+     * Endpoint: PUT /businesses/types
+     * Auth: @TenantAdmin()
+     */
+    async updateBusinessType(dto) {
+        return this.apiClient.put(`${this.basePath}/types`, dto);
+    }
+    /**
+     * ADMIN: Delete business type
+     *
+     * Endpoint: DELETE /businesses/types/{id}
+     * Auth: @TenantAdmin()
+     */
+    async deleteBusinessType(id) {
+        return this.apiClient.delete(`${this.basePath}/types/${id}`);
+    }
+    // ==========================================
+    // 🏢 BUSINESS MANAGEMENT
+    // ==========================================
+    /**
+     * Get current business info (business authentication required)
+     *
+     * Endpoint: GET /businesses/me
+     * Auth: @Business()
+     */
+    async getCurrentBusiness() {
+        return this.apiClient.get(`${this.basePath}/me`);
+    }
+    /**
+     * Get all active businesses (project key required)
+     *
+     * Endpoint: GET /businesses
+     * Auth: @ApiSecurity('projectKey')
+     * Note: Regular users automatically get active businesses only
+     */
+    async getActiveBusinesses() {
+        return this.apiClient.get(`${this.basePath}`);
+    }
+    /**
+     * Get all businesses with filtering (admin users can access inactive)
+     *
+     * Endpoint: GET /businesses?active={boolean}&sanitize={mode}
+     * Auth: @ApiSecurity('projectKey') (enhanced with role-based filtering)
+     */
+    async getAllBusinesses(options) {
+        const params = new URLSearchParams();
+        if (options?.active !== undefined) {
+            params.append('active', String(options.active));
+        }
+        if (options?.sanitize) {
+            params.append('sanitize', options.sanitize);
+        }
+        const queryString = params.toString();
+        const url = queryString ? `${this.basePath}?${queryString}` : this.basePath;
+        return this.apiClient.get(url);
+    }
+    /**
+     * ADMIN: Get all businesses (admin endpoint with full access)
+     *
+     * Endpoint: GET /businesses/admin
+     * Auth: @TenantAdmin()
+     */
+    async getAllBusinessesAdmin(options) {
+        const params = new URLSearchParams();
+        if (options?.active !== undefined) {
+            params.append('active', String(options.active));
+        }
+        if (options?.sanitize) {
+            params.append('sanitize', options.sanitize);
+        }
+        const queryString = params.toString();
+        const url = queryString ? `${this.basePath}?${queryString}` : this.basePath;
+        return this.apiClient.get(url);
+    }
+    /**
+     * Get business by ID
+     *
+     * Endpoint: GET /businesses/{id}
+     * Auth: @ApiSecurity('projectKey')
+     */
+    async getBusinessById(businessId) {
+        return this.apiClient.get(`${this.basePath}/${businessId}`);
+    }
+    /**
+     * Get business by account address
+     *
+     * Endpoint: GET /businesses/account/{accountAddress}
+     * Auth: @ApiSecurity('projectKey')
+     */
+    async getBusinessByAccount(accountAddress) {
+        return this.apiClient.get(`${this.basePath}/account/${accountAddress}`);
+    }
+    // ==========================================
+    // 🔧 ADMIN OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Create business
+     *
+     * Endpoint: POST /businesses
+     * Auth: @TenantAdmin()
+     * Returns: BusinessApiKeyDTO | BusinessTokenBalancesDTO
+     */
+    async createBusiness(dto) {
+        return this.apiClient.post(`${this.basePath}`, dto);
+    }
+    /**
+     * ADMIN: Create business by display name (convenience method)
+     *
+     * This is a convenience wrapper that creates the proper DTO structure
+     */
+    async createBusinessByDisplayName(displayName) {
+        const dto = {
+            displayName,
+            // Add other required fields based on BusinessCreateRequestDTO structure
+            // You may need to check the DTO definition for required fields
+        };
+        return this.createBusiness(dto);
+    }
+    /**
+     * ADMIN: Create businesses from URL
+     *
+     * Endpoint: POST /businesses/bulk/url
+     * Auth: @TenantAdmin()
+     */
+    async createBusinessesFromUrl(url) {
+        return this.apiClient.post(`${this.basePath}/bulk/url`, { url });
+    }
+    /**
+     * ADMIN: Update business
+     *
+     * Endpoint: PUT /businesses/{id}
+     * Auth: @TenantAdmin()
+     */
+    async updateBusiness(id, businessData) {
+        return this.apiClient.put(`${this.basePath}/${id}`, businessData);
+    }
+    /**
+     * ADMIN: Toggle business active status
+     *
+     * Endpoint: PUT /businesses/{id}/activate
+     * Auth: @TenantAdmin()
+     */
+    async toggleBusinessActive(id, isActive) {
+        const dto = { isActive };
+        return this.apiClient.put(`${this.basePath}/${id}/status`, dto);
+    }
+    /**
+     * ADMIN: Generate new business API key
+     *
+     * Endpoint: PUT /businesses/{id}/api-key
+     * Auth: @TenantAdmin()
+     */
+    async generateNewBusinessApiKey(id) {
+        return this.apiClient.put(`${this.basePath}/${id}/api-key`, {});
+    }
+}
+
+/**
+ * Platform-Agnostic Business Service
+ *
+ * Contains business logic and operations that work across platforms.
+ * No framework dependencies - pure TypeScript business logic.
+ *
+ * Focuses only on actual backend capabilities.
+ */
+class BusinessService {
+    constructor(businessApi) {
+        this.businessApi = businessApi;
+    }
+    /**
+     * Get all active businesses
+     */
+    async getActiveBusinesses() {
+        return this.businessApi.getActiveBusinesses();
+    }
+    /**
+     * Get all business types
+     */
+    async getAllBusinessTypes() {
+        return this.businessApi.getAllBusinessTypes();
+    }
+    /**
+     * Get business by ID
+     */
+    async getBusinessById(businessId) {
+        return this.businessApi.getBusinessById(businessId);
+    }
+    /**
+     * Get business by account address
+     */
+    async getBusinessByAccount(accountAddress) {
+        return this.businessApi.getBusinessByAccount(accountAddress);
+    }
+    /**
+     * Get businesses by type (client-side filtering)
+     */
+    async getBusinessesByType(typeId) {
+        const businesses = await this.getActiveBusinesses();
+        return businesses.filter(business => business.businessType && business.businessType.id === parseInt(typeId));
+    }
+    // ==========================================
+    // ADMIN OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Get all businesses (active and inactive)
+     */
+    async getAllBusinesses() {
+        return this.businessApi.getAllBusinesses();
+    }
+    /**
+     * ADMIN: Create business by display name
+     */
+    async createBusinessByDisplayName(displayName) {
+        return this.businessApi.createBusinessByDisplayName(displayName);
+    }
+    /**
+     * ADMIN: Update business
+     */
+    async updateBusiness(id, businessData) {
+        return this.businessApi.updateBusiness(id, businessData);
+    }
+    /**
+     * ADMIN: Toggle business active status
+     */
+    async toggleBusinessActive(id, isActive) {
+        return this.businessApi.toggleBusinessActive(id, isActive);
+    }
+}
+
+/**
+ * @explorins/pers-sdk-business
+ *
+ * Platform-agnostic Business Domain SDK for PERS ecosystem
+ * Focuses on non-admin business operations
+ */
+// API Layer
+/**
+ * Create a complete Business SDK instance
+ *
+ * @param apiClient - Configured PERS API client
+ * @returns Business SDK with flattened structure for better DX
+ */
+function createBusinessSDK(apiClient) {
+    const businessApi = new BusinessApi(apiClient);
+    const businessService = new BusinessService(businessApi);
+    return {
+        // Direct access to service methods (primary interface)
+        getActiveBusinesses: () => businessService.getActiveBusinesses(),
+        getAllBusinessTypes: () => businessService.getAllBusinessTypes(),
+        getBusinessById: (businessId) => businessService.getBusinessById(businessId),
+        getBusinessByAccount: (accountAddress) => businessService.getBusinessByAccount(accountAddress),
+        getBusinessesByType: (typeId) => businessService.getBusinessesByType(typeId),
+        // Admin methods
+        getAllBusinesses: () => businessService.getAllBusinesses(),
+        createBusinessByDisplayName: (displayName) => businessService.createBusinessByDisplayName(displayName),
+        updateBusiness: (id, businessData) => businessService.updateBusiness(id, businessData),
+        toggleBusinessActive: (id, isActive) => businessService.toggleBusinessActive(id, isActive),
+        // Advanced access for edge cases
+        api: businessApi,
+        service: businessService
+    };
+}
+
+/**
+ * Platform-Agnostic Transaction API Client (UPDATED FOR NEW RESTful ENDPOINTS)
+ *
+ * Handles transaction operations using the PERS backend.
+ * Uses @explorins/pers-shared DTOs for consistency with backend.
+ *
+ * MIGRATION NOTES:
+ * - All endpoints changed from /transaction to /transactions
+ * - Role-based paths removed (no more /auth, /admin, /business in URLs)
+ * - New RESTful resource-based structure
+ * - Added new client-side transaction flow methods
+ * - Enhanced admin query capabilities
+ */
+class TransactionApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+        this.basePath = '/transactions';
+    }
+    /**
+     * Get transaction by ID (public endpoint)
+     *
+     * UPDATED: /transaction/{id} → /transactions/{id}
+     */
+    async getTransactionById(transactionId) {
+        return this.apiClient.get(`${this.basePath}/${transactionId}`);
+    }
+    // ==========================================
+    // AUTHENTICATED USER OPERATIONS
+    // ==========================================
+    /**
+     * AUTH: Create authenticated user transaction
+     *
+     * UPDATED: /transaction/auth/transaction → /transactions/user
+     */
+    async createAuthTransaction(request) {
+        return this.apiClient.post(`${this.basePath}/user`, request);
+    }
+    /**
+     * AUTH: Get user's sent transactions
+     *
+     * UPDATED: /transaction/auth/sender → /transactions/me/sent
+     */
+    async getUserSentTransactions() {
+        const params = new URLSearchParams({
+            timestamp: Date.now().toString()
+        });
+        return this.apiClient.get(`${this.basePath}/me/sent?${params.toString()}`);
+    }
+    /**
+     * AUTH: Get user's received transactions
+     *
+     * UPDATED: /transaction/auth/recipient → /transactions/me/received
+     */
+    async getUserReceivedTransactions() {
+        const params = new URLSearchParams({
+            timestamp: Date.now().toString()
+        });
+        return this.apiClient.get(`${this.basePath}/me/received?${params.toString()}`);
+    }
+    /**
+     * AUTH: Get user transaction history by type (backwards compatibility)
+     *
+     * UPDATED: Maps to appropriate /transactions/me/* endpoints
+     */
+    async getUserTransactionHistory(type) {
+        const params = new URLSearchParams({
+            timestamp: Date.now().toString()
+        });
+        // Map legacy type parameter to new endpoints
+        switch (type.toLowerCase()) {
+            case 'sender':
+            case 'sent':
+                return this.apiClient.get(`${this.basePath}/me/sent?${params.toString()}`);
+            case 'recipient':
+            case 'received':
+                return this.apiClient.get(`${this.basePath}/me/received?${params.toString()}`);
+            default:
+                // Default to sent transactions for backwards compatibility
+                return this.apiClient.get(`${this.basePath}/me/sent?${params.toString()}`);
+        }
+    }
+    /**
+     * AUTH: Prepare client signed transaction
+     *
+     * UPDATED: /transaction/auth/prepare-signing → /transactions/prepare
+     */
+    async prepareClientSignedTransaction(request) {
+        return this.apiClient.post(`${this.basePath}/prepare`, request);
+    }
+    /**
+     * AUTH: Prepare existing transaction for client-side signing
+     *
+     * NEW ENDPOINT: GET /transactions/{id}/prepare
+     */
+    async prepareExistingTransaction(transactionId) {
+        return this.apiClient.get(`${this.basePath}/${transactionId}/prepare`);
+    }
+    /**
+     * AUTH: Submit client-side signed transaction
+     *
+     * NEW ENDPOINT: POST /transactions/{id}/submit
+     */
+    async submitSignedTransaction(transactionId, signedData) {
+        return this.apiClient.post(`${this.basePath}/${transactionId}/submit`, signedData);
+    }
+    /**
+     * AUTH: Burn user tokens
+     *
+     * UPDATED: Uses new user transaction endpoint with burn-specific parameters
+     * Note: This might need backend confirmation on burn functionality implementation
+     */
+    async burnUserTokens(request) {
+        // Map burn request to TransactionRequestDTO format for new endpoint
+        const transactionRequest = {
+            ...request,
+            // Add any specific burn transaction parameters here
+        };
+        return this.apiClient.post(`${this.basePath}/user`, transactionRequest);
+    }
+    // ==========================================
+    // BUSINESS OPERATIONS
+    // ==========================================
+    /**
+     * BUSINESS: Create business transaction
+     *
+     * UPDATED: /transaction/business/transaction → /transactions/business
+     */
+    async createBusinessTransaction(request) {
+        return this.apiClient.post(`${this.basePath}/business`, request);
+    }
+    // ==========================================
+    // ADMIN OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Create admin transaction
+     *
+     * UPDATED: /transaction/admin/transaction → /transactions/admin
+     */
+    async createAdminTransaction(request) {
+        return this.apiClient.post(`${this.basePath}/system`, request);
+    }
+    /**
+     * ADMIN: Get all tenant transactions
+     *
+     * UPDATED: /transaction/admin → /transactions
+     */
+    async getTenantTransactions() {
+        const result = await this.apiClient.get(`${this.basePath}`);
+        // If the new endpoint returns paginated response, extract the data array
+        if ('data' in result) {
+            return result.data;
+        }
+        // Fallback for direct array response
+        return result;
+    }
+    /**
+     * ADMIN: Get paginated transactions with filtering and sorting
+     *
+     * UPDATED: /transaction/admin → /transactions (same endpoint, better structure)
+     */
+    async getPaginatedTransactions(params) {
+        // Build query parameters
+        const queryParams = {
+            page: params.page.toString(),
+            limit: params.limit.toString()
+        };
+        // Add sorting parameters if provided
+        if (params.sortBy) {
+            queryParams['sortBy'] = params.sortBy;
+        }
+        if (params.sortOrder) {
+            queryParams['sortOrder'] = params.sortOrder;
+        }
+        // Add user-specific filtering if provided
+        if (params.participantId) {
+            queryParams['participantId'] = params.participantId;
+        }
+        // Add status filtering if provided
+        if (params.status) {
+            queryParams['status'] = params.status;
+        }
+        // Add additional filters if provided
+        if (params.filters) {
+            if (params.filters.startDate) {
+                queryParams['startDate'] = params.filters.startDate;
+            }
+            if (params.filters.endDate) {
+                queryParams['endDate'] = params.filters.endDate;
+            }
+            if (params.filters.type && params.filters.type.length > 0) {
+                queryParams['type'] = params.filters.type.join(',');
+            }
+            if (params.filters.tokenType && params.filters.tokenType.length > 0) {
+                queryParams['tokenType'] = params.filters.tokenType.join(',');
+            }
+        }
+        // Build query string
+        const queryString = Object.entries(queryParams)
+            .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
+            .join('&');
+        return this.apiClient.get(`${this.basePath}?${queryString}`);
+    }
+    /**
+     * ADMIN: Export transactions to CSV
+     *
+     * UPDATED: /transaction/admin/export/csv → /transactions/export/csv
+     */
+    async exportTransactionsCSV() {
+        return this.apiClient.get(`${this.basePath}/export/csv`, 'blob');
+    }
+    // ==========================================
+    // NEW ADMIN QUERY METHODS
+    // ==========================================
+    /**
+     * ADMIN: Query transactions by sender
+     *
+     * NEW ENDPOINT: POST /transactions/query-sender
+     */
+    async queryTransactionsBySender(accountSelector) {
+        return this.apiClient.post(`${this.basePath}/query-sender`, accountSelector);
+    }
+    /**
+     * ADMIN: Query transactions by recipient
+     *
+     * NEW ENDPOINT: POST /transactions/query-recipient
+     */
+    async queryTransactionsByRecipient(accountSelector) {
+        return this.apiClient.post(`${this.basePath}/query-recipient`, accountSelector);
+    }
+    /**
+     * ADMIN: Get transaction analytics
+     *
+     * NEW ENDPOINT: POST /transactions/analytics
+     */
+    async getTransactionAnalytics(analyticsRequest) {
+        return this.apiClient.post(`${this.basePath}/analytics`, analyticsRequest);
+    }
+    // ==========================================
+    // CONVENIENCE METHODS (BACKWARDS COMPATIBILITY)
+    // ==========================================
+    /**
+     * Convenience method: Get user sent transactions (alias)
+     */
+    async getUserSenderTransactions() {
+        return this.getUserSentTransactions();
+    }
+    /**
+     * Convenience method: Get user received transactions (alias)
+     */
+    async getUserRecipientTransactions() {
+        return this.getUserReceivedTransactions();
+    }
+}
+
+/**
+ * Platform-Agnostic Transaction Service
+ *
+ * Contains transaction business logic and operations that work across platforms.
+ * No framework dependencies - pure TypeScript business logic.
+ *
+ * Focuses only on actual backend capabilities.
+ */
+class TransactionService {
+    constructor(transactionApi) {
+        this.transactionApi = transactionApi;
+    }
+    /**
+     * Get transaction by ID
+     */
+    async getTransactionById(transactionId) {
+        return this.transactionApi.getTransactionById(transactionId);
+    }
+    // ==========================================
+    // AUTHENTICATED OPERATIONS
+    // ==========================================
+    /**
+     * AUTH: Create authenticated transaction
+     */
+    async createAuthTransaction(request) {
+        return this.transactionApi.createAuthTransaction(request);
+    }
+    /**
+     * AUTH: Get user transaction history by type
+     */
+    async getUserTransactionHistory(type) {
+        return this.transactionApi.getUserTransactionHistory(type);
+    }
+    /**
+     * AUTH: Prepare client signed transaction
+     */
+    async prepareClientSignedTransaction(request) {
+        return this.transactionApi.prepareClientSignedTransaction(request);
+    }
+    /**
+     * AUTH: Burn user tokens
+     */
+    async burnUserTokens(request) {
+        return this.transactionApi.burnUserTokens(request);
+    }
+    // ==========================================
+    // BUSINESS OPERATIONS
+    // ==========================================
+    /**
+     * BUSINESS: Create business transaction
+     */
+    async createBusinessTransaction(request) {
+        return this.transactionApi.createBusinessTransaction(request);
+    }
+    // ==========================================
+    // ADMIN OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Create admin transaction
+     */
+    async createAdminTransaction(request) {
+        return this.transactionApi.createAdminTransaction(request);
+    }
+    /**
+     * ADMIN: Get all tenant transactions
+     */
+    async getTenantTransactions() {
+        return this.transactionApi.getTenantTransactions();
+    }
+    /**
+     * ADMIN: Get paginated transactions with filtering and sorting
+     */
+    async getPaginatedTransactions(params) {
+        return this.transactionApi.getPaginatedTransactions(params);
+    }
+    /**
+     * ADMIN: Export transactions to CSV
+     */
+    async exportTransactionsCSV() {
+        return this.transactionApi.exportTransactionsCSV();
+    }
+}
+
+/**
+ * Transaction Domain Models
+ *
+ * Re-exports from @explorins/pers-shared for consistency with backend
+ * and to provide a single import source for transaction-related types.
+ */
+// Transaction account types (domain-specific enum)
+var TransactionAccountType;
+(function (TransactionAccountType) {
+    // Add specific transaction account types as needed
+    // This should match the enum used in the infrastructure layer
+})(TransactionAccountType || (TransactionAccountType = {}));
+
+/**
+ * @explorins/pers-sdk-transaction
+ *
+ * Platform-agnostic Transaction Domain SDK for PERS ecosystem
+ * Handles transaction operations across different authorization levels
+ */
+// API Layer
+/**
+ * Create a complete Transaction SDK instance
+ *
+ * @param apiClient - Configured PERS API client
+ * @returns Transaction SDK with flattened structure for better DX
+ */
+function createTransactionSDK(apiClient) {
+    const transactionApi = new TransactionApi(apiClient);
+    const transactionService = new TransactionService(transactionApi);
+    return {
+        // Direct access to service methods (primary interface)
+        // Public methods
+        getTransactionById: (transactionId) => transactionService.getTransactionById(transactionId),
+        // Auth methods
+        createAuthTransaction: (request) => transactionService.createAuthTransaction(request),
+        getUserTransactionHistory: (type) => transactionService.getUserTransactionHistory(type),
+        prepareClientSignedTransaction: (request) => transactionService.prepareClientSignedTransaction(request),
+        burnUserTokens: (request) => transactionService.burnUserTokens(request),
+        // Business methods
+        createBusinessTransaction: (request) => transactionService.createBusinessTransaction(request),
+        // Admin methods
+        createAdminTransaction: (request) => transactionService.createAdminTransaction(request),
+        getTenantTransactions: () => transactionService.getTenantTransactions(),
+        getPaginatedTransactions: (params) => transactionService.getPaginatedTransactions(params),
+        exportTransactionsCSV: () => transactionService.exportTransactionsCSV(),
+        // Advanced access for edge cases
+        api: transactionApi,
+        service: transactionService
+    };
+}
+
+/**
+ * Platform-Agnostic Analytics API Client
+ *
+ * Handles analytics operations using the PERS backend.
+ * Uses @explorins/pers-shared DTOs for consistency with backend.
+ */
+class AnalyticsApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+    }
+    // ==========================================
+    // ADMIN OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Get transaction analytics with filtering and aggregation
+     */
+    async getTransactionAnalytics(request) {
+        return this.apiClient.post('/transactions/analytics', request);
+    }
+}
+
+/**
+ * Platform-Agnostic Analytics Service
+ *
+ * Contains analytics business logic and operations that work across platforms.
+ * No framework dependencies - pure TypeScript business logic.
+ *
+ * Focuses only on actual backend capabilities.
+ */
+class AnalyticsService {
+    constructor(analyticsApi) {
+        this.analyticsApi = analyticsApi;
+    }
+    // ==========================================
+    // ADMIN OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Get transaction analytics with filtering and aggregation
+     */
+    async getTransactionAnalytics(request) {
+        return this.analyticsApi.getTransactionAnalytics(request);
+    }
+}
+
+/**
+ * @explorins/pers-sdk-analytics
+ *
+ * Platform-agnostic Analytics Domain SDK for PERS ecosystem
+ * Handles analytics operations and data aggregation
+ */
+// API Layer
+/**
+ * Create a complete Analytics SDK instance
+ *
+ * @param apiClient - Configured PERS API client
+ * @returns Analytics SDK with flattened structure for better DX
+ */
+function createAnalyticsSDK(apiClient) {
+    const analyticsApi = new AnalyticsApi(apiClient);
+    const analyticsService = new AnalyticsService(analyticsApi);
+    return {
+        // Direct access to service methods (primary interface)
+        // Admin methods
+        getTransactionAnalytics: (request) => analyticsService.getTransactionAnalytics(request),
+        // Advanced access for edge cases
+        api: analyticsApi,
+        service: analyticsService
+    };
+}
+
+/**
+ * Platform-Agnostic Auth Admin API Client
+ *
+ * Handles authentication and authorization admin operations using the PERS backend.
+ * Uses @explorins/pers-shared DTOs for consistency with backend.
+ *
+ * Note: Special header handling (bypass-auth-interceptor) may need to be implemented
+ * at the PersApiClient level or through a specialized auth client.
+ */
+class AuthAdminApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+        this.basePath = '/auth';
+    }
+    // ==========================================
+    // ADMIN AUTHENTICATION OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Login tenant admin with JWT
+     * Note: JWT handling and auth bypass headers may need special implementation
+     */
+    async loginTenantAdmin(jwt) {
+        // TODO: Implement proper JWT and bypass header handling when PersApiClient supports it
+        return this.apiClient.post(`${this.basePath}/token`, {});
+    }
+    /**
+     * ADMIN: Refresh access token
+     * Note: Bypass header handling may need special implementation
+     */
+    async refreshAccessToken(refreshToken) {
+        return this.apiClient.post(`${this.basePath}/refresh`, { refreshToken });
+    }
+}
+
+/**
+ * Platform-Agnostic Auth Admin Service
+ *
+ * Contains auth admin business logic and operations that work across platforms.
+ * No framework dependencies - pure TypeScript business logic.
+ *
+ * Focuses only on actual backend capabilities.
+ */
+class AuthAdminService {
+    constructor(authAdminApi) {
+        this.authAdminApi = authAdminApi;
+    }
+    // ==========================================
+    // ADMIN AUTHENTICATION OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Login tenant admin with JWT
+     */
+    async loginTenantAdmin(jwt) {
+        return this.authAdminApi.loginTenantAdmin(jwt);
+    }
+    /**
+     * ADMIN: Refresh access token
+     */
+    async refreshAccessToken(refreshToken) {
+        return this.authAdminApi.refreshAccessToken(refreshToken);
+    }
+}
+
+/**
+ * @explorins/pers-sdk-auth-admin
+ *
+ * Platform-agnostic Auth Admin Domain SDK for PERS ecosystem
+ * Handles authentication and authorization admin operations
+ */
+// API Layer
+/**
+ * Create a complete Auth Admin SDK instance
+ *
+ * @param apiClient - Configured PERS API client
+ * @returns Auth Admin SDK with flattened structure for better DX
+ */
+function createAuthAdminSDK(apiClient) {
+    const authAdminApi = new AuthAdminApi(apiClient);
+    const authAdminService = new AuthAdminService(authAdminApi);
+    return {
+        // Direct access to service methods (primary interface)
+        // Admin authentication methods
+        loginTenantAdmin: (jwt) => authAdminService.loginTenantAdmin(jwt),
+        refreshAccessToken: (refreshToken) => authAdminService.refreshAccessToken(refreshToken),
+        // Advanced access for edge cases
+        api: authAdminApi,
+        service: authAdminService
+    };
+}
+
+/**
+ * Platform-Agnostic Campaign API Client (NEW - RESTful Design)
+ *
+ * Updated to use the new microservice-ready campaign controllers:
+ * - CampaignsController: Core campaign operations
+ * - CampaignTagsController: Tag management
+ * - CampaignTokensController: Token unit operations
+ * - CampaignTriggersController: Trigger system
+ * - CampaignEngagementsController: Business relationships
+ * - CampaignClaimsController: Claims processing
+ *
+ * Uses @explorins/pers-shared DTOs for consistency with backend.
+ * All endpoints updated to new RESTful patterns without role revelation.
+ */
+class CampaignApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+    }
+    // ==========================================
+    // CORE CAMPAIGN OPERATIONS (/campaigns)
+    // ==========================================
+    /**
+     * PUBLIC: Get all active campaigns
+     * NEW: /campaigns (intelligent access detection)
+     */
+    async getActiveCampaigns() {
+        return this.apiClient.get('/campaigns');
+    }
+    /**
+     * ADMIN: Get campaigns with filtering options
+     * NEW: /campaigns with query parameters (admin access detected automatically)
+     */
+    async getCampaigns(options) {
+        let url = '/campaigns';
+        const params = [];
+        if (options) {
+            if (options.active !== undefined)
+                params.push(`active=${options.active}`);
+            if (options.tag)
+                params.push(`tag=${encodeURIComponent(options.tag)}`);
+            if (options.limit)
+                params.push(`limit=${options.limit}`);
+            if (options.offset)
+                params.push(`offset=${options.offset}`);
+            if (options.sort)
+                params.push(`sort=${options.sort}`);
+            if (options.order)
+                params.push(`order=${options.order}`);
+        }
+        if (params.length > 0) {
+            url += `?${params.join('&')}`;
+        }
+        return this.apiClient.get(url);
+    }
+    /**
+     * PUBLIC: Get campaign by ID
+     * NEW: /campaigns/{id}
+     */
+    async getCampaignById(id) {
+        return this.apiClient.get(`/campaigns/${id}`);
+    }
+    /**
+     * ADMIN: Create campaign
+     * NEW: POST /campaigns
+     */
+    async createCampaign(campaign) {
+        return this.apiClient.post('/campaigns', campaign);
+    }
+    /**
+     * ADMIN: Update campaign
+     * NEW: PUT /campaigns/{id}
+     */
+    async updateCampaign(campaignId, campaign) {
+        return this.apiClient.put(`/campaigns/${campaignId}`, campaign);
+    }
+    /**
+     * ADMIN: Toggle campaign active status
+     * NEW: PUT /campaigns/{id}/status
+     */
+    async toggleCampaignActive(campaignId) {
+        return this.apiClient.put(`/campaigns/${campaignId}/status`, {});
+    }
+    /**
+     * ADMIN: Toggle campaign testnet environment
+     * NEW: PUT /campaigns/{id}/environment
+     */
+    async toggleCampaignTestnet(campaignId) {
+        return this.apiClient.put(`/campaigns/${campaignId}/environment`, {});
+    }
+    /**
+     * ADMIN: Delete campaign
+     * NEW: DELETE /campaigns/{id}
+     */
+    async deleteCampaign(campaignId) {
+        return this.apiClient.delete(`/campaigns/${campaignId}`);
+    }
+    // ==========================================
+    // TAG MANAGEMENT (/campaign-tags)
+    // ==========================================
+    /**
+     * ADMIN: Get all unique campaign tags
+     * NEW: GET /campaign-tags
+     */
+    async getAllUniqueTags() {
+        return this.apiClient.get('/campaign-tags');
+    }
+    /**
+     * ADMIN: Update campaign tags (replace all)
+     * NEW: PUT /campaign-tags/{id}
+     */
+    async updateCampaignTags(campaignId, tags) {
+        return this.apiClient.put(`/campaign-tags/${campaignId}`, { tags });
+    }
+    /**
+     * ADMIN: Add tags to campaign
+     * NEW: POST /campaign-tags/{id}
+     */
+    async addTagsToCampaign(campaignId, tags) {
+        return this.apiClient.post(`/campaign-tags/${campaignId}`, { tags });
+    }
+    /**
+     * ADMIN: Remove tag from campaign
+     * NEW: DELETE /campaign-tags/{id}/{tag}
+     */
+    async removeTagFromCampaign(campaignId, tag) {
+        return this.apiClient.delete(`/campaign-tags/${campaignId}/${encodeURIComponent(tag)}`);
+    }
+    // ==========================================
+    // TOKEN MANAGEMENT (/campaign-tokens)
+    // ==========================================
+    /**
+     * ADMIN: Create campaign token unit
+     * NEW: POST /campaign-tokens/{id}
+     */
+    async createCampaignTokenUnit(campaignId, campaignTokenUnit) {
+        return this.apiClient.post(`/campaign-tokens/${campaignId}`, campaignTokenUnit);
+    }
+    /**
+     * ADMIN: Update campaign token unit
+     * NEW: PUT /campaign-tokens/{id}/{tokenUnitId}
+     */
+    async updateCampaignTokenUnit(campaignId, tokenUnitId, campaignTokenUnit) {
+        return this.apiClient.put(`/campaign-tokens/${campaignId}/${tokenUnitId}`, campaignTokenUnit);
+    }
+    /**
+     * ADMIN: Delete campaign token unit
+     * NEW: DELETE /campaign-tokens/{id}/{tokenUnitId}
+     */
+    async deleteCampaignTokenUnit(campaignId, campaignTokenUnitId) {
+        return this.apiClient.delete(`/campaign-tokens/${campaignId}/${campaignTokenUnitId}`);
+    }
+    // ==========================================
+    // TRIGGER SYSTEM (/campaign-triggers)
+    // ==========================================
+    /**
+     * PUBLIC: Get campaign triggers catalog
+     * NEW: GET /campaign-triggers
+     */
+    async getCampaignTriggers() {
+        return this.apiClient.get('/campaign-triggers');
+    }
+    /**
+     * ADMIN: Create campaign trigger
+     * NEW: POST /campaign-triggers
+     */
+    async createCampaignTrigger(trigger) {
+        return this.apiClient.post('/campaign-triggers', trigger);
+    }
+    /**
+     * ADMIN: Update campaign trigger
+     * NEW: PUT /campaign-triggers/{id}
+     */
+    async updateCampaignTrigger(triggerId, trigger) {
+        return this.apiClient.put(`/campaign-triggers/${triggerId}`, trigger);
+    }
+    /**
+     * ADMIN: Delete campaign trigger
+     * NEW: DELETE /campaign-triggers/{id}
+     */
+    async deleteCampaignTrigger(triggerId) {
+        return this.apiClient.delete(`/campaign-triggers/${triggerId}`);
+    }
+    /**
+     * ADMIN: Set campaign trigger
+     * NEW: PUT /campaign-triggers/campaigns/{id}/trigger/{triggerId}
+     */
+    async setCampaignTrigger(campaignId, triggerId) {
+        return this.apiClient.put(`/campaign-triggers/campaigns/${campaignId}/trigger/${triggerId}`, {});
+    }
+    /**
+     * ADMIN: Create trigger condition
+     * NEW: POST /campaign-triggers/conditions
+     */
+    async createTriggerCondition(condition) {
+        return this.apiClient.post('/campaign-triggers/conditions', condition);
+    }
+    /**
+     * ADMIN: Update trigger condition
+     * NEW: PUT /campaign-triggers/conditions/{id}
+     */
+    async updateTriggerCondition(conditionId, condition) {
+        return this.apiClient.put(`/campaign-triggers/conditions/${conditionId}`, condition);
+    }
+    /**
+     * ADMIN: Add/Remove condition to trigger
+     * NEW: PUT /campaign-triggers/{triggerId}/condition/{conditionId}
+     */
+    async addOrRemoveConditionToTrigger(triggerId, conditionId) {
+        return this.apiClient.put(`/campaign-triggers/${triggerId}/condition/${conditionId}`, {});
+    }
+    // ==========================================
+    // BUSINESS ENGAGEMENTS (/campaign-engagements)
+    // ==========================================
+    /**
+     * ADMIN: Add business engagement to campaign
+     * NEW: POST /campaign-engagements/{id}
+     */
+    async addBusinessEngagementToCampaign(campaignId, campaignBusinessEngagement) {
+        return this.apiClient.post(`/campaign-engagements/${campaignId}`, campaignBusinessEngagement);
+    }
+    /**
+     * ADMIN: Update campaign business engagement
+     * NEW: PUT /campaign-engagements/{id}/{businessEngagementId}
+     */
+    async updateCampaignBusinessEngagement(campaignId, businessEngagementId, campaignBusinessEngagement) {
+        return this.apiClient.put(`/campaign-engagements/${campaignId}/${businessEngagementId}`, campaignBusinessEngagement);
+    }
+    /**
+     * ADMIN: Delete campaign business engagement
+     * NEW: DELETE /campaign-engagements/{id}/{businessEngagementId}
+     */
+    async deleteCampaignBusinessEngagement(campaignId, businessEngagementId) {
+        return this.apiClient.delete(`/campaign-engagements/${campaignId}/${businessEngagementId}`);
+    }
+    // ==========================================
+    // CLAIMS PROCESSING (/campaign-claims)
+    // ==========================================
+    /**
+     * USER: Claim campaign reward
+     * NEW: POST /campaign-claims/user
+     */
+    async claimCampaign(request) {
+        return this.apiClient.post('/campaign-claims/user', request);
+    }
+    /**
+     * USER: Get claims for logged user
+     * NEW: GET /campaign-claims/users/me
+     */
+    async getClaimsForLoggedUser() {
+        return this.apiClient.get('/campaign-claims/users/me');
+    }
+    /**
+     * BUSINESS: Claim campaign reward for customer
+     * NEW: POST /campaign-claims/business
+     */
+    async businessClaimCampaign(request) {
+        return this.apiClient.post('/campaign-claims/business', request);
+    }
+    /**
+     * SYSTEM: Process automated claim
+     * NEW: POST /campaign-claims/system
+     */
+    async systemClaimCampaign(request) {
+        return this.apiClient.post('/campaign-claims/system', request);
+    }
+    /**
+     * ADMIN: Manual claim processing
+     * NEW: POST /campaign-claims/admin
+     */
+    async adminClaimCampaign(request) {
+        return this.apiClient.post('/campaign-claims/admin', request);
+    }
+    /**
+     * ADMIN: Get all campaign claims
+     * NEW: GET /campaign-claims/admin
+     */
+    async getCampaignClaims() {
+        return this.apiClient.get('/campaign-claims/admin');
+    }
+    /**
+     * ADMIN: Get campaign claims by campaign ID
+     * NEW: GET /campaign-claims/admin/{campaignId}
+     */
+    async getCampaignClaimsByCampaignId(campaignId) {
+        return this.apiClient.get(`/campaign-claims/admin/${campaignId}`);
+    }
+    /**
+     * ADMIN: Get campaign claims by user ID
+     * NEW: GET /campaign-claims/admin/users/{userId}
+     */
+    async getCampaignClaimsByUserId(userId) {
+        return this.apiClient.get(`/campaign-claims/admin/users/${userId}`);
+    }
+    /**
+     * ADMIN: Get campaign claims by business ID
+     * NEW: GET /campaign-claims/admin/businesses/{businessId}
+     */
+    async getCampaignClaimsByBusinessId(businessId) {
+        return this.apiClient.get(`/campaign-claims/admin/businesses/${businessId}`);
+    }
+    /**
+     * USER: Get user's claims for specific campaign
+     * NEW: GET /campaign-claims/campaigns/{campaignId}/users/me
+     */
+    async getUserClaimsForCampaign(campaignId) {
+        return this.apiClient.get(`/campaign-claims/campaigns/${campaignId}/users/me`);
+    }
+    // ==========================================
+    // BACKWARD COMPATIBILITY (DEPRECATED)
+    // ==========================================
+    /**
+     * @deprecated Use getCampaigns() instead
+     * LEGACY: Get campaigns with active filter
+     */
+    async getCampaignsLegacy(active) {
+        console.warn('CampaignApi.getCampaignsLegacy() is deprecated. Use getCampaigns() instead.');
+        return this.getCampaigns(active !== undefined ? { active } : undefined);
+    }
+}
+
+/**
+ * Platform-Agnostic Campaign Service
+ *
+ * Contains campaign business logic and operations that work across platforms.
+ * No framework dependencies - pure TypeScript business logic.
+ *
+ * Focuses only on actual backend capabilities.
+ */
+class CampaignService {
+    constructor(campaignApi) {
+        this.campaignApi = campaignApi;
+    }
+    // ==========================================
+    // PUBLIC OPERATIONS
+    // ==========================================
+    /**
+     * PUBLIC: Get all active campaigns
+     */
+    async getActiveCampaigns() {
+        return this.campaignApi.getActiveCampaigns();
+    }
+    /**
+     * PUBLIC: Get campaign by ID
+     */
+    async getCampaignById(id) {
+        return this.campaignApi.getCampaignById(id);
+    }
+    // ==========================================
+    // AUTHENTICATED OPERATIONS
+    // ==========================================
+    /**
+     * AUTH: Claim campaign
+     */
+    async claimCampaign(request) {
+        return this.campaignApi.claimCampaign(request);
+    }
+    /**
+     * AUTH: Get claims for logged user
+     */
+    async getClaimsForLoggedUser() {
+        return this.campaignApi.getClaimsForLoggedUser();
+    }
+    // ==========================================
+    // ADMIN OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Get campaigns with optional active filter
+     */
+    async getCampaigns(active) {
+        return this.campaignApi.getCampaigns(active !== undefined ? { active } : undefined);
+    }
+    /**
+     * ADMIN: Get campaign triggers
+     */
+    async getCampaignTriggers() {
+        return this.campaignApi.getCampaignTriggers();
+    }
+    /**
+     * ADMIN: Toggle campaign active status
+     */
+    async toggleCampaignActive(campaignId) {
+        return this.campaignApi.toggleCampaignActive(campaignId);
+    }
+    /**
+     * ADMIN: Toggle campaign testnet environment
+     */
+    async toggleCampaignTestnet(campaignId) {
+        return this.campaignApi.toggleCampaignTestnet(campaignId);
+    }
+    /**
+     * ADMIN: Create campaign
+     */
+    async createCampaign(campaign) {
+        return this.campaignApi.createCampaign(campaign);
+    }
+    /**
+     * ADMIN: Set campaign trigger
+     */
+    async setCampaignTrigger(campaignId, triggerId) {
+        return this.campaignApi.setCampaignTrigger(campaignId, triggerId);
+    }
+    /**
+     * ADMIN: Update campaign
+     */
+    async updateCampaign(campaignId, campaign) {
+        return this.campaignApi.updateCampaign(campaignId, campaign);
+    }
+    /**
+     * ADMIN: Create campaign token unit
+     */
+    async createCampaignTokenUnit(campaignId, campaignTokenUnit) {
+        return this.campaignApi.createCampaignTokenUnit(campaignId, campaignTokenUnit);
+    }
+    /**
+     * ADMIN: Delete campaign token unit
+     */
+    async deleteCampaignTokenUnit(campaignId, campaignTokenUnitId) {
+        return this.campaignApi.deleteCampaignTokenUnit(campaignId, campaignTokenUnitId);
+    }
+    /**
+     * ADMIN: Add business engagement to campaign
+     */
+    async addBusinessEngagementToCampaign(campaignId, campaignBusinessEngagement) {
+        return this.campaignApi.addBusinessEngagementToCampaign(campaignId, campaignBusinessEngagement);
+    }
+    /**
+     * ADMIN: Update campaign business engagement
+     */
+    async updateCampaignBusinessEngagement(campaignId, businessEngagementId, campaignBusinessEngagement) {
+        return this.campaignApi.updateCampaignBusinessEngagement(campaignId, businessEngagementId, campaignBusinessEngagement);
+    }
+    async deleteCampaignBusinessEngagement(campaignId, businessEngagementId) {
+        return this.campaignApi.deleteCampaignBusinessEngagement(campaignId, businessEngagementId);
+    }
+    /**
+     * ADMIN: Get all campaign claims
+     */
+    async getCampaignClaims() {
+        return this.campaignApi.getCampaignClaims();
+    }
+    /**
+     * ADMIN: Get campaign claims by user ID
+     */
+    async getCampaignClaimsByUserId(userId) {
+        return this.campaignApi.getCampaignClaimsByUserId(userId);
+    }
+    /**
+     * ADMIN: Get campaign claims by business ID
+     */
+    async getCampaignClaimsByBusinessId(businessId) {
+        return this.campaignApi.getCampaignClaimsByBusinessId(businessId);
+    }
+}
+
+/**
+ * @explorins/pers-sdk-campaign
+ *
+ * Platform-agnostic Campaign Domain SDK for PERS ecosystem
+ * Handles campaign operations across different authorization levels
+ */
+// API Layer
+/**
+ * Create a complete Campaign SDK instance
+ *
+ * @param apiClient - Configured PERS API client
+ * @returns Campaign SDK with flattened structure for better DX
+ */
+function createCampaignSDK(apiClient) {
+    const campaignApi = new CampaignApi(apiClient);
+    const campaignService = new CampaignService(campaignApi);
+    return {
+        // Direct access to service methods (primary interface)
+        // Public methods
+        getActiveCampaigns: () => campaignService.getActiveCampaigns(),
+        getCampaignById: (id) => campaignService.getCampaignById(id),
+        // Auth methods
+        claimCampaign: (request) => campaignService.claimCampaign(request),
+        getClaimsForLoggedUser: () => campaignService.getClaimsForLoggedUser(),
+        // Admin methods
+        getCampaigns: (active) => campaignService.getCampaigns(active),
+        getCampaignTriggers: () => campaignService.getCampaignTriggers(),
+        toggleCampaignActive: (campaignId) => campaignService.toggleCampaignActive(campaignId),
+        toggleCampaignTestnet: (campaignId) => campaignService.toggleCampaignTestnet(campaignId),
+        createCampaign: (campaign) => campaignService.createCampaign(campaign),
+        setCampaignTrigger: (campaignId, triggerId) => campaignService.setCampaignTrigger(campaignId, triggerId),
+        updateCampaign: (campaignId, campaign) => campaignService.updateCampaign(campaignId, campaign),
+        createCampaignTokenUnit: (campaignId, campaignTokenUnit) => campaignService.createCampaignTokenUnit(campaignId, campaignTokenUnit),
+        deleteCampaignTokenUnit: (campaignId, campaignTokenUnitId) => campaignService.deleteCampaignTokenUnit(campaignId, campaignTokenUnitId),
+        addBusinessEngagementToCampaign: (campaignId, campaignBusinessEngagement) => campaignService.addBusinessEngagementToCampaign(campaignId, campaignBusinessEngagement),
+        updateCampaignBusinessEngagement: (campaignId, businessEngagementId, campaignBusinessEngagement) => campaignService.updateCampaignBusinessEngagement(campaignId, businessEngagementId, campaignBusinessEngagement),
+        deleteCampaignBusinessEngagement: (campaignId, businessEngagementId) => campaignService.deleteCampaignBusinessEngagement(campaignId, businessEngagementId),
+        getCampaignClaims: () => campaignService.getCampaignClaims(),
+        getCampaignClaimsByUserId: (userId) => campaignService.getCampaignClaimsByUserId(userId),
+        getCampaignClaimsByBusinessId: (businessId) => campaignService.getCampaignClaimsByBusinessId(businessId),
+        // Advanced access for edge cases
+        api: campaignApi,
+        service: campaignService
+    };
+}
+
+/**
+ * Platform-Agnostic Donation API Client
+ *
+ * Handles donation operations using the PERS backend.
+ * Matches framework DonationApiService methods exactly.
+ */
+class DonationApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+    }
+    // ==========================================
+    // PUBLIC OPERATIONS
+    // ==========================================
+    /**
+     * PUBLIC: Get all donation types
+     * ✅ ONLY method actually used by framework
+     */
+    async getAllDonationTypes() {
+        return this.apiClient.get('/purchase/donation/type');
+    }
+}
+
+/**
+ * Platform-Agnostic Donation Service
+ *
+ * Contains donation business logic and operations that work across platforms.
+ * No framework dependencies - pure TypeScript business logic.
+ * Matches framework DonationApiService capabilities exactly.
+ */
+class DonationService {
+    constructor(donationApi) {
+        this.donationApi = donationApi;
+    }
+    // ==========================================
+    // PUBLIC OPERATIONS
+    // ==========================================
+    /**
+     * PUBLIC: Get all donation types
+     * ✅ ONLY method actually used by framework
+     */
+    async getAllDonationTypes() {
+        return this.donationApi.getAllDonationTypes();
+    }
+}
+
+/**
+ * @explorins/pers-sdk-donation
+ *
+ * Platform-agnostic Donation Domain SDK for PERS ecosystem
+ * Handles donation type retrieval for purchase flow integration
+ */
+// API Layer
+/**
+ * Create a complete Donation SDK instance
+ *
+ * @param apiClient - Configured PERS API client
+ * @returns Donation SDK with flattened structure for better DX
+ */
+function createDonationSDK(apiClient) {
+    const donationApi = new DonationApi(apiClient);
+    const donationService = new DonationService(donationApi);
+    return {
+        // Direct access to service methods (primary interface)
+        // ✅ FRAMEWORK ALIGNED: Only method actually used by framework
+        // Public methods
+        getAllDonationTypes: () => donationService.getAllDonationTypes(),
+        // Advanced access for edge cases
+        api: donationApi,
+        service: donationService
+    };
+}
+
+/**
+ * Platform-Agnostic Purchase API Client (RESTful Architecture)
+ *
+ * Handles purchase and payment operations using the PERS backend's new RESTful endpoints.
+ * Uses @explorins/pers-shared DTOs for consistency with backend.
+ *
+ * Migration Status: Updated to match /purchases controller (replaces /purchase endpoints)
+ *
+ * Available Access Levels:
+ * - PUBLIC: Project key authentication for catalog browsing and payment operations
+ * - USER: Requires user authentication JWT (purchase creation, history access)
+ * - ADMIN: Requires tenant admin privileges (not implemented in this client)
+ *
+ * Note: This SDK focuses on backend purchase operations only.
+ * Payment provider integrations (Stripe, etc.) should remain in infrastructure layer.
+ */
+class PurchaseApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+        this.basePath = '/purchases';
+    }
+    // ==========================================
+    // PUBLIC OPERATIONS (Project Key)
+    // ==========================================
+    /**
+     * PUBLIC: Get purchase tokens (Intelligent Access)
+     *
+     * RESTful endpoint: GET /purchases/tokens
+     * Replaces: GET /purchase/token
+     *
+     * INTELLIGENT ACCESS:
+     * - PUBLIC (Project Key): Returns active tokens only (active parameter ignored)
+     * - ADMIN (Tenant Admin JWT): Returns filtered results based on active parameter
+     */
+    async getPurchaseTokens(active) {
+        let url = `${this.basePath}/tokens`;
+        if (active !== undefined) {
+            url += `?active=${active}`;
+        }
+        return this.apiClient.get(url);
+    }
+    /**
+     * PUBLIC: Get donation types
+     *
+     * RESTful endpoint: GET /purchases/donation-types
+     * Replaces: GET /purchase/donation/type
+     */
+    async getDonationTypes() {
+        return this.apiClient.get(`${this.basePath}/donation-types`);
+    }
+    // ==========================================
+    // PAYMENT OPERATIONS (FINANCIAL - CRITICAL)
+    // ==========================================
+    /**
+     * PUBLIC: Create payment intent (FINANCIAL OPERATION)
+     *
+     * RESTful endpoint: POST /purchases/payment-intents
+     * Replaces: POST /purchase/payment-intent
+     *
+     * CRITICAL: Handles real money operations - tenant context required
+     */
+    async createPaymentIntent(amount, currency, receiptEmail, description) {
+        const body = {
+            amount,
+            currency,
+            receiptEmail,
+            description
+        };
+        return this.apiClient.post(`${this.basePath}/payment-intents`, body);
+    }
+    /**
+     * PUBLIC: Update payment intent (FINANCIAL OPERATION)
+     *
+     * RESTful endpoint: PUT /purchases/payment-intents/{paymentIntentId}
+     * Replaces: PUT /purchase/payment-intent/{paymentIntentId}
+     *
+     * CRITICAL: Handles real money operations - tenant context required
+     */
+    async updatePaymentIntent(paymentIntentId, amount, currency, receiptEmail, description) {
+        const body = {
+            amount,
+            currency,
+            receiptEmail,
+            description
+        };
+        return this.apiClient.put(`${this.basePath}/payment-intents/${paymentIntentId}`, body);
+    }
+    /**
+     * PUBLIC: Cancel payment intent (FINANCIAL OPERATION)
+     *
+     * RESTful endpoint: DELETE /purchases/payment-intents/{paymentIntentId}
+     * Replaces: DELETE /purchase/payment-intent/{paymentIntentId}
+     *
+     * CRITICAL: Handles real money operations - tenant context required
+     */
+    async cancelPaymentIntent(paymentIntentId) {
+        return this.apiClient.delete(`${this.basePath}/payment-intents/${paymentIntentId}`);
+    }
+    // ==========================================
+    // USER OPERATIONS (JWT + Project Key)
+    // ==========================================
+    /**
+     * USER: Create purchase (BUSINESS CRITICAL - FINANCIAL TRANSACTION)
+     *
+     * RESTful endpoint: POST /purchases
+     * Replaces: POST /purchase/auth
+     *
+     * USER-ONLY: Requires user authentication JWT for purchase creation
+     * CRITICAL: Real financial transaction with Stripe integration
+     */
+    async createUserPurchase(paymentIntentId, amount, purchaseTokenId, donationTypeId, donationAccountAddress) {
+        const body = {
+            quantity: amount,
+            purchaseTokenId: purchaseTokenId || '',
+            donationTypeId,
+            donationAccountAddress,
+            paymentIntentId
+        };
+        return this.apiClient.post(`${this.basePath}`, body);
+    }
+    /**
+     * USER: Get user purchase history
+     *
+     * RESTful endpoint: GET /purchases/me/history
+     * Replaces: GET /purchase/auth
+     *
+     * USER-ONLY: Get authenticated user's purchase history
+     * FINANCIAL RECORDS: User attribution critical for compliance
+     */
+    async getUserPurchaseHistory() {
+        return this.apiClient.get(`${this.basePath}/me/history`);
+    }
+    // ==========================================
+    // CONVENIENCE METHODS (Backward Compatibility)
+    // ==========================================
+    /**
+     * @deprecated Use getPurchaseTokens() instead
+     * Backward compatibility alias for getActivePurchaseTokens
+     */
+    async getActivePurchaseTokens(active = true) {
+        return this.getPurchaseTokens(active);
+    }
+    /**
+     * @deprecated Use createUserPurchase() instead
+     * Backward compatibility alias for createPurchase
+     */
+    async createPurchase(paymentIntentId, amount, purchaseTokenId, donationTypeId, donationAccountAddress) {
+        return this.createUserPurchase(paymentIntentId, amount, purchaseTokenId, donationTypeId, donationAccountAddress);
+    }
+    /**
+     * @deprecated Use getUserPurchaseHistory() instead
+     * Backward compatibility alias for getAllUserPurchases
+     */
+    async getAllUserPurchases() {
+        return this.getUserPurchaseHistory();
+    }
+}
+
+/**
+ * Platform-Agnostic Payment Service
+ *
+ * Contains payment business logic and operations that work across platforms.
+ * No framework dependencies - pure TypeScript business logic.
+ *
+ * Focuses only on actual backend capabilities.
+ * Payment provider logic (Stripe, etc.) should remain in infrastructure layer.
+ */
+class PaymentService {
+    constructor(paymentApi) {
+        this.paymentApi = paymentApi;
+    }
+    // ==========================================
+    // PUBLIC OPERATIONS
+    // ==========================================
+    /**
+     * PUBLIC: Get active purchase tokens
+     */
+    async getActivePurchaseTokens(active = true) {
+        return this.paymentApi.getActivePurchaseTokens(active);
+    }
+    /**
+     * PUBLIC: Create payment intent
+     */
+    async createPaymentIntent(amount, currency, receiptEmail, description) {
+        return this.paymentApi.createPaymentIntent(amount, currency, receiptEmail, description);
+    }
+    /**
+     * PUBLIC: Update payment intent
+     */
+    async updatePaymentIntent(paymentIntentId, amount, currency, receiptEmail, description) {
+        return this.paymentApi.updatePaymentIntent(paymentIntentId, amount, currency, receiptEmail, description);
+    }
+    /**
+     * PUBLIC: Cancel payment intent
+     */
+    async cancelPaymentIntent(paymentIntentId) {
+        return this.paymentApi.cancelPaymentIntent(paymentIntentId);
+    }
+    // ==========================================
+    // AUTHENTICATED OPERATIONS
+    // ==========================================
+    /**
+     * AUTH: Create purchase
+     */
+    async createPurchase(paymentIntentId, amount, purchaseTokenId, donationTypeId, donationAccountAddress) {
+        return this.paymentApi.createPurchase(paymentIntentId, amount, purchaseTokenId, donationTypeId, donationAccountAddress);
+    }
+    /**
+     * AUTH: Get all user purchases
+     */
+    async getAllUserPurchases() {
+        return this.paymentApi.getAllUserPurchases();
+    }
+}
+
+/**
+ * @explorins/pers-sdk-payment
+ *
+ * Platform-agnostic Payment Domain SDK for PERS ecosystem
+ * Handles payment intents, purchases, and purchase tokens
+ *
+ * Note: Payment provider integrations (Stripe, etc.) are kept separate
+ * in the infrastructure layer to maintain platform-agnostic principles.
+ */
+// API Layer
+/**
+ * Create a complete Payment SDK instance
+ *
+ * @param apiClient - Configured PERS API client
+ * @returns Payment SDK with flattened structure for better DX
+ */
+function createPaymentSDK(apiClient) {
+    const paymentApi = new PurchaseApi(apiClient);
+    const paymentService = new PaymentService(paymentApi);
+    return {
+        // Direct access to service methods (primary interface)
+        // Public methods
+        getActivePurchaseTokens: (active) => paymentService.getActivePurchaseTokens(active),
+        // ✅ FIXED: Proper type instead of any
+        createPaymentIntent: (amount, currency, receiptEmail, description) => paymentService.createPaymentIntent(amount, currency, receiptEmail, description),
+        // ✅ FIXED: Proper type instead of any
+        updatePaymentIntent: (paymentIntentId, amount, currency, receiptEmail, description) => paymentService.updatePaymentIntent(paymentIntentId, amount, currency, receiptEmail, description),
+        cancelPaymentIntent: (paymentIntentId) => paymentService.cancelPaymentIntent(paymentIntentId),
+        // Auth methods
+        createPurchase: (paymentIntentId, amount, purchaseTokenId, donationTypeId, donationAccountAddress) => paymentService.createPurchase(paymentIntentId, amount, purchaseTokenId, donationTypeId, donationAccountAddress),
+        getAllUserPurchases: () => paymentService.getAllUserPurchases(),
+        // Advanced access for edge cases
+        api: paymentApi,
+        service: paymentService
+    };
+}
+
+/**
+ * Platform-Agnostic Redemption API Client (UPDATED - RESTful Design)
+ *
+ * Updated to work with the new RESTful /redemptions endpoints.
+ * Handles redemption operations using the PERS backend with intelligent access detection.
+ * Uses @explorins/pers-shared DTOs for consistency with backend.
+ *
+ * Migration Update: Updated all endpoints from /redemption to /redemptions
+ * - Removed role revelation from URLs (no more /admin, /auth paths)
+ * - Added intelligent access detection for unified endpoints
+ * - Updated toggle endpoint to follow /status pattern
+ * - Enhanced redemption process with path-based IDs
+ */
+class RedemptionApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+        this.basePath = '/redemptions';
+    }
+    // ==========================================
+    // PUBLIC OPERATIONS (Project Key)
+    // ==========================================
+    /**
+     * PUBLIC: Get redemptions (intelligent access)
+     *
+     * NEW: Intelligent endpoint that adapts based on authentication
+     * - Public users: Get active redemptions only
+     * - Admin users: Get all redemptions with optional filtering
+     *
+     * Replaces: getActiveRedemptions() + getRedemptionsAsAdmin()
+     */
+    async getRedemptions(active) {
+        let url = `${this.basePath}`;
+        if (active !== undefined) {
+            url += `?active=${active}`;
+        }
+        return this.apiClient.get(url);
+    }
+    /**
+     * PUBLIC: Get active redemptions
+     *
+     * Updated: Now uses unified endpoint (backward compatibility)
+     */
+    async getActiveRedemptions() {
+        return this.getRedemptions(); // Will return active only for public access
+    }
+    /**
+     * PUBLIC: Get redemption types
+     *
+     * Updated: /redemption/type → /redemptions/types
+     */
+    async getRedemptionTypes() {
+        return this.apiClient.get(`${this.basePath}/types`);
+    }
+    /**
+     * PUBLIC: Get redemption by ID
+     *
+     * Updated: /redemption/:id → /redemptions/:id
+     */
+    async getRedemptionById(id) {
+        return this.apiClient.get(`${this.basePath}/${id}`);
+    }
+    /**
+     * PUBLIC: Get available supply for redemption
+     *
+     * Updated: /redemption/:id/available-supply → /redemptions/:id/available-supply
+     */
+    async getRedemptionAvailableSupply(id) {
+        return this.apiClient.get(`${this.basePath}/${id}/available-supply`);
+    }
+    // ==========================================
+    // USER OPERATIONS (JWT + Project Key)
+    // ==========================================
+    /**
+     * USER: Redeem a redemption
+     *
+     * Updated: /redemption/auth/redeem → /redemptions/:id/redeem
+     * Enhanced: Path-based redemption ID for better RESTful design
+     */
+    async redeemRedemption(redemptionId) {
+        const body = {
+            redemptionId: redemptionId,
+        };
+        return this.apiClient.post(`${this.basePath}/${redemptionId}/redeem`, body);
+    }
+    /**
+     * USER: Get user redemption history
+     *
+     * Updated: /redemption/auth/redeem → /redemptions/me/history
+     */
+    async getUserRedemptionHistory() {
+        return this.apiClient.get(`${this.basePath}/me/history`);
+    }
+    /**
+     * USER: Get user redemptions (backward compatibility)
+     *
+     * Deprecated: Use getUserRedemptionHistory() instead
+     */
+    async getUserRedeems() {
+        return this.getUserRedemptionHistory();
+    }
+    // ==========================================
+    // ADMIN OPERATIONS (Tenant Admin JWT)
+    // ==========================================
+    /**
+     * ADMIN: Get redemptions with filtering (using intelligent endpoint)
+     *
+     * Updated: /redemption/admin → /redemptions (intelligent access detection)
+     * The unified endpoint will detect admin privileges and allow filtering
+     */
+    async getRedemptionsAsAdmin(active) {
+        return this.getRedemptions(active); // Uses intelligent endpoint
+    }
+    /**
+     * ADMIN: Create redemption
+     *
+     * Updated: /redemption/admin → /redemptions
+     */
+    async createRedemption(redemption) {
+        return this.apiClient.post(`${this.basePath}`, redemption);
+    }
+    /**
+     * ADMIN: Update redemption
+     *
+     * Updated: /redemption/admin/:id → /redemptions/:id
+     */
+    async updateRedemption(id, redemptionCreateRequest) {
+        return this.apiClient.put(`${this.basePath}/${id}`, redemptionCreateRequest);
+    }
+    /**
+     * ADMIN: Toggle redemption status
+     *
+     * Updated: /redemption/admin/:id/toggle-active → /redemptions/:id/status
+     * Following standard /status pattern used across domains
+     */
+    async toggleRedemptionStatus(redemptionId) {
+        return this.apiClient.put(`${this.basePath}/${redemptionId}/status`, {});
+    }
+    /**
+     * ADMIN: Toggle redemption active (backward compatibility)
+     *
+     * Deprecated: Use toggleRedemptionStatus() instead
+     */
+    async toggleRedemptionActive(redemptionId) {
+        return this.toggleRedemptionStatus(redemptionId);
+    }
+    /**
+     * ADMIN: Delete redemption
+     *
+     * Updated: /redemption/admin/:id → /redemptions/:id
+     */
+    async deleteRedemption(id) {
+        return this.apiClient.delete(`${this.basePath}/${id}`);
+    }
+    /**
+     * ADMIN: Create redemption type
+     *
+     * Updated: /redemption/admin/type → /redemptions/types
+     */
+    async createRedemptionType(redemptionType) {
+        return this.apiClient.post(`${this.basePath}/types`, redemptionType);
+    }
+    // ==========================================
+    // TOKEN UNIT MANAGEMENT (Admin)
+    // ==========================================
+    /**
+     * ADMIN: Create redemption token unit
+     *
+     * Updated: /redemption/admin/:id/token-units → /redemptions/:id/token-units
+     */
+    async createRedemptionTokenUnit(redemptionId, redemptionTokenUnit) {
+        return this.apiClient.post(`${this.basePath}/${redemptionId}/token-units`, redemptionTokenUnit);
+    }
+    /**
+     * ADMIN: Update redemption token unit
+     *
+     * Updated: /redemption/admin/:id/token-units/:tokenUnitId → /redemptions/:id/token-units/:tokenUnitId
+     */
+    async updateRedemptionTokenUnit(redemptionId, tokenUnitId, redemptionTokenUnit) {
+        return this.apiClient.put(`${this.basePath}/${redemptionId}/token-units/${tokenUnitId}`, redemptionTokenUnit);
+    }
+    /**
+     * ADMIN: Delete redemption token unit
+     *
+     * Updated: /redemption/admin/:id/token-units/:tokenUnitId → /redemptions/:id/token-units/:tokenUnitId
+     */
+    async deleteRedemptionTokenUnit(redemptionId, redemptionTokenUnitId) {
+        return this.apiClient.delete(`${this.basePath}/${redemptionId}/token-units/${redemptionTokenUnitId}`);
+    }
+    // ==========================================
+    // BACKWARD COMPATIBILITY METHODS
+    // ==========================================
+    /**
+     * @deprecated Use getRedemptions() instead
+     * Backward compatibility for old admin endpoint
+     */
+    async getRedemptionsAdmin(active) {
+        return this.getRedemptionsAsAdmin(active);
+    }
+    /**
+     * @deprecated Use redeemRedemption() instead
+     * Backward compatibility for old redeem method
+     */
+    async redeem(redemptionId) {
+        return this.redeemRedemption(redemptionId);
+    }
+}
+
+/**
+ * Platform-Agnostic Redemption Service
+ *
+ * Contains redemption business logic and operations that work across platforms.
+ * No framework dependencies - pure TypeScript business logic.
+ *
+ * Focuses only on actual backend capabilities.
+ */
+class RedemptionService {
+    constructor(redemptionApi) {
+        this.redemptionApi = redemptionApi;
+    }
+    // ==========================================
+    // PUBLIC OPERATIONS
+    // ==========================================
+    /**
+     * PUBLIC: Get active redemptions
+     */
+    async getActiveRedemptions() {
+        return this.redemptionApi.getActiveRedemptions();
+    }
+    /**
+     * PUBLIC: Get redemption types
+     */
+    async getRedemptionTypes() {
+        return this.redemptionApi.getRedemptionTypes();
+    }
+    // ==========================================
+    // AUTHENTICATED OPERATIONS
+    // ==========================================
+    /**
+     * AUTH: Redeem a redemption
+     */
+    async redeemRedemption(redemptionId) {
+        return this.redemptionApi.redeemRedemption(redemptionId);
+    }
+    /**
+     * AUTH: Get user redemptions
+     */
+    async getUserRedeems() {
+        return this.redemptionApi.getUserRedeems();
+    }
+    // ==========================================
+    // ADMIN OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Get redemptions with optional active filter
+     */
+    async getRedemptionsAsAdmin(active) {
+        return this.redemptionApi.getRedemptionsAsAdmin(active);
+    }
+    /**
+     * ADMIN: Create redemption
+     */
+    async createRedemption(redemption) {
+        return this.redemptionApi.createRedemption(redemption);
+    }
+    /**
+     * ADMIN: Update redemption
+     */
+    async updateRedemption(id, redemptionCreateRequest) {
+        return this.redemptionApi.updateRedemption(id, redemptionCreateRequest); // ✅ CORRECTED: Fixed parameter
+    }
+    /**
+     * ADMIN: Toggle redemption active status
+     */
+    async toggleRedemptionActive(redemptionId) {
+        return this.redemptionApi.toggleRedemptionActive(redemptionId);
+    }
+    /**
+     * ADMIN: Create redemption token unit
+     */
+    async createRedemptionTokenUnit(redemptionId, redemptionTokenUnit) {
+        return this.redemptionApi.createRedemptionTokenUnit(redemptionId, redemptionTokenUnit);
+    }
+    /**
+     * ADMIN: Delete redemption token unit
+     */
+    async deleteRedemptionTokenUnit(redemptionId, redemptionTokenUnitId) {
+        return this.redemptionApi.deleteRedemptionTokenUnit(redemptionId, redemptionTokenUnitId);
+    }
+}
+
+/**
+ * @explorins/pers-sdk-redemption
+ *
+ * Platform-agnostic Redemption Domain SDK for PERS ecosystem
+ * Handles redemption operations across different authorization levels
+ */
+// API Layer
+/**
+ * Create a complete Redemption SDK instance
+ *
+ * @param apiClient - Configured PERS API client
+ * @returns Redemption SDK with flattened structure for better DX
+ */
+function createRedemptionSDK(apiClient) {
+    const redemptionApi = new RedemptionApi(apiClient);
+    const redemptionService = new RedemptionService(redemptionApi);
+    return {
+        // Direct access to service methods (primary interface)
+        // Public methods
+        getActiveRedemptions: () => redemptionService.getActiveRedemptions(),
+        getRedemptionTypes: () => redemptionService.getRedemptionTypes(),
+        // Auth methods
+        redeemRedemption: (redemptionId) => redemptionService.redeemRedemption(redemptionId),
+        getUserRedeems: () => redemptionService.getUserRedeems(),
+        // Admin methods
+        getRedemptionsAsAdmin: (active) => redemptionService.getRedemptionsAsAdmin(active),
+        createRedemption: (redemption) => redemptionService.createRedemption(redemption),
+        updateRedemption: (id, redemptionCreateRequest) => redemptionService.updateRedemption(id, redemptionCreateRequest),
+        toggleRedemptionActive: (redemptionId) => redemptionService.toggleRedemptionActive(redemptionId),
+        createRedemptionTokenUnit: (redemptionId, redemptionTokenUnit) => redemptionService.createRedemptionTokenUnit(redemptionId, redemptionTokenUnit),
+        deleteRedemptionTokenUnit: (redemptionId, redemptionTokenUnitId) => redemptionService.deleteRedemptionTokenUnit(redemptionId, redemptionTokenUnitId),
+        // Advanced access for edge cases
+        api: redemptionApi,
+        service: redemptionService
+    };
+}
+
+/**
+ * Platform-Agnostic Tenant API Client
+ *
+ * Handles tenant and admin operations using the PERS backend.
+ * Matches framework TenantApiService methods exactly.
+ *
+ * Note: Special header handling (bypass-auth-interceptor) should be handled by PersApiClient internally
+ * or through endpoint-specific configuration.
+ */
+class TenantApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+        this.basePath = '/tenants';
+        this.adminPath = '/admins';
+    }
+    // ==========================================
+    // PUBLIC OPERATIONS
+    // ==========================================
+    /**
+     * PUBLIC: Get tenant public information
+     * ✅ FIXED: Matches framework cache busting pattern exactly
+     */
+    async getRemoteTenant() {
+        const timestamp = Date.now().toString();
+        const url = `${this.basePath}/public?date=${timestamp}`;
+        return this.apiClient.get(url);
+    }
+    /**
+     * PUBLIC: Get remote login token
+     */
+    async getRemoteLoginToken() {
+        return this.apiClient.get(`${this.basePath}/login-token`);
+    }
+    /**
+     * PUBLIC: Get remote client configuration
+     * ✅ FIXED: Removed second parameter - PersApiClient handles bypass auth internally
+     * Note: The /tenants/client-config endpoint should be configured to bypass auth at the API client level
+     */
+    async getRemoteClientConfig() {
+        return this.apiClient.get(`${this.basePath}/client-config`);
+    }
+    // ==========================================
+    // ADMIN OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Update tenant information
+     * ✅ FIXED: Uses TenantPublicDTO directly like framework
+     */
+    async updateRemoteTenant(tenantData) {
+        return this.apiClient.put(`${this.basePath}`, tenantData);
+    }
+    /**
+     * ADMIN: Get all tenant admins
+     */
+    async getAdmins() {
+        return this.apiClient.get(`${this.adminPath}`);
+    }
+    /**
+     * ADMIN: Create new admin
+     * ✅ FIXED: Renamed to match framework postAdmin method
+     */
+    async postAdmin(adminData) {
+        return this.apiClient.post(`${this.adminPath}`, adminData);
+    }
+    /**
+     * ADMIN: Update admin (toggle tenant association)
+     * ✅ FIXED: Renamed to match framework putAdmin method
+     */
+    async putAdmin(adminId, adminData) {
+        return this.apiClient.put(`${this.adminPath}/${adminId}/tenant`, adminData);
+    }
+}
+
+/**
+ * Platform-Agnostic Tenant Service
+ *
+ * Contains tenant business logic and operations that work across platforms.
+ * No framework dependencies - pure TypeScript business logic.
+ * Matches framework TenantApiService capabilities exactly.
+ */
+class TenantService {
+    constructor(tenantApi) {
+        this.tenantApi = tenantApi;
+    }
+    // ==========================================
+    // PUBLIC OPERATIONS
+    // ==========================================
+    /**
+     * PUBLIC: Get tenant public information
+     */
+    async getRemoteTenant() {
+        return this.tenantApi.getRemoteTenant();
+    }
+    /**
+     * PUBLIC: Get remote login token
+     */
+    async getRemoteLoginToken() {
+        return this.tenantApi.getRemoteLoginToken();
+    }
+    /**
+     * PUBLIC: Get remote client configuration
+     */
+    async getRemoteClientConfig() {
+        return this.tenantApi.getRemoteClientConfig();
+    }
+    // ==========================================
+    // ADMIN OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Update tenant information
+     * ✅ FIXED: Uses TenantPublicDTO directly like framework
+     */
+    async updateRemoteTenant(tenantData) {
+        return this.tenantApi.updateRemoteTenant(tenantData);
+    }
+    /**
+     * ADMIN: Get all tenant admins
+     */
+    async getAdmins() {
+        return this.tenantApi.getAdmins();
+    }
+    /**
+     * ADMIN: Create new admin
+     * ✅ FIXED: Renamed to match framework postAdmin method
+     */
+    async postAdmin(adminData) {
+        return this.tenantApi.postAdmin(adminData);
+    }
+    /**
+     * ADMIN: Update admin (toggle tenant association)
+     * ✅ FIXED: Renamed to match framework putAdmin method
+     */
+    async putAdmin(adminId, adminData) {
+        return this.tenantApi.putAdmin(adminId, adminData);
+    }
+}
+
+/**
+ * @explorins/pers-sdk-tenant
+ *
+ * Platform-agnostic Tenant Domain SDK for PERS ecosystem
+ * Handles tenant management and admin operations for multi-tenant architecture
+ */
+// API Layer
+/**
+ * Create a complete Tenant SDK instance
+ *
+ * @param apiClient - Configured PERS API client
+ * @returns Tenant SDK with flattened structure for better DX
+ */
+function createTenantSDK(apiClient) {
+    const tenantApi = new TenantApi(apiClient);
+    const tenantService = new TenantService(tenantApi);
+    return {
+        // Direct access to service methods (primary interface)
+        // ✅ FRAMEWORK ALIGNED: Only methods actually used by framework
+        // Public methods
+        getRemoteTenant: () => tenantService.getRemoteTenant(),
+        getRemoteLoginToken: () => tenantService.getRemoteLoginToken(),
+        getRemoteClientConfig: () => tenantService.getRemoteClientConfig(),
+        // Admin methods - ✅ FIXED: Matches framework method names exactly
+        updateRemoteTenant: (tenantData) => tenantService.updateRemoteTenant(tenantData),
+        getAdmins: () => tenantService.getAdmins(),
+        postAdmin: (adminData) => tenantService.postAdmin(adminData),
+        putAdmin: (adminId, adminData) => tenantService.putAdmin(adminId, adminData),
+        // Advanced access for edge cases
+        api: tenantApi,
+        service: tenantService
+    };
+}
+
+class TokenApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+        this.basePath = '/tokens';
+    }
+    // ==========================================
+    // PUBLIC OPERATIONS
+    // ==========================================
+    /**
+     * PUBLIC: Get all remote tokens
+     * ENHANCED: Added admin filtering capability
+     */
+    async getRemoteTokens(includeInactive = false) {
+        const url = includeInactive ? `${this.basePath}?active=false` : `${this.basePath}`;
+        return this.apiClient.get(url);
+    }
+    /**
+     * PUBLIC: Get all remote token types
+     */
+    async getRemoteTokenTypes() {
+        return this.apiClient.get(`${this.basePath}/types`);
+    }
+    /**
+     * PUBLIC: Get active point token (was credit token)
+     */
+    async getRemoteActiveCreditToken() {
+        return this.apiClient.get(`${this.basePath}/points`);
+    }
+    /**
+     * PUBLIC: Get reward tokens
+     * ENHANCED: Added admin filtering capability
+     */
+    async getRemoteRewardTokens(includeInactive = false) {
+        const url = includeInactive ? `${this.basePath}/rewards?active=false` : `${this.basePath}/rewards`;
+        return this.apiClient.get(url);
+    }
+    /**
+     * PUBLIC: Get stamp tokens (was status tokens)
+     * ENHANCED: Added admin filtering capability
+     */
+    async getRemoteStatusTokens(includeInactive = false) {
+        const url = includeInactive ? `${this.basePath}/stamps?active=false` : `${this.basePath}/stamps`;
+        return this.apiClient.get(url);
+    }
+    /**
+     * PUBLIC: Get token by contract address
+     */
+    async getTokenByContractAddress(contractAddress, contractTokenId) {
+        let url = `${this.basePath}/address/${contractAddress}`;
+        if (contractTokenId) {
+            url += `?contractTokenId=${contractTokenId}`;
+        }
+        return this.apiClient.get(url);
+    }
+    // ==========================================
+    // ADMIN OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Create new token
+     */
+    async createToken(tokenData) {
+        return this.apiClient.post(`${this.basePath}`, tokenData);
+    }
+    /**
+     * ADMIN: Update token
+     */
+    async updateToken(tokenId, tokenData) {
+        return this.apiClient.put(`${this.basePath}/${tokenId}`, tokenData);
+    }
+    /**
+     * ADMIN: Toggle token active status
+     * FIXED: Now calls correct endpoint
+     */
+    async toggleTokenActive(tokenId) {
+        return this.apiClient.put(`${this.basePath}/${tokenId}/status`, {});
+    }
+    /**
+     * ADMIN: Set mainnet contract address
+     */
+    async setMainnetContract(tokenId, contractAddress, chainId) {
+        return this.apiClient.put(`${this.basePath}/${tokenId}/mainnet`, {
+            contractAddress,
+            chainId
+        });
+    }
+    /**
+     * ADMIN: Create token metadata
+     */
+    async createTokenMetadata(tokenId, tokenData) {
+        return this.apiClient.post(`${this.basePath}/${tokenId}/metadata`, tokenData);
+    }
+    /**
+     * ADMIN: Toggle token metadata status (separate from token status)
+     */
+    async toggleTokenMetadataStatus(metadataId) {
+        return this.apiClient.put(`${this.basePath}/metadata/${metadataId}/status`, {});
+    }
+    /**
+     * ADMIN: Create token type
+     */
+    async createTokenType(tokenType) {
+        return this.apiClient.post(`${this.basePath}/types`, tokenType);
+    }
+}
+
+/**
+ * Platform-Agnostic Token Service
+ *
+ * Contains token business logic and operations that work across platforms.
+ * No framework dependencies - pure TypeScript business logic.
+ * Matches framework TokenApiService capabilities exactly.
+ */
+class TokenService {
+    constructor(tokenApi) {
+        this.tokenApi = tokenApi;
+    }
+    // ==========================================
+    // PUBLIC OPERATIONS
+    // ==========================================
+    /**
+     * PUBLIC: Get all remote tokens
+     */
+    async getRemoteTokens() {
+        return this.tokenApi.getRemoteTokens();
+    }
+    /**
+     * PUBLIC: Get all remote token types
+     */
+    async getRemoteTokenTypes() {
+        return this.tokenApi.getRemoteTokenTypes();
+    }
+    /**
+     * PUBLIC: Get active credit token
+     */
+    async getRemoteActiveCreditToken() {
+        return this.tokenApi.getRemoteActiveCreditToken();
+    }
+    /**
+     * PUBLIC: Get reward tokens
+     */
+    async getRemoteRewardTokens() {
+        return this.tokenApi.getRemoteRewardTokens();
+    }
+    /**
+     * PUBLIC: Get status tokens
+     */
+    async getRemoteStatusTokens() {
+        return this.tokenApi.getRemoteStatusTokens();
+    }
+    /**
+     * PUBLIC: Get token by contract address
+     * ✅ FIXED: Matches framework parameter types exactly
+     */
+    async getTokenByContractAddress(contractAddress, contractTokenId) {
+        return this.tokenApi.getTokenByContractAddress(contractAddress, contractTokenId);
+    }
+    // ==========================================
+    // ADMIN OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Create token metadata
+     */
+    async createTokenMetadata(tokenId, tokenData) {
+        return this.tokenApi.createTokenMetadata(tokenId, tokenData);
+    }
+    /**
+     * ADMIN: Toggle token active status
+     */
+    async toggleTokenActive(tokenId) {
+        return this.tokenApi.toggleTokenActive(tokenId);
+    }
+    /**
+     * ADMIN: Create new token
+     */
+    async createToken(tokenData) {
+        return this.tokenApi.createToken(tokenData);
+    }
+    /**
+     * ADMIN: Update token
+     */
+    async updateToken(tokenId, tokenData) {
+        return this.tokenApi.updateToken(tokenId, tokenData);
+    }
+    /**
+     * ADMIN: Set mainnet contract address
+     */
+    async setMainnetContract(tokenId, contractAddress, chainId) {
+        return this.tokenApi.setMainnetContract(tokenId, contractAddress, chainId);
+    }
+    /**
+     * ADMIN: Toggle token metadata status
+     */
+    async toggleTokenMetadataStatus(metadataId) {
+        return this.tokenApi.toggleTokenMetadataStatus(metadataId);
+    }
+    /**
+     * ADMIN: Create token type
+     */
+    async createTokenType(tokenType) {
+        return this.tokenApi.createTokenType(tokenType);
+    }
+}
+
+/**
+ * Token SDK - Class-based Promise SDK for Token Operations
+ *
+ * Modern, performant SDK with direct method access and excellent TypeScript support.
+ * Optimized for bundle size, performance, and developer experience.
+ *
+ * Usage:
+ *   const tokenSDK = new TokenSDK(apiClient);
+ *   const tokens = await tokenSDK.getTokens();
+ *   const creditToken = await tokenSDK.getActiveCreditToken();
+ */
+class TokenSDK {
+    constructor(apiClient) {
+        this.tokenApi = new TokenApi(apiClient);
+        this.tokenService = new TokenService(this.tokenApi);
+    }
+    // ==========================================
+    // CONVENIENCE METHODS - Direct Promise API
+    // ==========================================
+    // Simplified method names for better developer experience
+    /**
+     * Get all tokens
+     * @returns Promise with all available tokens
+     */
+    async getTokens() {
+        return this.tokenService.getRemoteTokens();
+    }
+    /**
+     * Get all token types
+     * @returns Promise with all available token types
+     */
+    async getTokenTypes() {
+        return this.tokenService.getRemoteTokenTypes();
+    }
+    /**
+     * Get the active credit token
+     * @returns Promise with the current active credit token
+     */
+    async getActiveCreditToken() {
+        return this.tokenService.getRemoteActiveCreditToken();
+    }
+    /**
+     * Get all reward tokens
+     * @returns Promise with all reward tokens
+     */
+    async getRewardTokens() {
+        return this.tokenService.getRemoteRewardTokens();
+    }
+    /**
+     * Get all status tokens
+     * @returns Promise with all status tokens
+     */
+    async getStatusTokens() {
+        return this.tokenService.getRemoteStatusTokens();
+    }
+    /**
+     * Get token by contract address
+     * @param contractAddress - The contract address to search for
+     * @param contractTokenId - Optional contract token ID
+     * @returns Promise with the matching token
+     */
+    async getTokenByContract(contractAddress, contractTokenId = null) {
+        return this.tokenService.getTokenByContractAddress(contractAddress, contractTokenId);
+    }
+    // ==========================================
+    // ADMIN METHODS - Token Management
+    // ==========================================
+    /**
+     * Create token metadata
+     * @param tokenId - The token ID
+     * @param tokenData - The token storage data
+     * @returns Promise with the updated token
+     */
+    async createTokenMetadata(tokenId, tokenData) {
+        return this.tokenService.createTokenMetadata(tokenId, tokenData);
+    }
+    /**
+     * Toggle token active status
+     * @param tokenId - The token ID to toggle
+     * @returns Promise with the updated token
+     */
+    async toggleTokenActive(tokenId) {
+        return this.tokenService.toggleTokenActive(tokenId);
+    }
+    /**
+     * Create a new token
+     * @param tokenData - The token creation data
+     * @returns Promise with the created token
+     */
+    async createToken(tokenData) {
+        return this.tokenService.createToken(tokenData);
+    }
+    /**
+     * Update an existing token
+     * @param tokenId - The token ID to update
+     * @param tokenData - The token update data
+     * @returns Promise with the updated token
+     */
+    async updateToken(tokenId, tokenData) {
+        return this.tokenService.updateToken(tokenId, tokenData);
+    }
+    /**
+     * Set mainnet contract address for a token
+     * @param tokenId - The token ID
+     * @param contractAddress - The contract address
+     * @param chainId - The blockchain chain ID
+     * @returns Promise with the updated token
+     */
+    async setMainnetContract(tokenId, contractAddress, chainId) {
+        return this.tokenService.setMainnetContract(tokenId, contractAddress, chainId);
+    }
+    /**
+     * Toggle token metadata status
+     * @param metadataId - The metadata ID to toggle
+     * @returns Promise with the updated metadata
+     */
+    async toggleTokenMetadataStatus(metadataId) {
+        return this.tokenService.toggleTokenMetadataStatus(metadataId);
+    }
+    /**
+     * Create a new token type
+     * @param tokenType - The token type data
+     * @returns Promise with the created token type
+     */
+    async createTokenType(tokenType) {
+        return this.tokenService.createTokenType(tokenType);
+    }
+    // ==========================================
+    // ADVANCED ACCESS - For Complex Operations
+    // ==========================================
+    /**
+     * Get direct access to the token service for advanced operations
+     * @returns The underlying TokenService instance
+     */
+    getTokenService() {
+        return this.tokenService;
+    }
+    /**
+     * Get direct access to the token API for low-level operations
+     * @returns The underlying TokenApi instance
+     */
+    getTokenApi() {
+        return this.tokenApi;
+    }
+    // ==========================================
+    // FRAMEWORK COMPATIBILITY METHODS
+    // ==========================================
+    // These maintain compatibility with existing framework method names
+    /**
+     * @deprecated Use getTokens() instead
+     * Framework compatibility method
+     */
+    async getRemoteTokens() {
+        return this.getTokens();
+    }
+    /**
+     * @deprecated Use getTokenTypes() instead
+     * Framework compatibility method
+     */
+    async getRemoteTokenTypes() {
+        return this.getTokenTypes();
+    }
+    /**
+     * @deprecated Use getActiveCreditToken() instead
+     * Framework compatibility method
+     */
+    async getRemoteActiveCreditToken() {
+        return this.getActiveCreditToken();
+    }
+    /**
+     * @deprecated Use getRewardTokens() instead
+     * Framework compatibility method
+     */
+    async getRemoteRewardTokens() {
+        return this.getRewardTokens();
+    }
+    /**
+     * @deprecated Use getStatusTokens() instead
+     * Framework compatibility method
+     */
+    async getRemoteStatusTokens() {
+        return this.getStatusTokens();
+    }
+    /**
+     * @deprecated Use getTokenByContract() instead
+     * Framework compatibility method
+     */
+    async getTokenByContractAddress(contractAddress, contractTokenId) {
+        return this.getTokenByContract(contractAddress, contractTokenId);
+    }
+}
+
+/**
+ * Abstract Base Token Service - Explicit Initialization Pattern
+ *
+ * Platform-agnostic token operations with Promise-based API.
+ * Framework services extend this and control initialization lifecycle.
+ *
+ * Benefits:
+ * - Explicit initialization control
+ * - Better error boundaries
+ * - Clear lifecycle management
+ * - Testable initialization state
+ * - Zero framework dependencies
+ */
+class BaseTokenService {
+    constructor() {
+        this._isInitialized = false;
+    }
+    // ==========================================
+    // INITIALIZATION LIFECYCLE
+    // ==========================================
+    /**
+     * LIFECYCLE: Initialize token service with API client
+     * Must be called before using any token operations
+     */
+    initializeTokenService(apiClient) {
+        if (!apiClient) {
+            throw new Error('Cannot initialize TokenService: apiClient is null or undefined');
+        }
+        if (!this._isInitialized) {
+            this._tokenApi = new TokenApi(apiClient);
+            this._tokenBusinessService = new TokenService(this._tokenApi);
+            this._isInitialized = true;
+        }
+    }
+    /**
+     * LIFECYCLE: Check if token service is initialized
+     */
+    get isTokenServiceInitialized() {
+        return this._isInitialized;
+    }
+    /**
+     * INTERNAL: Get token business service (throws if not initialized)
+     */
+    get tokenBusinessService() {
+        if (!this._tokenBusinessService) {
+            throw new Error('TokenService not initialized. Call initializeTokenService(apiClient) first.');
+        }
+        return this._tokenBusinessService;
+    }
+    // ==========================================
+    // PUBLIC OPERATIONS
+    // ==========================================
+    /**
+     * PUBLIC: Get all remote tokens
+     */
+    getRemoteTokens() {
+        return this.tokenBusinessService.getRemoteTokens();
+    }
+    /**
+     * PUBLIC: Get all remote token types
+     */
+    getRemoteTokenTypes() {
+        return this.tokenBusinessService.getRemoteTokenTypes();
+    }
+    /**
+     * PUBLIC: Get active credit token
+     */
+    getRemoteActiveCreditToken() {
+        return this.tokenBusinessService.getRemoteActiveCreditToken();
+    }
+    /**
+     * PUBLIC: Get reward tokens
+     */
+    getRemoteRewardTokens() {
+        return this.tokenBusinessService.getRemoteRewardTokens();
+    }
+    /**
+     * PUBLIC: Get status tokens
+     */
+    getRemoteStatusTokens() {
+        return this.tokenBusinessService.getRemoteStatusTokens();
+    }
+    /**
+     * PUBLIC: Get token by contract address
+     */
+    getTokenByContractAddress(contractAddress, contractTokenId) {
+        return this.tokenBusinessService.getTokenByContractAddress(contractAddress, contractTokenId);
+    }
+    // ==========================================
+    // ADMIN OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Create token metadata
+     */
+    createTokenMetadata(tokenId, tokenData) {
+        return this.tokenBusinessService.createTokenMetadata(tokenId, tokenData);
+    }
+    /**
+     * ADMIN: Toggle token active status
+     */
+    toggleTokenActive(tokenId) {
+        return this.tokenBusinessService.toggleTokenActive(tokenId);
+    }
+    /**
+     * ADMIN: Create new token
+     */
+    createToken(tokenData) {
+        return this.tokenBusinessService.createToken(tokenData);
+    }
+    /**
+     * ADMIN: Update token
+     */
+    updateToken(tokenId, tokenData) {
+        return this.tokenBusinessService.updateToken(tokenId, tokenData);
+    }
+    /**
+     * ADMIN: Set mainnet contract address
+     */
+    setMainnetContract(tokenId, contractAddress, chainId) {
+        return this.tokenBusinessService.setMainnetContract(tokenId, contractAddress, chainId);
+    }
+    /**
+     * ADMIN: Toggle token metadata status
+     */
+    toggleTokenMetadataStatus(metadataId) {
+        return this.tokenBusinessService.toggleTokenMetadataStatus(metadataId);
+    }
+    /**
+     * ADMIN: Create token type
+     */
+    createTokenType(tokenType) {
+        return this.tokenBusinessService.createTokenType(tokenType);
+    }
+}
+
+/**
+ * Platform-Agnostic User API Client
+ *
+ * Handles user operations using the PERS backend RESTful API.
+ * Updated to use new /users endpoints with enhanced security and consistency.
+ * Maintains framework UserApiService method compatibility.
+ */
+class UserApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+        this.basePath = '/users';
+    }
+    // ==========================================
+    // PUBLIC OPERATIONS
+    // ==========================================
+    /**
+     * PUBLIC: Get all users public profiles with optional filtering
+     * ✅ UPDATED: Uses new RESTful /users/public endpoint
+     */
+    async getAllUsersPublicProfiles(filter = null) {
+        let url = `${this.basePath}/public`;
+        if (filter) {
+            // ✅ MAINTAINED: Same parameter pattern for compatibility
+            const params = new URLSearchParams();
+            params.set('filterKey', filter.key);
+            params.set('filterValue', filter.value);
+            url += `?${params.toString()}`;
+        }
+        return this.apiClient.get(url);
+    }
+    // ==========================================
+    // AUTHENTICATED OPERATIONS
+    // ==========================================
+    /**
+     * AUTH: Get current authenticated user
+     * ✅ UPDATED: Uses new RESTful /users/me endpoint
+     */
+    async getRemoteUser() {
+        return this.apiClient.get(`${this.basePath}/me`);
+    }
+    /**
+     * AUTH: Update current authenticated user
+     * ✅ UPDATED: Uses new RESTful /users/me endpoint
+     */
+    async updateRemoteUser(updateRequest) {
+        return this.apiClient.put(`${this.basePath}/me`, updateRequest);
+    }
+    // ==========================================
+    // ADMIN OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Get all remote users with query parameters
+     * ✅ UPDATED: Uses new RESTful /users endpoint with role-based access
+     * Note: Admin users get full data, non-admin users get public profiles only
+     */
+    async getAllRemoteUsers() {
+        // ✅ MAINTAINED: Same merge=soft parameter for compatibility
+        const url = `${this.basePath}?merge=soft`;
+        return this.apiClient.get(url);
+    }
+    /**
+     * ADMIN: Update user as admin
+     * ✅ UPDATED: Uses new RESTful /users/{id} endpoint
+     */
+    async updateUserAsAdmin(id, userData) {
+        return this.apiClient.put(`${this.basePath}/${id}`, userData);
+    }
+    /**
+     * ADMIN: Toggle user active status
+     * ✅ UPDATED: Uses new consistent /users/{id}/status endpoint
+     * Enhanced: Follows RESTful status management pattern across all domains
+     */
+    async toggleUserActiveStatusByUser(user) {
+        return this.apiClient.put(`${this.basePath}/${user.id}/status`, {});
+    }
+    /**
+     * ADMIN: Get user by unique identifier
+     * ✅ UPDATED: Uses new RESTful /users/{id} endpoint
+     */
+    async getUserByUniqueIdentifier(id) {
+        return this.apiClient.get(`${this.basePath}/${id}`);
+    }
+}
+
+/**
+ * Platform-Agnostic User Service
+ *
+ * Contains user business logic and operations that work across platforms.
+ * No framework dependencies - pure TypeScript business logic.
+ * Matches framework UserApiService capabilities exactly.
+ */
+class UserService {
+    constructor(userApi) {
+        this.userApi = userApi;
+    }
+    // ==========================================
+    // PUBLIC OPERATIONS
+    // ==========================================
+    /**
+     * PUBLIC: Get all users public profiles with optional filtering
+     * ✅ FIXED: Uses framework-compatible inline filter type
+     */
+    async getAllUsersPublicProfiles(filter = null) {
+        return this.userApi.getAllUsersPublicProfiles(filter);
+    }
+    // ==========================================
+    // AUTHENTICATED OPERATIONS
+    // ==========================================
+    /**
+     * AUTH: Get current authenticated user
+     */
+    async getRemoteUser() {
+        return this.userApi.getRemoteUser();
+    }
+    /**
+     * AUTH: Update current authenticated user
+     */
+    async updateRemoteUser(updateRequest) {
+        return this.userApi.updateRemoteUser(updateRequest);
+    }
+    // ==========================================
+    // ADMIN OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Get all remote users
+     * ✅ FIXED: Matches API method signature (no parameters needed)
+     */
+    async getAllRemoteUsers() {
+        return this.userApi.getAllRemoteUsers();
+    }
+    /**
+     * ADMIN: Update user as admin
+     */
+    async updateUserAsAdmin(id, userData) {
+        return this.userApi.updateUserAsAdmin(id, userData);
+    }
+    async getUserByUniqueIdentifier(id) {
+        return this.userApi.getUserByUniqueIdentifier(id);
+    }
+    /**
+     * ADMIN: Toggle user active status by user object
+     * ✅ FIXED: Matches API method signature exactly
+     */
+    async toggleUserActiveStatusByUser(user) {
+        return this.userApi.toggleUserActiveStatusByUser(user);
+    }
+}
+
+/**
+ * @explorins/pers-sdk-user
+ *
+ * Platform-agnostic User Domain SDK for PERS ecosystem
+ * Handles user management, profiles, and authentication operations
+ */
+// API Layer
+/**
+ * Create a complete User SDK instance
+ *
+ * @param apiClient - Configured PERS API client
+ * @returns User SDK with flattened structure for better DX
+ */
+function createUserSDK(apiClient) {
+    const userApi = new UserApi(apiClient);
+    const userService = new UserService(userApi);
+    return {
+        // Direct access to service methods (primary interface)
+        // Public methods - matches framework exactly
+        getAllUsersPublicProfiles: (filter = null) => userService.getAllUsersPublicProfiles(filter),
+        // Auth methods - matches framework exactly
+        getRemoteUser: () => userService.getRemoteUser(),
+        updateRemoteUser: (updateRequest) => userService.updateRemoteUser(updateRequest),
+        // Admin methods - matches framework exactly
+        getAllRemoteUsers: () => userService.getAllRemoteUsers(),
+        updateUserAsAdmin: (id, userData) => userService.updateUserAsAdmin(id, userData),
+        toggleUserActiveStatusByUser: (user) => userService.toggleUserActiveStatusByUser(user),
+        getUserByUniqueIdentifier: (id) => userService.getUserByUniqueIdentifier(id),
+        // Advanced access for edge cases
+        api: userApi,
+        service: userService
+    };
+}
+
+/**
+ * Platform-Agnostic User Status API Client
+ *
+ * Handles user status operations using the PERS backend.
+ * Matches framework UserStatusApiService methods exactly.
+ *
+ * ✅ UPDATED: All endpoints updated to new RESTful /users patterns
+ *
+ * Error handling patterns follow framework implementation:
+ * - getRemoteEarnedUserStatus() uses silent fallback (empty array)
+ * - Other operations throw errors for proper error handling
+ */
+class UserStatusApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+        this.basePath = '/users';
+    }
+    // ==========================================
+    // PUBLIC OPERATIONS
+    // ==========================================
+    /**
+     * PUBLIC: Get remote user status types
+     * ✅ UPDATED: /user/status-type → /users/status-types
+     */
+    async getRemoteUserStatusTypes() {
+        try {
+            return await this.apiClient.get(`${this.basePath}/status-types`);
+        }
+        catch (error) {
+            console.error('Error getting user status types', error);
+            throw error;
+        }
+    }
+    // ==========================================
+    // AUTHENTICATED OPERATIONS
+    // ==========================================
+    /**
+     * AUTH: Get earned user status for authenticated user
+     * ✅ UPDATED: /user/auth/status → /users/me/status
+     * ✅ FIXED: Returns UserStatusTypeDTO[] to match framework exactly
+     * Note: Uses silent fallback pattern from framework - returns empty array on error
+     */
+    async getRemoteEarnedUserStatus() {
+        try {
+            return await this.apiClient.get(`${this.basePath}/me/status`);
+        }
+        catch (error) {
+            console.error('Error getting user status', error);
+            // ✅ FIXED: Silent fallback pattern from framework implementation
+            return [];
+        }
+    }
+    // ==========================================
+    // ADMIN OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Create user status type
+     * ✅ UPDATED: /user/admin/status-type → /users/status-types
+     */
+    async createUserStatusType(userStatusType) {
+        try {
+            return await this.apiClient.post(`${this.basePath}/status-types`, userStatusType);
+        }
+        catch (error) {
+            console.error('Error creating user status type', error);
+            throw error;
+        }
+    }
+}
+
+/**
+ * Platform-Agnostic User Status Service
+ *
+ * Contains user status business logic and operations that work across platforms.
+ * No framework dependencies - pure TypeScript business logic.
+ * Matches framework UserStatusApiService capabilities exactly.
+ */
+class UserStatusService {
+    constructor(userStatusApi) {
+        this.userStatusApi = userStatusApi;
+    }
+    // ==========================================
+    // PUBLIC OPERATIONS
+    // ==========================================
+    /**
+     * PUBLIC: Get remote user status types
+     */
+    async getRemoteUserStatusTypes() {
+        return this.userStatusApi.getRemoteUserStatusTypes();
+    }
+    // ==========================================
+    // AUTHENTICATED OPERATIONS
+    // ==========================================
+    /**
+     * AUTH: Get earned user status for authenticated user
+     */
+    async getRemoteEarnedUserStatus() {
+        return this.userStatusApi.getRemoteEarnedUserStatus();
+    }
+    // ==========================================
+    // ADMIN OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Create user status type
+     */
+    async createUserStatusType(userStatusType) {
+        return this.userStatusApi.createUserStatusType(userStatusType);
+    }
+}
+
+/**
+ * @explorins/pers-sdk-user-status
+ *
+ * Platform-agnostic User Status Domain SDK for PERS ecosystem
+ * Handles user status management and type operations
+ */
+// API Layer
+/**
+ * Create a complete User Status SDK instance
+ *
+ * @param apiClient - Configured PERS API client
+ * @returns User Status SDK with flattened structure for better DX
+ */
+function createUserStatusSDK(apiClient) {
+    const userStatusApi = new UserStatusApi(apiClient);
+    const userStatusService = new UserStatusService(userStatusApi);
+    return {
+        // Direct access to service methods (primary interface)
+        // ✅ FRAMEWORK ALIGNED: Only methods actually used by framework
+        // Public methods
+        getRemoteUserStatusTypes: () => userStatusService.getRemoteUserStatusTypes(),
+        // Auth methods
+        getRemoteEarnedUserStatus: () => userStatusService.getRemoteEarnedUserStatus(),
+        // Admin methods
+        createUserStatusType: (userStatusType) => userStatusService.createUserStatusType(userStatusType),
+        // Advanced access for edge cases
+        api: userStatusApi,
+        service: userStatusService
+    };
+}
+
+/**
+ * Platform-Agnostic Web3 Chain API Client
+ *
+ * Handles blockchain chain operations using the PERS backend.
+ * Uses @explorins/web3-ts types for perfect framework compatibility.
+ */
+class Web3ChainApi {
+    constructor(apiClient) {
+        this.apiClient = apiClient;
+        this.basePath = '/chains';
+    }
+    // ==========================================
+    // PUBLIC OPERATIONS
+    // ==========================================
+    /**
+     * PUBLIC: Get chain data by chain ID
+     * ✅ Returns ChainData exactly as framework expects from @explorins/web3-ts
+     */
+    async getChainData(chainId) {
+        try {
+            console.log('🔍 [Web3ChainApi] Fetching chain data for chainId:', chainId);
+            const response = await this.apiClient.get(`${this.basePath}/${chainId}`);
+            if (!response) {
+                throw new Error(`No chain data received for chainId: ${chainId}`);
+            }
+            return response;
+        }
+        catch (error) {
+            console.error('❌ [Web3ChainApi] Failed to get chain data:', {
+                chainId,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            throw error;
+        }
+    }
+}
+
+const isTokenExpired = (token, margin = 60) => {
+    // ✅ SANITIZE: Remove any words (Bearer etc) if exists and get the token
+    const cleanToken = token.split(' ')[1] || token;
+    // ✅ VALIDATION: Check if token is jwt
+    if (!cleanToken || cleanToken.split('.').length !== 3) {
+        return true; // Consider invalid tokens as expired
+    }
+    try {
+        // ✅ TYPE-SAFE: Decode with proper typing
+        const decoded = jwtDecode(cleanToken);
+        const currentTime = Math.floor(Date.now() / 1000);
+        // ✅ CONFIGURABLE: Use provided margin (default 60 seconds)
+        return decoded.exp < (currentTime + margin);
+    }
+    catch (error) {
+        console.error('[SDK JWT Utils] Error decoding JWT token:', error);
+        return true; // Consider unparseable tokens as expired
+    }
+};
+
+class Web3ChainService {
+    constructor(web3ChainApi, providerService) {
+        this.web3ChainApi = web3ChainApi;
+        this.providerService = providerService;
+        this.web3InstanceCache = new Map();
+    }
+    async getWeb3ByChainId(chainId) {
+        const cached = this.web3InstanceCache.get(chainId);
+        // ✅ SMART CACHE: Check if cache is valid based on token expiration
+        if (cached && !this.checkIsTokenExpired(cached.chainData.authHeader)) {
+            console.log(`♻️ [Web3ChainService] Using cached Web3 instance for chain ${chainId}`);
+            return cached.web3Instance;
+        }
+        // ✅ CREATE WITH ERROR RECOVERY: Handle auth errors gracefully
+        try {
+            console.log(`🔧 [Web3ChainService] Creating new Web3 instance for chain ${chainId}`);
+            const { web3, chainData } = await this.createWeb3Instance(chainId);
+            // ✅ CACHE NEW INSTANCE
+            this.web3InstanceCache.set(chainId, {
+                web3Instance: web3,
+                chainData: chainData,
+                createdAt: Date.now(),
+                chainId
+            });
+            return web3;
+        }
+        catch (error) {
+            // ✅ AUTH ERROR RECOVERY: Clear cache and retry once
+            if (this.isAuthError(error)) {
+                console.warn(`🔄 [Web3ChainService] Auth error detected, clearing cache and retrying...`);
+                this.web3InstanceCache.delete(chainId);
+                // Retry once with fresh instance
+                const { web3, chainData } = await this.createWeb3Instance(chainId);
+                this.web3InstanceCache.set(chainId, {
+                    web3Instance: web3,
+                    chainData: chainData,
+                    createdAt: Date.now(),
+                    chainId
+                });
+                return web3;
+            }
+            throw error;
+        }
+    }
+    async getChainDataWithCache(chainId) {
+        const cached = this.web3InstanceCache.get(chainId);
+        //const now = Date.now();
+        if (cached && !this.checkIsTokenExpired(cached.chainData.authHeader)) {
+            console.log(`♻️ [Web3ChainService] Using cached ChainData for chain ${chainId}`);
+            return cached.chainData;
+        }
+        // If not cached, fetch fresh data
+        const chainData = await this.getChainDataById(chainId);
+        if (!chainData) {
+            throw new Error(`Chain data not found for chainId: ${chainId}`);
+        }
+        return chainData;
+    }
+    checkIsTokenExpired(authHeader) {
+        // ✅ NULL CHECK: Handle undefined case
+        if (!authHeader) {
+            return false; // No token means no expiration (public chains)
+        }
+        // ✅ FUNCTION CALL: Use imported function, not method
+        return isTokenExpired(authHeader);
+    }
+    async createWeb3Instance(chainId) {
+        const chainData = await this.getChainDataById(chainId);
+        if (!chainData) {
+            throw new Error(`Chain data not found for chainId: ${chainId}`);
+        }
+        // ✅ CRITICAL CHECK: Ensure authHeader is present for private chains
+        if (chainData.chainType === 'PRIVATE' && !chainData.authHeader) {
+            console.error('❌ [Web3ChainService] CRITICAL: Private chain missing authHeader!');
+            throw new Error(`Private chain ${chainId} missing authentication header`);
+        }
+        const web3 = await this.providerService.getWeb3(chainId, chainData.chainType || 'PUBLIC', chainData);
+        return { web3, chainData };
+    }
+    // ✅ HELPER: Type-safe error checking
+    isAuthError(error) {
+        const message = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+        return (message.includes('unauthorized') ||
+            message.includes('401') ||
+            message.includes('token expired') ||
+            message.includes('invalid token'));
+    }
+    async getChainDataById(chainId) {
+        try {
+            return await this.web3ChainApi.getChainData(chainId);
+        }
+        catch (error) {
+            console.error('❌ [SDK Web3ChainService] Error getting chain data for chainId:', chainId, error);
+            return null;
+        }
+    }
+}
+
+//IMPORTANT//
+//This function is temporary so we install ethers just to make it work, once we delete this function we must uninstall Ethers
+const getWeb3ProviderFromChainData = (chainData, timeout = 15000, customUserAgentName = '', tokenRefresher) => {
+    // Fixed ethers provider setup for authenticated requests
+    let ethersProvider;
+    if (chainData.authHeader) {
+        // For authenticated requests, create a custom FetchRequest
+        const fetchRequest = new FetchRequest(chainData.rpcUrl);
+        fetchRequest.timeout = timeout;
+        fetchRequest.setHeader('Authorization', chainData.authHeader);
+        fetchRequest.setHeader('Content-Type', 'application/json');
+        if (customUserAgentName) {
+            fetchRequest.setHeader('User-Agent', customUserAgentName);
+        }
+        // Create provider with the configured FetchRequest
+        ethersProvider = new JsonRpcProvider(fetchRequest, undefined, {
+            staticNetwork: false,
+            polling: false, // Disable polling for better Lambda performance
+        });
+    }
+    else {
+        // For public chains, use simple URL-based provider
+        ethersProvider = new JsonRpcProvider(chainData.rpcUrl, undefined, {
+            staticNetwork: false,
+            polling: false,
+        });
+    }
+    return {
+        web3Provider: null,
+        ethersProvider: ethersProvider,
+        isAuthenticated: !!chainData.authHeader,
+    };
+};
+
+class Web3ProviderService {
+    constructor(publicHttpProviderService) {
+        this.publicHttpProviderService = publicHttpProviderService;
+        this._web3 = null;
+        this._currentChainId = null;
+    }
+    async getWeb3(chainId, chainType, privateChainData = null) {
+        if (!this._web3 || this._currentChainId !== chainId) {
+            if (!chainId)
+                throw new Error('ChainId not found');
+            try {
+                this._currentChainId = chainId;
+                const provider = await this.getWeb3ByChainId(chainId, chainType, privateChainData);
+                this._web3 = this.convertToWeb3(provider);
+            }
+            catch (error) {
+                console.error('Error getting web3 connection from chain id ' + chainId, error);
+                throw new Error('Error getting web3 connection from chain id ' + chainId);
+            }
+        }
+        return this._web3;
+    }
+    // Keep return type as 'any' to avoid TypeScript errors while still being adapted later
+    getWeb3ByChainId(chainId, chainType, privateChainData = null) {
+        // Rest of the method remains the same
+        if (chainType === ChainTypes$1.PRIVATE && privateChainData) {
+            //const privateProvider = this.privateChainProviderService.getProviderFromChainData(privateChainData)
+            const privateProvider = getWeb3ProviderFromChainData(privateChainData);
+            if (!privateProvider || privateProvider instanceof Error)
+                throw new Error('Error getting web3 provider');
+            return privateProvider;
+        }
+        else {
+            const publicProvider = this.publicHttpProviderService.getProvider(chainId);
+            if (!publicProvider || publicProvider instanceof Error)
+                throw new Error('Error getting web3 provider');
+            return publicProvider;
+        }
+    }
+    convertToWeb3(provider) {
+        if (provider instanceof Web3) {
+            return provider;
+        }
+        if (provider && typeof provider === 'object' && 'web3Provider' in provider) {
+            const providerObj = provider;
+            // If we want to user the web3Provider directly:
+            /*if (providerObj.web3Provider) {
+                return new Web3(providerObj.web3Provider as never);
+            }*/
+            if (providerObj.ethersProvider) {
+                const url = this.extractUrlFromEthersProvider(providerObj.ethersProvider);
+                const headers = this.extractHeadersFromEthersProvider(providerObj.ethersProvider);
+                const web3 = new Web3(url);
+                const currentProvider = web3.currentProvider;
+                if (currentProvider) {
+                    currentProvider['url'] = url;
+                    if (headers && Object.keys(headers).length > 0) {
+                        currentProvider['request'] = async (payload) => {
+                            const response = await fetch(url, {
+                                method: 'POST',
+                                headers: {
+                                    'Content-Type': 'application/json',
+                                    ...headers
+                                },
+                                body: JSON.stringify(payload)
+                            });
+                            if (!response.ok) {
+                                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+                            }
+                            return await response.json();
+                        };
+                    }
+                }
+                return web3;
+            }
+        }
+        return new Web3(provider);
+    }
+    extractUrlFromEthersProvider(ethersProvider) {
+        return ethersProvider.connection?.url ||
+            ethersProvider._getConnection?.()?.url ||
+            ethersProvider.url ||
+            '';
+    }
+    extractHeadersFromEthersProvider(ethersProvider) {
+        return ethersProvider.connection?.headers ||
+            ethersProvider._getConnection?.()?.headers ||
+            {};
+    }
+}
+
+/**
+ * Web3 Chain Domain Models
+ *
+ * Minimal interface definitions matching framework usage exactly.
+ * Local ChainData interface to avoid external dependency issues.
+ */
+const ChainTypes = {
+    PUBLIC: 'PUBLIC',
+    PRIVATE: 'PRIVATE'
+};
+
+function createWeb3ChainSDK(apiClient, providerService) {
+    const web3ChainApi = new Web3ChainApi(apiClient);
+    const web3ChainService = new Web3ChainService(web3ChainApi, providerService); // ✅ DIRECT INJECTION
+    return {
+        // ✅ REPLICA: Same methods as framework
+        getChainDataById: (chainId) => web3ChainService.getChainDataById(chainId),
+        getWeb3ByChainId: (chainId) => web3ChainService.getWeb3ByChainId(chainId),
+        api: web3ChainApi,
+        service: web3ChainService
+    };
+}
+
+class Web3Api {
+    constructor(web3ChainService) {
+        this.web3ChainService = web3ChainService;
+    }
+    async getTokenBalance(request) {
+        const web3 = await this.web3ChainService.getWeb3ByChainId(request.chainId);
+        const tokenContract = getSmartContractInstance(request.contractAddress, request.abi, web3);
+        const balance = await getAddressTokenBalanceByContract(tokenContract, request.accountAddress, request.tokenId);
+        return Number(balance);
+    }
+    async getTokenUri(request) {
+        const web3 = await this.web3ChainService.getWeb3ByChainId(request.chainId);
+        // ✅ DIRECT: Use web3-ts functions directly
+        const tokenContract = getSmartContractInstance(request.contractAddress, request.abi, web3);
+        const tokenId = Number(request.tokenId);
+        const tokenUri = await getTokenUri(tokenContract, tokenId);
+        return String(tokenUri);
+    }
+    async getTokenOfOwnerByIndex(request) {
+        const web3 = await this.web3ChainService.getWeb3ByChainId(request.chainId);
+        // ✅ DIRECT: Use web3-ts functions directly
+        const tokenContract = getSmartContractInstance(request.contractAddress, request.abi, web3);
+        const tokenId = await getTokenOfOwnerByIndex(tokenContract, request.accountAddress, request.tokenIndex);
+        return String(tokenId);
+    }
+}
+
+class SimpleCache {
+    constructor() {
+        this.storage = {};
+        this.defaultTTL = 10 * 1000; // 10 seconds
+    }
+    set(key, data, ttl) {
+        this.storage[key] = {
+            data,
+            timestamp: Date.now(),
+            ttl: ttl ?? this.defaultTTL
+        };
+    }
+    get(key) {
+        const entry = this.storage[key];
+        if (!entry) {
+            return null;
+        }
+        const now = Date.now();
+        const isExpired = (now - entry.timestamp) > entry.ttl;
+        if (isExpired) {
+            delete this.storage[key];
+            return null;
+        }
+        return entry.data;
+    }
+    clear() {
+        this.storage = {};
+    }
+    cleanup() {
+        const now = Date.now();
+        Object.keys(this.storage).forEach(key => {
+            const entry = this.storage[key];
+            if ((now - entry.timestamp) > entry.ttl) {
+                delete this.storage[key];
+            }
+        });
+    }
+}
+
+class Web3Service {
+    constructor(web3Api, web3ChainService) {
+        this.web3Api = web3Api;
+        this.web3ChainService = web3ChainService;
+        //temporary fix, remove when the backend supports custom gateways
+        this.defaultIpfsGatewayDomain = 'pers.mypinata.cloud';
+        // ✅ CACHE: Simple 10-second cache instance
+        this.cache = new SimpleCache();
+        this.cleanupInterval = null;
+        this.cleanupInterval = setInterval(() => {
+            this.cache.cleanup();
+        }, 30 * 1000);
+    }
+    destroy() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        this.cache.clear();
+    }
+    async getERC20Balance(request) {
+        const cacheKey = `erc20_balance_${request.accountAddress}_${request.token.contractAddress}_${request.token.chainId}`;
+        // ✅ CACHE CHECK: Try to get from cache first
+        const cached = this.cache.get(cacheKey);
+        if (cached) {
+            console.debug(`💾 [Web3Service] Using cached ERC20 balance for ${request.token.symbol}`);
+            return cached;
+        }
+        console.debug(`🔄 [Web3Service] Fetching fresh ERC20 balance for ${request.token.symbol}`);
+        const rawBalance = await this.web3Api.getTokenBalance({
+            accountAddress: request.accountAddress,
+            contractAddress: request.token.contractAddress,
+            abi: request.token.abi,
+            tokenId: null, // Always null for ERC20
+            chainId: request.token.chainId
+        });
+        const decimals = request.token.decimals ?? 18;
+        const symbol = request.token.symbol ?? 'UNKNOWN';
+        const response = {
+            rawBalance,
+            formattedBalance: this.formatBalance(rawBalance, decimals),
+            decimals,
+            symbol,
+            hasBalance: rawBalance > 0
+        };
+        // ✅ CACHE SET: Store result in cache
+        this.cache.set(cacheKey, response);
+        return response;
+    }
+    async getERC1155Collection(request) {
+        // ✅ CACHE KEY: Create unique cache key for collection request
+        const contractAddresses = request.tokens.map(t => t.contractAddress).sort().join(',');
+        const cacheKey = `erc1155_collection_${request.accountAddress}_${contractAddresses}`;
+        // ✅ CACHE CHECK: Try to get from cache first
+        const cached = this.cache.get(cacheKey);
+        if (cached) {
+            console.debug(`💾 [Web3Service] Using cached ERC1155 collection for ${request.accountAddress}`);
+            return cached;
+        }
+        console.debug(`🔄 [Web3Service] Fetching fresh ERC1155 collection for ${request.accountAddress}`);
+        const tokenResults = await Promise.all(request.tokens.map(async (token) => {
+            // ✅ FIXED: Handle null metadata properly
+            const tokenIds = token.metadata?.map(m => m.tokenMetadataIncrementalId?.toString()).filter((id) => id !== undefined) ?? [];
+            // Check balance for each known tokenId
+            const balanceResults = await Promise.allSettled(tokenIds.map(async (tokenId) => {
+                try {
+                    const rawBalance = await this.web3Api.getTokenBalance({
+                        accountAddress: request.accountAddress,
+                        contractAddress: token.contractAddress,
+                        abi: token.abi,
+                        tokenId,
+                        chainId: token.chainId
+                    });
+                    const decimals = token.decimals ?? 0; // ERC1155 usually no decimals
+                    return {
+                        tokenId,
+                        balance: rawBalance,
+                        formattedBalance: this.formatBalance(rawBalance, decimals),
+                        hasBalance: rawBalance > 0,
+                        // ✅ FIXED: Convert null to undefined for findMetadata
+                        metadata: this.findMetadata(token.metadata ?? undefined, tokenId)
+                    };
+                }
+                catch (error) {
+                    console.warn(`Failed to get balance for token ${token.contractAddress}:${tokenId}`, error);
+                    return null; // Skip failed tokens
+                }
+            }));
+            // Filter successful results with balance > 0
+            const successfulResults = [];
+            for (const result of balanceResults) {
+                if (result.status === 'fulfilled' && result.value !== null && result.value.hasBalance) {
+                    successfulResults.push(result.value);
+                }
+            }
+            return {
+                token,
+                results: successfulResults
+            };
+        }));
+        const response = {
+            accountAddress: request.accountAddress,
+            tokens: tokenResults.filter(t => t.results.length > 0)
+        };
+        // ✅ CACHE SET: Store complete collection result
+        this.cache.set(cacheKey, response);
+        return response;
+    }
+    async getERC721Collection(request) {
+        // ✅ CACHE KEY: Create unique cache key for NFT collection
+        const contractAddresses = request.nftContracts.map(t => t.contractAddress).sort().join(',');
+        const maxNFTs = request.maxNFTsPerContract || 50;
+        const cacheKey = `erc721_collection_${request.accountAddress}_${contractAddresses}_${maxNFTs}`;
+        // ✅ CACHE CHECK: Try to get from cache first
+        const cached = this.cache.get(cacheKey);
+        if (cached) {
+            console.debug(`💾 [Web3Service] Using cached ERC721 collection for ${request.accountAddress}`);
+            return cached;
+        }
+        console.debug(`🔄 [Web3Service] Fetching fresh ERC721 collection for ${request.accountAddress}`);
+        const startTime = Date.now();
+        const contractResults = await Promise.all(request.nftContracts.map(async (token) => {
+            try {
+                const totalBalance = await this.web3Api.getTokenBalance({
+                    accountAddress: request.accountAddress,
+                    contractAddress: token.contractAddress,
+                    abi: token.abi,
+                    tokenId: null,
+                    chainId: token.chainId
+                });
+                if (totalBalance === 0) {
+                    return {
+                        token,
+                        totalNFTs: 0,
+                        nfts: [],
+                        hasMore: false
+                    };
+                }
+                const nftsToLoad = Math.min(totalBalance, maxNFTs);
+                const nftResults = await Promise.allSettled(Array.from({ length: nftsToLoad }, async (_, index) => {
+                    try {
+                        const tokenId = await this.web3Api.getTokenOfOwnerByIndex({
+                            contractAddress: token.contractAddress,
+                            abi: token.abi,
+                            accountAddress: request.accountAddress,
+                            tokenIndex: index,
+                            chainId: token.chainId
+                        });
+                        const tokenUri = await this.web3Api.getTokenUri({
+                            contractAddress: token.contractAddress,
+                            abi: token.abi,
+                            tokenId,
+                            chainId: token.chainId
+                        });
+                        const metadata = await this.fetchMetadata(tokenUri, token.chainId);
+                        const nftItem = {
+                            tokenId,
+                            name: metadata?.name || `Token #${tokenId}`,
+                            description: metadata?.description || '',
+                            imageUrl: await this.resolveIPFSUrl(metadata?.image || '', token.chainId),
+                            rawBalance: 1,
+                            formattedBalance: '1',
+                            hasBalance: true,
+                            metadata,
+                            tokenIndex: index
+                        };
+                        return nftItem;
+                    }
+                    catch (error) {
+                        console.warn(`Failed to load NFT at index ${index} for ${token.symbol}:`, error);
+                        return null;
+                    }
+                }));
+                // ✅ FIXED: Usar tipo específico NFTItem
+                const successfulNFTs = nftResults
+                    .filter((result) => result.status === 'fulfilled' && result.value !== null)
+                    .map(result => result.value);
+                return {
+                    token,
+                    totalNFTs: totalBalance,
+                    nfts: successfulNFTs,
+                    hasMore: totalBalance > maxNFTs
+                };
+            }
+            catch (error) {
+                console.error(`Failed to load NFT collection for ${token.symbol}:`, error);
+                return {
+                    token,
+                    totalNFTs: 0,
+                    nfts: [],
+                    hasMore: false
+                };
+            }
+        }));
+        const totalNFTs = contractResults.reduce((sum, contract) => sum + contract.nfts.length, 0);
+        const loadingTime = Date.now() - startTime;
+        const response = {
+            accountAddress: request.accountAddress,
+            contracts: contractResults,
+            summary: {
+                totalContracts: request.nftContracts.length,
+                totalNFTs,
+                loadingTime
+            }
+        };
+        // ✅ CACHE SET: Store complete collection response
+        this.cache.set(cacheKey, response);
+        return response;
+    }
+    // ==========================================
+    // HELPER METHODS
+    // ==========================================
+    formatBalance(rawBalance, decimals) {
+        const balance = rawBalance / Math.pow(10, decimals);
+        return balance.toLocaleString('en-US', {
+            minimumFractionDigits: 0,
+            maximumFractionDigits: decimals > 0 ? 2 : 0
+        });
+    }
+    // ✅ FIXED: Update method signature to handle null properly
+    findMetadata(metadata, tokenId) {
+        if (!metadata || tokenId === null)
+            return null;
+        return metadata.find(m => m.tokenMetadataIncrementalId?.toString() === tokenId) || null;
+    }
+    async fetchMetadata(uri, chainId) {
+        try {
+            const httpUrl = await this.resolveIPFSUrl(uri, chainId);
+            const response = await fetch(httpUrl);
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+            return await response.json();
+        }
+        catch (error) {
+            console.warn('Failed to fetch NFT metadata:', error);
+            return null;
+        }
+    }
+    async getIpfsGatewayDomain(chainId) {
+        try {
+            const chainData = await this.web3ChainService.getChainDataWithCache(chainId);
+            return chainData.ipfsGatewayDomain || this.defaultIpfsGatewayDomain;
+        }
+        catch (error) {
+            console.warn(`Failed to get chain data for chainId ${chainId}, using default IPFS gateway:`, error);
+            return this.defaultIpfsGatewayDomain;
+        }
+    }
+    async resolveIPFSUrl(url, chainId) {
+        if (!url)
+            return '';
+        if (url.startsWith('ipfs://')) {
+            const gatewayDomain = await this.getIpfsGatewayDomain(chainId);
+            return `https://${gatewayDomain}/ipfs/${url.slice(7)}`;
+        }
+        return url;
+    }
+}
+
+function createWeb3SDK(apiClient, web3ProviderService) {
+    const web3ChainSDK = createWeb3ChainSDK(apiClient, web3ProviderService);
+    const web3Api = new Web3Api(web3ChainSDK.service);
+    const web3Service = new Web3Service(web3Api, web3ChainSDK.service);
+    return {
+        getCreditsBalance: (request) => web3Service.getERC20Balance(request),
+        getRewardsCollection: (request) => web3Service.getERC1155Collection(request),
+        getStampsCollection: (request) => web3Service.getERC721Collection(request),
+        api: web3Api,
+        service: web3Service
+    };
+}
+
+export { AnalyticsApi, AnalyticsService, AuthAdminApi, AuthAdminService, BaseTokenService, BusinessApi, BusinessService, CampaignApi, CampaignService, ChainTypes, DEFAULT_PERS_CONFIG, DonationApi, DonationService, PurchaseApi as PaymentApi, PaymentService, PersApiClient, PersApiError, PersSDK, RedemptionApi, RedemptionService, SimpleCache, TenantApi, TenantService, TokenApi, TokenSDK, TokenService, TransactionAccountType, TransactionApi, TransactionService, UserApi, UserService, UserStatusApi, UserStatusService, Web3ChainApi, Web3ChainService, Web3ProviderService, buildApiRoot, createAnalyticsSDK, createAuthAdminSDK, createAuthProvider, createBusinessSDK, createCampaignSDK, createDonationSDK, createPaymentSDK, createPersSDK, createRedemptionSDK, createTenantSDK, createTransactionSDK, createUserSDK, createUserStatusSDK, createWeb3ChainSDK, createWeb3SDK, mergeWithDefaults };
+//# sourceMappingURL=index.js.map