@explorins/pers-sdk 1.1.2 → 1.2.0

package/dist/index.cjs

@@ -0,0 +1,4217 @@
+'use strict';
+
+var jwtDecode = require('jwt-decode');
+var Web3 = require('web3');
+var web3Ts = require('@explorins/web3-ts');
+var ethers = require('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)
+exports.TransactionAccountType = void 0;
+(function (TransactionAccountType) {
+    // Add specific transaction account types as needed
+    // This should match the enum used in the infrastructure layer
+})(exports.TransactionAccountType || (exports.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.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 ethers.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 ethers.JsonRpcProvider(fetchRequest, undefined, {
+            staticNetwork: false,
+            polling: false, // Disable polling for better Lambda performance
+        });
+    }
+    else {
+        // For public chains, use simple URL-based provider
+        ethersProvider = new ethers.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 === web3Ts.ChainTypes.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 = web3Ts.getSmartContractInstance(request.contractAddress, request.abi, web3);
+        const balance = await web3Ts.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 = web3Ts.getSmartContractInstance(request.contractAddress, request.abi, web3);
+        const tokenId = Number(request.tokenId);
+        const tokenUri = await web3Ts.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 = web3Ts.getSmartContractInstance(request.contractAddress, request.abi, web3);
+        const tokenId = await web3Ts.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
+    };
+}
+
+exports.AnalyticsApi = AnalyticsApi;
+exports.AnalyticsService = AnalyticsService;
+exports.AuthAdminApi = AuthAdminApi;
+exports.AuthAdminService = AuthAdminService;
+exports.BaseTokenService = BaseTokenService;
+exports.BusinessApi = BusinessApi;
+exports.BusinessService = BusinessService;
+exports.CampaignApi = CampaignApi;
+exports.CampaignService = CampaignService;
+exports.ChainTypes = ChainTypes;
+exports.DEFAULT_PERS_CONFIG = DEFAULT_PERS_CONFIG;
+exports.DonationApi = DonationApi;
+exports.DonationService = DonationService;
+exports.PaymentApi = PurchaseApi;
+exports.PaymentService = PaymentService;
+exports.PersApiClient = PersApiClient;
+exports.PersApiError = PersApiError;
+exports.PersSDK = PersSDK;
+exports.RedemptionApi = RedemptionApi;
+exports.RedemptionService = RedemptionService;
+exports.SimpleCache = SimpleCache;
+exports.TenantApi = TenantApi;
+exports.TenantService = TenantService;
+exports.TokenApi = TokenApi;
+exports.TokenSDK = TokenSDK;
+exports.TokenService = TokenService;
+exports.TransactionApi = TransactionApi;
+exports.TransactionService = TransactionService;
+exports.UserApi = UserApi;
+exports.UserService = UserService;
+exports.UserStatusApi = UserStatusApi;
+exports.UserStatusService = UserStatusService;
+exports.Web3ChainApi = Web3ChainApi;
+exports.Web3ChainService = Web3ChainService;
+exports.Web3ProviderService = Web3ProviderService;
+exports.buildApiRoot = buildApiRoot;
+exports.createAnalyticsSDK = createAnalyticsSDK;
+exports.createAuthAdminSDK = createAuthAdminSDK;
+exports.createAuthProvider = createAuthProvider;
+exports.createBusinessSDK = createBusinessSDK;
+exports.createCampaignSDK = createCampaignSDK;
+exports.createDonationSDK = createDonationSDK;
+exports.createPaymentSDK = createPaymentSDK;
+exports.createPersSDK = createPersSDK;
+exports.createRedemptionSDK = createRedemptionSDK;
+exports.createTenantSDK = createTenantSDK;
+exports.createTransactionSDK = createTransactionSDK;
+exports.createUserSDK = createUserSDK;
+exports.createUserStatusSDK = createUserStatusSDK;
+exports.createWeb3ChainSDK = createWeb3ChainSDK;
+exports.createWeb3SDK = createWeb3SDK;
+exports.mergeWithDefaults = mergeWithDefaults;
+//# sourceMappingURL=index.cjs.map