@explorins/pers-sdk 1.2.6 → 1.3.1

package/dist/chunks/pers-sdk-_1sTi9x9.cjs

@@ -0,0 +1,1384 @@
+'use strict';
+
+var persShared = require('@explorins/pers-shared');
+
+/**
+ * PERS SDK Configuration interfaces and utilities
+ *
+ * Provides type-safe configuration options for the PERS SDK
+ * with sensible defaults for production environments.
+ */
+/**
+ * Default configuration values
+ */
+const DEFAULT_PERS_CONFIG = {
+    environment: 'production',
+    apiVersion: 'v2',
+    timeout: 30000,
+    retries: 3,
+    tokenRefreshMargin: 60, // Refresh tokens 60 seconds before expiry
+    backgroundRefreshThreshold: 30 // Use background refresh if >30s remaining
+};
+/**
+ * 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
+    };
+}
+
+/**
+ * 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 AuthApi {
+    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) {
+        const body = {
+            authToken: jwt,
+            authType: persShared.AccountOwnerType.TENANT
+        };
+        return this.apiClient.post(`${this.basePath}/token`, body, { bypassAuth: true });
+    }
+    /**
+     * Login user with JWT - bypasses auth headers
+     */
+    async loginUser(jwt) {
+        const body = {
+            authToken: jwt,
+            authType: persShared.AccountOwnerType.USER
+        };
+        return this.apiClient.post(`${this.basePath}/token`, body, { bypassAuth: true });
+    }
+    /**
+     * Refresh access token - bypasses auth headers to prevent circular dependency
+     */
+    async refreshAccessToken(refreshToken) {
+        // Bypass auth headers for refresh calls to prevent circular dependency
+        return this.apiClient.post(`${this.basePath}/refresh`, { refreshToken }, { bypassAuth: true });
+    }
+}
+
+/**
+ * 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 AuthService {
+    constructor(authApi, authProvider) {
+        this.authApi = authApi;
+        this.authProvider = authProvider;
+    }
+    // ==========================================
+    // ADMIN AUTHENTICATION OPERATIONS
+    // ==========================================
+    /**
+     * ADMIN: Login tenant admin with JWT
+     * Automatically stores tokens if auth provider supports token storage
+     */
+    async loginTenantAdmin(jwt) {
+        const response = await this.authApi.loginTenantAdmin(jwt);
+        // Store tokens if auth provider supports it
+        if (this.authProvider && response.accessToken) {
+            await this.storeTokens(response.accessToken, response.refreshToken, 'admin', jwt);
+        }
+        return response;
+    }
+    /**
+     * ADMIN: Login user with JWT
+     * Automatically stores tokens if auth provider supports token storage
+     */
+    async loginUser(jwt) {
+        const response = await this.authApi.loginUser(jwt);
+        // Store tokens if auth provider supports it
+        if (this.authProvider && response.accessToken) {
+            await this.storeTokens(response.accessToken, response.refreshToken, 'user', jwt);
+        }
+        return response;
+    }
+    /**
+     * ADMIN: Refresh access token
+     * Automatically stores new tokens if auth provider supports token storage
+     */
+    async refreshAccessToken(refreshToken) {
+        // Use provided refresh token or get from auth provider
+        const tokenToUse = refreshToken || (this.authProvider?.getRefreshToken ? await this.authProvider.getRefreshToken() : null);
+        if (!tokenToUse) {
+            throw new Error('No refresh token available for token refresh');
+        }
+        const response = await this.authApi.refreshAccessToken(tokenToUse);
+        // Store new tokens if auth provider supports it
+        if (this.authProvider && response.accessToken) {
+            await this.storeTokens(response.accessToken, response.refreshToken);
+        }
+        return response;
+    }
+    /**
+     * Automatic token refresh using stored refresh token
+     * Convenience method for 401 error handling
+     */
+    async autoRefreshToken() {
+        return this.refreshAccessToken(); // Uses stored refresh token
+    }
+    /**
+     * Clear stored tokens if auth provider supports it
+     */
+    async clearTokens() {
+        if (this.authProvider?.clearTokens) {
+            await this.authProvider.clearTokens();
+        }
+    }
+    /**
+     * Check if we have valid tokens for authentication
+     */
+    hasValidAuth() {
+        return this.authProvider?.hasValidToken?.() ?? false;
+    }
+    // ==========================================
+    // PRIVATE HELPERS
+    // ==========================================
+    /**
+     * Store tokens using auth provider if it supports token storage
+     */
+    async storeTokens(accessToken, refreshToken, authType, providerToken) {
+        if (!this.authProvider)
+            return;
+        try {
+            // Store access token
+            if (this.authProvider.setAccessToken) {
+                await this.authProvider.setAccessToken(accessToken);
+            }
+            // Store refresh token if provided and supported
+            if (refreshToken && this.authProvider.setRefreshToken) {
+                await this.authProvider.setRefreshToken(refreshToken);
+            }
+            // Store provider token if provided and provider supports it
+            if (providerToken && 'setProviderToken' in this.authProvider &&
+                typeof this.authProvider.setProviderToken === 'function') {
+                await this.authProvider.setProviderToken(providerToken);
+            }
+            // Store auth type if provided and provider supports it
+            if (authType && 'setAuthType' in this.authProvider &&
+                typeof this.authProvider.setAuthType === 'function') {
+                await this.authProvider.setAuthType(authType);
+            }
+        }
+        catch (error) {
+            // Don't throw - token storage failure shouldn't break authentication
+        }
+    }
+}
+
+/**
+ * Authentication-related constants for type safety
+ */
+/**
+ * Storage keys for authentication tokens
+ */
+const AUTH_STORAGE_KEYS = {
+    ACCESS_TOKEN: 'pers_access_token',
+    REFRESH_TOKEN: 'pers_refresh_token',
+    PROVIDER_TOKEN: 'pers_provider_token', // Generic external JWT (Firebase, Auth0, etc.)
+    AUTH_TYPE: 'pers_auth_type',
+};
+/**
+ * Authentication method types
+ */
+const AUTH_METHODS = {
+    GET: 'GET',
+    POST: 'POST',
+    PUT: 'PUT',
+    DELETE: 'DELETE',
+};
+
+/**
+ * Token Storage Management
+ *
+ * Handles secure token storage with different strategies
+ */
+/**
+ * LocalStorage-based token storage
+ */
+class LocalStorageTokenStorage {
+    async setToken(key, value) {
+        if (typeof localStorage !== 'undefined') {
+            localStorage.setItem(key, value);
+        }
+    }
+    async getToken(key) {
+        if (typeof localStorage !== 'undefined') {
+            return localStorage.getItem(key);
+        }
+        return null;
+    }
+    async removeToken(key) {
+        if (typeof localStorage !== 'undefined') {
+            localStorage.removeItem(key);
+        }
+    }
+    async clear() {
+        if (typeof localStorage !== 'undefined') {
+            Object.values(AUTH_STORAGE_KEYS).forEach(key => {
+                localStorage.removeItem(key);
+            });
+        }
+    }
+}
+/**
+ * Token Manager - High-level token management
+ */
+class TokenManager {
+    constructor(storage = new LocalStorageTokenStorage()) {
+        this.storage = storage;
+    }
+    async setAccessToken(token) {
+        await this.storage.setToken(AUTH_STORAGE_KEYS.ACCESS_TOKEN, token);
+    }
+    async getAccessToken() {
+        return this.storage.getToken(AUTH_STORAGE_KEYS.ACCESS_TOKEN);
+    }
+    async setRefreshToken(token) {
+        await this.storage.setToken(AUTH_STORAGE_KEYS.REFRESH_TOKEN, token);
+    }
+    async getRefreshToken() {
+        return this.storage.getToken(AUTH_STORAGE_KEYS.REFRESH_TOKEN);
+    }
+    async getProviderToken() {
+        return await this.storage.getToken(AUTH_STORAGE_KEYS.PROVIDER_TOKEN);
+    }
+    async setTokenData(data) {
+        if (data.accessToken) {
+            await this.setAccessToken(data.accessToken);
+        }
+        if (data.refreshToken) {
+            await this.setRefreshToken(data.refreshToken);
+        }
+        // Could store expiration time if needed
+    }
+    async getTokenData() {
+        const accessToken = await this.getAccessToken();
+        const refreshToken = await this.getRefreshToken();
+        return {
+            accessToken: accessToken || undefined,
+            refreshToken: refreshToken || undefined
+        };
+    }
+    async clearAllTokens() {
+        await this.storage.clear();
+    }
+    async hasValidTokens() {
+        const accessToken = await this.getAccessToken();
+        return !!accessToken;
+    }
+    async hasRefreshToken() {
+        const refreshToken = await this.getRefreshToken();
+        return !!refreshToken;
+    }
+    async removeToken(key) {
+        await this.storage.removeToken(key);
+    }
+    /**
+     * Set auth type (user or admin)
+     */
+    async setAuthType(authType) {
+        await this.storage.setToken(AUTH_STORAGE_KEYS.AUTH_TYPE, authType);
+    }
+    /**
+     * Get stored auth type
+     */
+    async getAuthType() {
+        const authType = await this.storage.getToken(AUTH_STORAGE_KEYS.AUTH_TYPE);
+        return authType;
+    }
+    /**
+     * Clear auth type from storage
+     */
+    async clearAuthType() {
+        await this.storage.removeToken(AUTH_STORAGE_KEYS.AUTH_TYPE);
+    }
+    /**
+     * Set provider token (generic external JWT)
+     */
+    async setProviderToken(token) {
+        await this.storage.setToken(AUTH_STORAGE_KEYS.PROVIDER_TOKEN, token);
+    }
+    /**
+     * Clear provider token
+     */
+    async clearProviderToken() {
+        await this.storage.removeToken(AUTH_STORAGE_KEYS.PROVIDER_TOKEN);
+    }
+}
+
+/**
+ * PERS SDK Error Handling - Optimized for Performance
+ *
+ * Consolidated API and auth errors for fast SDK performance
+ * Uses @explorins/pers-shared when available, fallback to SDK errors
+ */
+// Fast type guards and utilities
+class ErrorUtils {
+    /**
+     * Fast token expiration detection
+     */
+    static isTokenExpired(error) {
+        if (typeof error !== 'object' || error === null)
+            return false;
+        const err = error;
+        const apiError = err?.error || err?.response?.data || err;
+        const status = err?.status || err?.response?.status || err?.statusCode;
+        return apiError?.code === 'TOKEN_EXPIRED' ||
+            apiError?.errorCode === 'TOKEN_EXPIRED' ||
+            (status === 401 && apiError?.message?.toLowerCase()?.includes('token'));
+    }
+    /**
+     * Fast error message extraction
+     */
+    static getMessage(error) {
+        if (typeof error !== 'object' || error === null)
+            return 'Unknown error';
+        const err = error;
+        const apiError = err?.error || err?.response?.data || err;
+        return apiError?.message || apiError?.detail || err?.message || 'Request failed';
+    }
+    /**
+     * Fast status code extraction
+     */
+    static getStatus(error) {
+        if (typeof error !== 'object' || error === null)
+            return null;
+        const err = error;
+        return err?.status || err?.statusCode || err?.response?.status || null;
+    }
+    /**
+     * Fast retryability check
+     */
+    static isRetryable(error) {
+        if (typeof error !== 'object' || error === null)
+            return false;
+        const err = error;
+        // Check explicit retryable property first (fastest)
+        if (typeof err?.retryable === 'boolean')
+            return err.retryable;
+        // Fast status-based check
+        const status = ErrorUtils.getStatus(error);
+        return status === null || status >= 500 || status === 429;
+    }
+    /**
+     * Check if error is from PERS API (uses @explorins/pers-shared format)
+     */
+    static isPersApiError(error) {
+        return typeof error === 'object' && error !== null &&
+            'errorCode' in error && 'domain' in error && 'category' in error;
+    }
+}
+// SDK-specific error classes for auth flows
+class TokenRefreshNeeded extends Error {
+    constructor(refreshToken) {
+        super('Token refresh needed');
+        this.refreshToken = refreshToken;
+        this.errorCode = 'TOKEN_REFRESH_NEEDED';
+        this.domain = 'auth';
+        this.category = 'SECURITY';
+        this.retryable = true;
+        this.name = 'TokenRefreshNeeded';
+    }
+}
+class ProviderTokenRefreshNeeded extends Error {
+    constructor(providerToken) {
+        super('Provider token refresh needed');
+        this.providerToken = providerToken;
+        this.errorCode = 'PROVIDER_TOKEN_REFRESH_NEEDED';
+        this.domain = 'auth';
+        this.category = 'SECURITY';
+        this.retryable = true;
+        this.name = 'ProviderTokenRefreshNeeded';
+    }
+}
+class LogoutRequired extends Error {
+    constructor(message) {
+        super(message);
+        this.errorCode = 'LOGOUT_REQUIRED';
+        this.domain = 'auth';
+        this.category = 'SECURITY';
+        this.retryable = false;
+        this.name = 'LogoutRequired';
+    }
+}
+class PersApiError extends Error {
+    constructor(message, endpoint, method, status, retryable = false) {
+        super(`API request failed: ${message}`);
+        this.endpoint = endpoint;
+        this.method = method;
+        this.status = status;
+        this.errorCode = 'PERS_API_ERROR';
+        this.domain = 'api';
+        this.category = 'TECHNICAL';
+        this.name = 'PersApiError';
+        this.retryable = retryable;
+    }
+}
+
+/**
+ * Token Refresh Management
+ *
+ * Handles the 6-step authentication process:
+ * 1. Check for provider token → get complete token set from PERS if missing
+ * 2. Store all tokens (access, refresh, provider)
+ * 3. Use access token for requests
+ * 4. Use refresh token if access expires → get new token set, keep provider
+ * 5. Fall back to provider token if refresh fails → get fresh token set from PERS
+ * 6. Clear all tokens if provider also fails
+ */
+/**
+ * Token Refresh Manager
+ *
+ * Implements the 6-step authentication process:
+ * 1. Use provider token to retrieve complete token set from PERS if not present
+ * 2. Store all 3 tokens (access, refresh, provider)
+ * 3. Use access token for API requests
+ * 4. Use refresh token if access expires → get new token set, preserve provider token
+ * 5. Fall back to provider token if refresh fails → get fresh token set from PERS
+ * 6. Clear all tokens if provider also fails → force logout
+ */
+class TokenRefreshManager {
+    constructor(tokenManager, refreshStrategy) {
+        this.refreshAttempts = new Map();
+        this.MAX_REFRESH_ATTEMPTS = 1;
+        this.loginRequiredListeners = [];
+        this.tokenManager = tokenManager;
+        this.refreshStrategy = refreshStrategy;
+    }
+    /**
+     * Add listener for login required events
+     */
+    onLoginRequired(listener) {
+        this.loginRequiredListeners.push(listener);
+    }
+    /**
+     * Remove listener for login required events
+     */
+    removeLoginRequiredListener(listener) {
+        const index = this.loginRequiredListeners.indexOf(listener);
+        if (index > -1) {
+            this.loginRequiredListeners.splice(index, 1);
+        }
+    }
+    /**
+     * Emit login required event to all listeners
+     */
+    emitLoginRequired(reason) {
+        const event = {
+            reason,
+            timestamp: new Date()
+        };
+        this.loginRequiredListeners.forEach(listener => {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                // Listener error - continuing with other listeners
+            }
+        });
+    }
+    /**
+     * Handle token expiration - orchestrates the 6-step authentication process
+     * 1. Check for provider token → get complete token set from PERS if missing
+     * 2. Store all 3 tokens (access, refresh, provider)
+     * 3. Use access token for requests
+     * 4. Use refresh token if access expires → get new token set, keep provider
+     * 5. Fall back to provider token if refresh fails → get fresh token set from PERS
+     * 6. Clear all tokens if provider also fails
+     */
+    async handleTokenExpiration() {
+        try {
+            const accessToken = await this.tokenManager.getAccessToken();
+            const refreshToken = await this.tokenManager.getRefreshToken();
+            const providerToken = await this.tokenManager.getProviderToken();
+            // If we have no PERS tokens but have a provider token, use it to get the complete set
+            if (!accessToken && !refreshToken && providerToken) {
+                await this.executeProviderTokenFlow(providerToken);
+                return;
+            }
+            // Try refresh token if we have one  
+            if (refreshToken) {
+                await this.executeRefreshTokenFlow(refreshToken);
+                return;
+            }
+            // No refresh token, try provider token
+            if (providerToken) {
+                await this.executeProviderTokenFlow(providerToken);
+                return;
+            }
+            // No tokens available, require login
+            await this.executeAuthCleanup('No authentication tokens available');
+            throw new LogoutRequired('No authentication tokens available');
+        }
+        catch (error) {
+            if (error instanceof TokenRefreshNeeded || error instanceof ProviderTokenRefreshNeeded || error instanceof LogoutRequired) {
+                throw error;
+            }
+            // Convert unexpected errors to login requirement
+            await this.executeAuthCleanup('Authentication process failed unexpectedly');
+            throw new LogoutRequired('Authentication process failed unexpectedly');
+        }
+    }
+    /**
+     * Execute refresh with refresh token (Step 4)
+     * Use refresh token to get new access token, preserve provider token
+     */
+    async executeRefreshTokenFlow(refreshToken) {
+        const attempts = this.refreshAttempts.get(refreshToken) || 0;
+        if (attempts >= this.MAX_REFRESH_ATTEMPTS) {
+            await this.fallbackToProviderToken();
+            return;
+        }
+        try {
+            this.refreshAttempts.set(refreshToken, attempts + 1);
+            const result = await this.refreshStrategy.refreshWithRefreshToken(refreshToken);
+            await this.storeTokenResult(result);
+            this.refreshAttempts.delete(refreshToken);
+        }
+        catch (error) {
+            await this.fallbackToProviderToken();
+        }
+    } /**
+     * Execute refresh with provider token (Step 5)
+     * Uses provider token to get a fresh token set from PERS backend
+     */
+    async executeProviderTokenFlow(providerToken) {
+        try {
+            const result = await this.refreshStrategy.refreshWithProviderToken(providerToken);
+            await this.storeTokenResult(result);
+            this.refreshAttempts.clear();
+        }
+        catch (error) {
+            await this.executeAuthCleanup('Provider token authentication failed - all methods exhausted');
+            throw new LogoutRequired('Provider token authentication failed - all methods exhausted');
+        }
+    }
+    async storeTokenResult(result) {
+        await this.tokenManager.setAccessToken(result.accessToken);
+        if (result.refreshToken) {
+            await this.tokenManager.setRefreshToken(result.refreshToken);
+        }
+    }
+    async fallbackToProviderToken() {
+        const providerToken = await this.tokenManager.getProviderToken();
+        if (providerToken) {
+            try {
+                await this.executeProviderTokenFlow(providerToken);
+            }
+            catch (providerError) {
+                await this.executeAuthCleanup('All authentication methods exhausted');
+                throw new LogoutRequired('All authentication methods exhausted');
+            }
+        }
+        else {
+            await this.executeAuthCleanup('Refresh failed and no provider token available');
+            throw new LogoutRequired('Refresh failed and no provider token available');
+        }
+    }
+    async clearAuthTokens() {
+        await this.tokenManager.removeToken(AUTH_STORAGE_KEYS.ACCESS_TOKEN);
+        await this.tokenManager.removeToken(AUTH_STORAGE_KEYS.REFRESH_TOKEN);
+        // Clear refresh attempts tracking
+        this.refreshAttempts.clear();
+    }
+    /**
+     * Execute authentication cleanup and notify login required (Step 6)
+     */
+    async executeAuthCleanup(reason = 'Authentication failed') {
+        await this.tokenManager.clearAllTokens();
+        this.refreshAttempts.clear();
+        this.emitLoginRequired(reason);
+    }
+    /**
+     * Check if an error should trigger token refresh (React Native compatible)
+     */
+    shouldRefreshToken(error) {
+        return ErrorUtils.isTokenExpired(error);
+    }
+}
+
+/**
+ * DefaultAuthRefreshStrategy - Implements the actual refresh logic
+ */
+class DefaultAuthRefreshStrategy {
+    constructor(tokenManager, getProviderTokenFn, authApi) {
+        this.tokenManager = tokenManager;
+        this.getProviderTokenFn = getProviderTokenFn;
+        this.authApi = authApi;
+    }
+    async refreshWithRefreshToken(refreshToken) {
+        try {
+            const result = await this.authApi.refreshAccessToken(refreshToken);
+            if (!result.accessToken) {
+                throw new Error('Invalid refresh response: missing accessToken');
+            }
+            return {
+                accessToken: result.accessToken,
+                refreshToken: result.refreshToken || refreshToken
+            };
+        }
+        catch (error) {
+            throw new Error(`Refresh token invalid or expired: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    async refreshWithProviderToken(providerToken) {
+        try {
+            const storedAuthType = await this.tokenManager.getAuthType();
+            let result;
+            if (storedAuthType === 'admin') {
+                result = await this.authApi.loginTenantAdmin(providerToken);
+            }
+            else if (storedAuthType === 'user') {
+                result = await this.authApi.loginUser(providerToken);
+            }
+            else {
+                try {
+                    result = await this.authApi.loginUser(providerToken);
+                    await this.tokenManager.setAuthType('user');
+                }
+                catch (userLoginError) {
+                    result = await this.authApi.loginTenantAdmin(providerToken);
+                    await this.tokenManager.setAuthType('admin');
+                }
+            }
+            if (!result.accessToken) {
+                throw new Error('Invalid provider login response: missing accessToken');
+            }
+            return {
+                accessToken: result.accessToken,
+                refreshToken: result.refreshToken
+            };
+        }
+        catch (error) {
+            throw new Error(`Provider token login failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+}
+/**
+ * Default authentication provider with modular architecture
+ *
+ * Delegates token storage to TokenManager and refresh logic to TokenRefreshManager.
+ * Perfect for platform-agnostic usage with reliable error handling.
+ */
+class DefaultAuthProvider {
+    constructor(projectKey, authApi) {
+        this.projectKey = null;
+        this.authApi = null;
+        this.authType = 'admin';
+        this.projectKey = projectKey || null;
+        this.authApi = authApi || null;
+        this.tokenManager = new TokenManager();
+        const refreshStrategy = new DefaultAuthRefreshStrategy(this.tokenManager, () => Promise.resolve(this.getProviderToken()), this.authApi);
+        this.tokenRefreshManager = new TokenRefreshManager(this.tokenManager, refreshStrategy);
+    }
+    async getToken() {
+        return await this.tokenManager.getAccessToken();
+    }
+    async getProjectKey() {
+        return this.projectKey;
+    }
+    /**
+     * Centralized token refresh handler - delegates to TokenRefreshManager
+     */
+    async onTokenExpired() {
+        await this.tokenRefreshManager.handleTokenExpiration();
+    }
+    /**
+     * Check if an error indicates token expiration (React Native compatible)
+     */
+    isTokenExpiredError(error) {
+        return ErrorUtils.isTokenExpired(error);
+    }
+    /**
+     * Get Firebase or other provider token for fresh JWT request
+     * Type-safe method that uses proper storage keys from AUTH_STORAGE_KEYS
+     */
+    getProviderToken() {
+        if (typeof localStorage !== 'undefined') {
+            return localStorage.getItem(AUTH_STORAGE_KEYS.PROVIDER_TOKEN);
+        }
+        return null;
+    }
+    async setAccessToken(token) {
+        await this.tokenManager.setAccessToken(token);
+    }
+    async setRefreshToken(token) {
+        await this.tokenManager.setRefreshToken(token);
+    }
+    async getRefreshToken() {
+        return await this.tokenManager.getRefreshToken();
+    }
+    async setProviderToken(token) {
+        await this.tokenManager.setProviderToken(token);
+    }
+    async clearProviderToken() {
+        await this.tokenManager.clearProviderToken();
+    }
+    async clearTokens() {
+        await this.tokenManager.clearAllTokens();
+    }
+    hasValidToken() {
+        if (typeof localStorage !== 'undefined') {
+            return !!localStorage.getItem(AUTH_STORAGE_KEYS.ACCESS_TOKEN);
+        }
+        return false;
+    }
+    hasRefreshToken() {
+        if (typeof localStorage !== 'undefined') {
+            return !!localStorage.getItem(AUTH_STORAGE_KEYS.REFRESH_TOKEN);
+        }
+        return false;
+    }
+    /**
+     * Proactively check token expiry and refresh if needed BEFORE making requests
+     * Uses smart refresh strategy based on time remaining:
+     * - >backgroundThreshold seconds: Background refresh (non-blocking)
+     * - <backgroundThreshold seconds: Immediate refresh (blocking)
+     */
+    async ensureValidToken(marginSeconds = 60, backgroundThreshold = 30) {
+        try {
+            const currentToken = await this.getToken();
+            // If no token, nothing to check
+            if (!currentToken) {
+                return;
+            }
+            // Check if token is expired or will expire within margin
+            if (await this.isTokenExpired(marginSeconds)) {
+                // Determine refresh strategy based on time remaining
+                const timeToExpiry = await this.getTokenTimeToExpiry(currentToken);
+                if (timeToExpiry > backgroundThreshold) {
+                    // Token has enough time left - start background refresh (non-blocking)
+                    this.startBackgroundRefresh();
+                }
+                else {
+                    // Token expiring soon or expired - block and refresh immediately
+                    const shouldSkipRefresh = await this.isRefreshTokenExpired(marginSeconds);
+                    if (shouldSkipRefresh) {
+                        // Both tokens expired - use provider token directly
+                        await this.handleExpiredRefreshToken();
+                    }
+                    else {
+                        // Normal refresh with refresh token
+                        if (this.onTokenExpired) {
+                            await this.onTokenExpired();
+                        }
+                    }
+                }
+            }
+        }
+        catch (error) {
+            // If token check/refresh fails, the error will be handled by the calling code
+            throw error;
+        }
+    }
+    /**
+     * Check if current access token is expired
+     */
+    async isTokenExpired(marginSeconds = 60) {
+        try {
+            const currentToken = await this.getToken();
+            if (!currentToken) {
+                return true;
+            }
+            // Import isTokenExpired function here to avoid circular imports
+            const { isTokenExpired } = await Promise.resolve().then(function () { return require('./jwt.function-BYiyl-z_.cjs'); });
+            return isTokenExpired(currentToken, marginSeconds);
+        }
+        catch (error) {
+            return true;
+        }
+    }
+    /**
+     * Check if refresh token is expired
+     */
+    async isRefreshTokenExpired(marginSeconds = 60) {
+        try {
+            const refreshToken = await this.tokenManager.getRefreshToken();
+            if (!refreshToken) {
+                return true; // No refresh token
+            }
+            // Import isTokenExpired function here to avoid circular imports
+            const { isTokenExpired } = await Promise.resolve().then(function () { return require('./jwt.function-BYiyl-z_.cjs'); });
+            return isTokenExpired(refreshToken, marginSeconds);
+        }
+        catch (error) {
+            return true; // Assume expired if we can't check
+        }
+    }
+    /**
+     * Check if both access and refresh tokens are expired
+     */
+    async areAllTokensExpired(marginSeconds = 60) {
+        const accessTokenExpired = await this.isTokenExpired(marginSeconds);
+        const refreshTokenExpired = await this.isRefreshTokenExpired(marginSeconds);
+        return accessTokenExpired && refreshTokenExpired;
+    }
+    /**
+     * Get seconds until token expires
+     */
+    async getTokenTimeToExpiry(token) {
+        try {
+            const { isTokenExpired } = await Promise.resolve().then(function () { return require('./jwt.function-BYiyl-z_.cjs'); });
+            const { jwtDecode } = await import('jwt-decode');
+            const decoded = jwtDecode(token);
+            const currentTime = Math.floor(Date.now() / 1000);
+            return Math.max(0, decoded.exp - currentTime);
+        }
+        catch (error) {
+            return 0; // Assume expired if can't decode
+        }
+    }
+    /**
+     * Start refresh in background without blocking current request
+     */
+    startBackgroundRefresh() {
+        // Use setTimeout to avoid blocking the current request
+        setTimeout(async () => {
+            try {
+                if (this.onTokenExpired) {
+                    await this.onTokenExpired();
+                }
+            }
+            catch (error) {
+                // Background refresh failed - next request will trigger reactive refresh
+            }
+        }, 0);
+    }
+    /**
+     * Handle case where refresh token is also expired - use provider token directly
+     */
+    async handleExpiredRefreshToken() {
+        try {
+            // Get provider token if available
+            const providerToken = this.getProviderToken();
+            if (!providerToken) {
+                // No provider token available - let normal refresh handle the failure
+                if (this.onTokenExpired) {
+                    await this.onTokenExpired();
+                }
+                return;
+            }
+            // Clear expired PERS tokens and use provider token to get fresh ones
+            await this.clearTokens();
+            // Trigger refresh which should now use provider token path
+            if (this.onTokenExpired) {
+                await this.onTokenExpired();
+            }
+        }
+        catch (error) {
+            // If provider token flow fails, let normal refresh handle it
+            if (this.onTokenExpired) {
+                await this.onTokenExpired();
+            }
+        }
+    }
+}
+
+// packages/pers-sdk/src/core/pers-api-client.ts
+/**
+ * PERS API Client - Core platform-agnostic client for PERS backend
+ *
+ * Provides authenticated HTTP client with automatic token management,
+ * proactive refresh, and comprehensive error handling.
+ *
+ * Features:
+ * - Automatic token refresh before expiry
+ * - Background refresh for optimal performance
+ * - Provider token fallback for seamless authentication
+ * - Configurable retry and timeout settings
+ * - Platform-agnostic design
+ *
+ * @example
+ * ```typescript
+ * const client = new PersApiClient(httpClient, {
+ *   environment: 'production',
+ *   apiProjectKey: 'your-project-key',
+ *   authProvider: createAuthProvider({
+ *     tokenProvider: () => getFirebaseToken()
+ *   })
+ * });
+ *
+ * // Make authenticated requests
+ * const data = await client.get('/users/me');
+ * ```
+ */
+class PersApiClient {
+    /**
+     * Creates a new PERS API Client instance
+     *
+     * @param httpClient - Platform-specific HTTP client implementation
+     * @param config - Configuration options for the API client
+     */
+    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);
+        // Initialize auth services for direct authentication
+        this.authApi = new AuthApi(this);
+        // Auto-create auth provider if none provided
+        if (!this.mergedConfig.authProvider) {
+            this.mergedConfig.authProvider = new DefaultAuthProvider(this.mergedConfig.apiProjectKey, this.authApi);
+        }
+        this.authService = new AuthService(this.authApi, this.mergedConfig.authProvider);
+    }
+    /**
+     * Ensures valid authentication token before making requests
+     *
+     * Implements intelligent refresh strategy:
+     * - Tokens with sufficient time remaining: Background refresh (non-blocking)
+     * - Tokens expiring soon or expired: Immediate refresh (blocking)
+     *
+     * @private
+     * @returns Promise that resolves when token validation is complete
+     */
+    async ensureValidToken() {
+        if (!this.mergedConfig.authProvider?.ensureValidToken) {
+            return; // Auth provider doesn't support proactive validation
+        }
+        try {
+            const refreshMargin = this.mergedConfig.tokenRefreshMargin || 60;
+            const backgroundThreshold = this.mergedConfig.backgroundRefreshThreshold || 30;
+            await this.mergedConfig.authProvider.ensureValidToken(refreshMargin, backgroundThreshold);
+        }
+        catch (error) {
+            // If token check/refresh fails, continue with request
+            // The reactive error handling will catch any auth issues
+        }
+    }
+    /**
+     * 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', bypassAuth = false } = options || {};
+        const url = `${this.apiRoot}${endpoint}`;
+        // Proactive token expiry check and refresh BEFORE making the request
+        if (!bypassAuth && this.mergedConfig.authProvider && retryCount === 0) {
+            await this.ensureValidToken();
+        }
+        const requestOptions = {
+            headers: bypassAuth ? await this.getHeadersWithoutAuth() : await this.getHeaders(),
+            timeout: this.mergedConfig.timeout,
+            responseType
+        };
+        // Log API request with auth info
+        // const hasAuth = !!this.mergedConfig.authProvider;
+        endpoint.includes('/export/csv');
+        try {
+            let result;
+            switch (method) {
+                case AUTH_METHODS.GET:
+                    result = await this.httpClient.get(url, requestOptions);
+                    break;
+                case AUTH_METHODS.POST:
+                    result = await this.httpClient.post(url, body, requestOptions);
+                    break;
+                case AUTH_METHODS.PUT:
+                    result = await this.httpClient.put(url, body, requestOptions);
+                    break;
+                case AUTH_METHODS.DELETE:
+                    result = await this.httpClient.delete(url, requestOptions);
+                    break;
+                default:
+                    throw new Error(`Unsupported HTTP method: ${method}`);
+            }
+            return result;
+        }
+        catch (error) {
+            // Error handling - proactive token refresh should prevent most 401s
+            const status = ErrorUtils.getStatus(error);
+            const errorMessage = ErrorUtils.getMessage(error);
+            // Fallback: reactive token refresh only if proactive check missed something
+            if (retryCount === 0 && this.mergedConfig.authProvider && ErrorUtils.isTokenExpired(error)) {
+                try {
+                    // Fallback token refresh delegation
+                    const result = await this.handleTokenRefreshDelegation(method, endpoint, body, options);
+                    if (result !== null) {
+                        return result;
+                    }
+                }
+                catch (refreshError) {
+                    throw new PersApiError(`Auth failed: ${refreshError.message || refreshError}`, endpoint, method, 401);
+                }
+            }
+            throw new PersApiError(errorMessage, endpoint, method, status || undefined, ErrorUtils.isRetryable(error));
+        }
+    }
+    /**
+     * Delegate token refresh to auth provider and handle the results
+     */
+    async handleTokenRefreshDelegation(method, endpoint, body, options) {
+        try {
+            // Let auth provider handle the refresh process
+            const authProvider = this.mergedConfig.authProvider;
+            if (authProvider?.onTokenExpired) {
+                await authProvider.onTokenExpired();
+            }
+            // If we get here, tokens should be refreshed - retry the request
+            // Auth provider refresh succeeded, retrying...
+            return this.request(method, endpoint, body, { ...options, retryCount: 1 });
+        }
+        catch (refreshError) {
+            // Auth provider handled all refresh attempts and failed
+            // Re-throw the error for the caller to handle
+            throw refreshError;
+        }
+    }
+    /**
+     * Performs an authenticated GET request
+     *
+     * @template T - Expected response type
+     * @param endpoint - API endpoint path (without base URL)
+     * @param responseType - Expected response format
+     * @returns Promise resolving to typed response data
+     *
+     * @example
+     * ```typescript
+     * const user = await client.get<User>('/users/123');
+     * const csvData = await client.get('/export/data', 'blob');
+     * ```
+     */
+    async get(endpoint, responseType) {
+        return this.request(AUTH_METHODS.GET, endpoint, undefined, { responseType });
+    }
+    /**
+     * Performs an authenticated POST request
+     *
+     * @template T - Expected response type
+     * @param endpoint - API endpoint path (without base URL)
+     * @param body - Request payload data
+     * @param options - Request options including auth bypass
+     * @returns Promise resolving to typed response data
+     *
+     * @example
+     * ```typescript
+     * const user = await client.post<User>('/users', userData);
+     * const publicData = await client.post('/public/contact', formData, { bypassAuth: true });
+     * ```
+     */
+    async post(endpoint, body, options) {
+        return this.request(AUTH_METHODS.POST, endpoint, body, options);
+    }
+    /**
+     * Generic PUT request
+     */
+    async put(endpoint, body) {
+        return this.request(AUTH_METHODS.PUT, endpoint, body);
+    }
+    /**
+     * Generic DELETE request
+     */
+    async delete(endpoint) {
+        return this.request(AUTH_METHODS.DELETE, endpoint);
+    }
+    /**
+   * Get request headers WITHOUT auth token (for auth operations like refresh/login)
+   */
+    async getHeadersWithoutAuth() {
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        // Add project key only (no auth token)
+        if (this.mergedConfig.authProvider) {
+            const projectKey = await this.mergedConfig.authProvider.getProjectKey();
+            if (projectKey) {
+                headers['x-project-key'] = projectKey;
+            }
+        }
+        else if (this.mergedConfig.apiProjectKey) {
+            headers['x-project-key'] = this.mergedConfig.apiProjectKey;
+        }
+        return headers;
+    }
+    // ==========================================
+    // AUTHENTICATION METHODS
+    // ==========================================
+    /**
+     * Authenticates an admin user using external JWT token
+     *
+     * Exchanges external provider token (Firebase, Auth0, etc.) for PERS access tokens.
+     * Automatically stores received tokens for subsequent requests.
+     *
+     * @param externalJwt - JWT token from external authentication provider
+     * @returns Promise resolving to session context with admin permissions
+     *
+     * @example
+     * ```typescript
+     * const firebaseToken = await getIdToken();
+     * const session = await client.loginAdmin(firebaseToken);
+     * console.log('Admin authenticated:', session.user.email);
+     * ```
+     */
+    async loginAdmin(externalJwt) {
+        return this.authService.loginTenantAdmin(externalJwt);
+    }
+    /**
+     * Authenticates a regular user using external JWT token
+     *
+     * Exchanges external provider token for PERS access tokens with user-level permissions.
+     * Automatically stores received tokens for subsequent requests.
+     *
+     * @param externalJwt - JWT token from external authentication provider
+     * @returns Promise resolving to session context with user permissions
+     *
+     * @example
+     * ```typescript
+     * const firebaseToken = await getIdToken();
+     * const session = await client.loginUser(firebaseToken);
+     * console.log('User authenticated:', session.user.email);
+     * ```
+     */
+    async loginUser(externalJwt) {
+        return this.authService.loginUser(externalJwt);
+    }
+    /**
+     * Refresh access token using stored refresh token
+     */
+    /* private async refreshToken(): Promise<SessionAuthResponseDTO> {
+      const refreshToken = await this.mergedConfig.authProvider?.getRefreshToken?.();
+      if (!refreshToken) {
+        throw new Error('No refresh token available');
+      }
+      return this.authService.refreshAccessToken(refreshToken);
+    } */
+    /**
+     * Clear all stored authentication tokens
+     */
+    /* private async clearAuth(): Promise<void> {
+      return this.authService.clearTokens();
+    } */
+    /**
+     * Checks if current user has a valid authentication token
+     *
+     * Performs basic token availability check without network requests.
+     * For comprehensive validation including expiry, use isTokenExpired().
+     *
+     * @returns True if valid token exists, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (client.hasValidAuth()) {
+     *   // User is authenticated, proceed with API calls
+     *   const data = await client.get('/protected-data');
+     * } else {
+     *   // Redirect to login
+     *   redirectToLogin();
+     * }
+     * ```
+     */
+    hasValidAuth() {
+        return this.mergedConfig.authProvider?.hasValidToken?.() || false;
+    }
+    /**
+     * Checks if current access token is expired or expiring soon
+     *
+     * @param marginSeconds - Seconds before expiry to consider token as expired (default: 60)
+     * @returns Promise resolving to true if token is expired/expiring, false if valid
+     *
+     * @example
+     * ```typescript
+     * if (await client.isTokenExpired(120)) {
+     *   console.log('Token expires within 2 minutes');
+     *   // Optionally trigger manual refresh
+     * }
+     * ```
+     */
+    async isTokenExpired(marginSeconds = 60) {
+        if (!this.mergedConfig.authProvider?.isTokenExpired) {
+            return true; // No auth provider or doesn't support expiry checking
+        }
+        try {
+            return await this.mergedConfig.authProvider.isTokenExpired(marginSeconds);
+        }
+        catch (error) {
+            return true;
+        }
+    }
+    /**
+     * Checks if both access and refresh tokens are expired
+     *
+     * Useful for determining if full re-authentication is required.
+     *
+     * @param marginSeconds - Seconds before expiry to consider tokens as expired (default: 60)
+     * @returns Promise resolving to true if both tokens expired, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (await client.areAllTokensExpired()) {
+     *   // Full re-authentication required
+     *   await redirectToLogin();
+     * }
+     * ```
+     */
+    async areAllTokensExpired(marginSeconds = 60) {
+        if (!this.mergedConfig.authProvider?.areAllTokensExpired) {
+            // Fallback to checking access token only
+            return await this.isTokenExpired(marginSeconds);
+        }
+        return await this.mergedConfig.authProvider.areAllTokensExpired(marginSeconds);
+    }
+    /**
+     * Get current configuration (returns merged config)
+     */
+    getConfig() {
+        return this.mergedConfig;
+    }
+    /**
+     * Get original user configuration
+     */
+    getOriginalConfig() {
+        return this.config;
+    }
+}
+
+/**
+ * PERS SDK - Platform-agnostic TypeScript SDK for PERS API
+ *
+ * Provides a simple wrapper around the core API client with
+ * intelligent authentication and token management.
+ */
+/**
+ * Main PERS SDK class
+ *
+ * Minimal wrapper around PersApiClient providing a clean interface
+ * for platform-specific implementations.
+ *
+ * @example
+ * ```typescript
+ * import { createPersSDK, createAuthProvider } from '@explorins/pers-sdk/core';
+ * import { BrowserHttpClient } from '@explorins/pers-sdk/browser';
+ *
+ * const authProvider = createAuthProvider({
+ *   tokenProvider: () => getFirebaseToken()
+ * });
+ *
+ * const sdk = new PersSDK(new BrowserHttpClient(), {
+ *   environment: 'production',
+ *   apiProjectKey: 'your-project-key',
+ *   authProvider
+ * });
+ *
+ * const apiClient = sdk.api();
+ * const user = await apiClient.get('/users/me');
+ * ```
+ */
+class PersSDK {
+    /**
+     * Creates a new PERS SDK instance
+     *
+     * @param httpClient Platform-specific HTTP client implementation
+     * @param config SDK configuration options
+     */
+    constructor(httpClient, config) {
+        this.apiClient = new PersApiClient(httpClient, config);
+    }
+    /**
+     * Gets the API client for making PERS API requests
+     *
+     * This is the main interface for interacting with the PERS backend.
+     * The returned client handles authentication, token refresh, and error handling automatically.
+     *
+     * @returns Configured PersApiClient instance
+     *
+     * @example
+     * ```typescript
+     * const apiClient = sdk.api();
+     * const user = await apiClient.get<User>('/users/me');
+     * await apiClient.post('/users', userData);
+     * ```
+     */
+    api() {
+        return this.apiClient;
+    }
+    /**
+     * Checks if SDK is configured for production environment
+     *
+     * @returns True if environment is 'production', false otherwise
+     */
+    isProduction() {
+        return this.apiClient.getConfig().environment === 'production';
+    }
+}
+/**
+ * Simple factory function
+ */
+function createPersSDK(httpClient, config) {
+    return new PersSDK(httpClient, config);
+}
+
+exports.DEFAULT_PERS_CONFIG = DEFAULT_PERS_CONFIG;
+exports.PersApiClient = PersApiClient;
+exports.PersSDK = PersSDK;
+exports.buildApiRoot = buildApiRoot;
+exports.createPersSDK = createPersSDK;
+exports.mergeWithDefaults = mergeWithDefaults;
+//# sourceMappingURL=pers-sdk-_1sTi9x9.cjs.map